Este repositório é um portal que exibe estudantes, professores e colaboradores do IFPB juntamente com seus projetos acadêmicos e de pesquisa. O objetivo é criar um catálogo colaborativo dos trabalhos desenvolvidos na instituição.

🌟 Portal disponível em: https://ifpb.github.io/projects/

• 🚀 Tecnologias
• 📝 Como Contribuir
• 👤 Cadastro de Pessoas
  • 🏷️ Campos Obrigatórios
  • 📸 Avatar
  • 🏫 Códigos de Cursos e Campus
  • 📋 Campos Opcionais
  • 👔 Múltiplas Ocupações
• 📦 Cadastro de Projetos
  • 🗂️ Tipos de Projetos
  • 🔗 Endereços do Projeto
  • 📝 Campos com Múltiplos Valores
  • 🏷️ Tags
  • 👥 Colaboradores
• ✨ Boas Práticas para um Projeto de Excelência
  • 📖 README do Projeto
  • 🔄 Automação com GitHub Actions
  • 📊 GitHub Projects (Kanban)
  • 🎯 Outras Boas Práticas
  • 🏆 Exemplos de Projetos Exemplares
• 🤝 Contribuições
  • 1. Fork e Clone
  • 2. Atualize seu Fork (se já existir)
  • 3. Adicione seus Arquivos
  • 4. Teste Localmente
  • 5. Commit e Push
  • 6. Crie o Pull Request
  • 📝 Convenções de Commit
• 🛠️ Desenvolvimento
  • Comandos Disponíveis
  • Estrutura do Projeto
• 📊 Dados Atuais
• 📄 Licença

• Astro.js v4.15.4 - Framework web moderno para sites rápidos
• React v18.2.0 - Componentes interativos
• Tailwind CSS v3.3.1 - Framework CSS utilitário
• Pagefind v1.1.1 - Busca estática rápida
• TypeScript - Tipagem estática
• Zod - Validação de esquemas
• YAML - Formato de dados estruturados

Você pode contribuir adicionando seus dados pessoais, projetos ou atualizando informações existentes através de Pull Requests (PRs). Este documento orienta como fazer o cadastro de pessoas e projetos.

Para se cadastrar, adicione um arquivo seguindo o formato nome-sobrenome-id.yml no diretório src/content/people/. O nome do arquivo deve usar apenas letras minúsculas, hífens e sua matrícula/ID.

name:
 compact: Luiz Chaves
 full: Luiz Carlos Rodrigues Chaves
avatar:
 github: https://github.com/luizchaves.png
occupations:
 - id: 20051370420
 type: student
 course: cstsi-jp # curso-campus (formato unificado)
 isFinished: true # true se já concluiu, false se ainda está cursando
addresses:
 github: https://github.com/luizchaves
 linkedin: https://www.linkedin.com/in/luizcarloschaves/
 instagram: https://www.instagram.com/luizcrchaves/
 bluesky: https://bsky.app/profile/luizcarloschaves.bsky.social
 homepage: https://luizchaves.github.io
 email: luiz.chaves@ifpb.edu.br

Segundo o esquema de validação definido com Zod, os seguintes campos são obrigatórios:

Para todos os tipos:

• name.compact - Nome resumido para exibição
• name.full - Nome completo
• avatar.github - URL da imagem do GitHub (formato: https://github.com/username.png)
• occupations[].id - Matrícula ou ID único
• occupations[].type - Tipo: student, professor, collaborator
• addresses.github - Perfil no GitHub

Para estudantes:

• occupations[].course - Código do curso + campus (ex: cstsi-jp, csbes-jp)

Para professores e colaboradores:

• occupations[].campus - Campus de atuação (ex: ifpb-jp)

A imagem de avatar deve ser do seu perfil do GitHub. Por exemplo:

• Perfil: https://github.com/luizchaves
• Avatar: https://github.com/luizchaves.png

• Cursos: cstsi (TSI), cstrc (Redes), csbes (Engenharia de Software), etc.
• Campus: jp (João Pessoa), cz (Cabedelo), cg (Campina Grande), etc.
• Formato curso: {codigo-curso}-{campus} (ex: cstsi-jp)

Você pode adicionar outros endereços sociais e profissionais:

• addresses.linkedin
• addresses.instagram
• addresses.homepage
• addresses.lattes
• addresses.researchgate
• addresses.orcid
• addresses.bluesky
• addresses.twitter
• addresses.email

Pessoas podem ter múltiplas ocupações (ex: estudante e professor, múltiplos cursos):

# Estudante de múltiplos cursos
occupations:
 - id: 20051370420
 type: student
 course: cstsi-jp
 isFinished: true
 - id: 20221370025
 type: student
 course: csbes-jp
 isFinished: false
# Estudante que virou professor
occupations:
 - id: 20051370420
 type: student
 course: cstsi-jp
 isFinished: true
 - id: 2680962
 type: professor
 campus: ifpb-jp
# Apenas professor
occupations:
 - id: 2680962
 type: professor
 campus: ifpb-jp

Para cadastrar um projeto, adicione um arquivo seguindo o formato titulo-do-projeto.yml no diretório src/content/projects/.

name: IFPB Projects
description:
 Este portal tem como objetivo listar projetos construídos pelos
 estudantes, professores e colaboradores do IFPB.
addresses:
 preview: https://github.com/ifpb/projects/blob/main/preview.png?raw=true
 homepage: https://ifpb.github.io/projects/
 repository: https://github.com/ifpb/projects
 design: https://www.figma.com/design/example # figma, canva, etc.
category:
 type: subject # ou 'subject', 'research', 'extension', 'open source'
 subject: pw2-csbes-jp
 period: 2025.1 # necessário para projetos de disciplina
tags:
 - javascript
 - astro.js
 - typescript
owners:
 - 20051370420 # matrícula/ID dos colaboradores
 - 2680962

1. Projeto de Disciplina (subject)

   • Requer: category.subject, category.period
   • Disciplina única: category: { type: subject, subject: "dw-cstrc-jp", period: "2024.1" }
   • Múltiplas disciplinas: category: { type: subject, subject: ["dw-cstrc-jp", "pw2-cstrc-jp"], period: "2024.1" }

2. Projeto de Pesquisa (research)

   • Requer: category.campus
   • Exemplo: category: { type: research, campus: "ifpb-jp" }

3. Projeto de Extensão (extension)

   • Requer: category.campus
   • Exemplo: category: { type: extension, campus: "ifpb-jp" }

4. Projeto Open Source (open source)

   • Requer: category.campus
   • Exemplo: category: { type: "open source", campus: "ifpb-jp" }

• addresses.repository (obrigatório) - Repositório(s) no GitHub
  • Pode ser um único repositório: repository: "https://github.com/user/repo"
  • Ou múltiplos repositórios: repository: ["https://github.com/user/frontend", "https://github.com/user/backend"]
• addresses.preview (obrigatório) - Imagem de preview (500x262px recomendado)
• addresses.homepage (opcional) - Site/demo do projeto
• addresses.design (opcional) - Link do design/protótipo (Figma, etc.)
• addresses.workflow (opcional) - Link público para documentação do processo de desenvolvimento, metodologia ou fluxo de trabalho (ex: documentos sobre metodologia ágil, processo de desenvolvimento, pipeline CI/CD, etc.)

Exemplos de projetos com design e workflow:

• Projetos com design - Veja exemplos de projetos que incluem links para protótipos e designs
• Projetos com workflow - Veja exemplos de projetos que documentam seus processos de desenvolvimento

Alguns campos suportam múltiplos valores quando aplicável:

Para projetos que envolvem múltiplas disciplinas:

# Disciplina única
category:
 type: subject
 subject: pw2-csbes-jp
 period: 2025.1
# Múltiplas disciplinas
category:
 type: subject
 subject:
 - pw2-csbes-jp # Programação Web 2
 - dw-csbes-jp # Desenvolvimento Web
 period: 2025.1

Para projetos com múltiplos repositórios (frontend/backend, monorepos, etc.):

# Repositório único
addresses:
 repository: https://github.com/user/meu-projeto
# Múltiplos repositórios
addresses:
 repository:
 - https://github.com/user/frontend
 - https://github.com/user/backend
 - https://github.com/user/mobile

Use tags descritivas das tecnologias, frameworks e conceitos utilizados:

• Linguagens: javascript, python, java, kotlin
• Frameworks: react, vue.js, spring boot, flutter
• Ferramentas: docker, git, figma
• Conceitos: machine learning, mobile, web, api
• Tipos de projeto: e-commerce, blog, portfolio, chatbot

No campo owners, liste as matrículas/IDs de todos os colaboradores do projeto. Certifique-se de que cada pessoa esteja cadastrada no diretório src/content/people/.

Para criar um projeto que se destaque e sirva de referência, siga estas orientações:

Todo projeto deve ter um README.md bem estruturado com:

# Nome do Projeto
## 📋 Descrição
Descreva claramente o que o projeto faz, seus objetivos e contexto acadêmico.
## ✨ Funcionalidades
- Lista das principais funcionalidades
- Features implementadas
- Diferenciais do projeto
## 🛠️ Tecnologias Utilizadas
- Frontend: React, Vue.js, Vanilla JS...
- Backend: Node.js, Spring Boot, Django...
- Database: PostgreSQL, MySQL, MongoDB...
- Deploy: Vercel, Netlify, Heroku...
## 🚀 Como Executar
### Pré-requisitos
- Node.js 18+
- NPM ou Yarn
- Outras dependências específicas
### Instalação
1. Clone o repositório
 git clone https://github.com/usuario/projeto.git
2. Instale as dependências
 npm install
3. Configure as variáveis de ambiente
 cp .env.example .env
4. Execute o projeto
 npm run dev
## 📱 Demo
- [🌐 Site Online](https://seu-projeto.vercel.app)
- [🎨 Design no Figma](https://figma.com/design/...)
- [📊 Apresentação](https://slides.com/...)
## 🧪 Testes
Instrua como executar os testes:
npm test
npm run test:e2e
## 📂 Estrutura do Projeto
src/
├── components/ # Componentes reutilizáveis
├── pages/ # Páginas da aplicação
├── services/ # Integração com APIs
├── utils/ # Funções utilitárias
└── styles/ # Estilos globais
## 👥 Autores
- **Seu Nome** - Desenvolvimento Full Stack - [@seuuser](https://github.com/seuuser)
- **Colega** - Frontend - [@colega](https://github.com/colega)
## 📄 Licença
Este projeto está sob licença [MIT](LICENSE).

Configure workflows automáticos para melhorar a qualidade do código:

name: CI/CD Pipeline
on:
 push:
 branches: [main, develop]
 pull_request:
 branches: [main]
jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: '18'
 cache: 'npm'
 - run: npm ci
 - run: npm run lint
 - run: npm test
 - run: npm run build
 deploy:
 needs: test
 runs-on: ubuntu-latest
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: '18'
 - run: npm ci
 - run: npm run build
 - name: Deploy to Vercel
 uses: amondnet/vercel-action@v25
 with:
 vercel-token: ${{ secrets.VERCEL_TOKEN }}
 vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
 vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}

• Code Quality: ESLint, Prettier, TypeScript checking
• Security: Dependabot, CodeQL analysis
• Performance: Lighthouse CI, Bundle analyzer
• Documentation: Auto-generate docs, deploy Storybook

Organize o desenvolvimento com um quadro Kanban:

1. Acesse GitHub Projects no seu repositório

2. Crie um novo projeto com template "Team Planning"

3. Configure colunas:

   • 📋 Backlog - Ideias e funcionalidades futuras
   • 🔄 To Do - Tarefas prontas para desenvolvimento
   • 👷 In Progress - Em desenvolvimento
   • 👀 In Review - Aguardando revisão
   • ✅ Done - Concluído
   • 🚀 Released - Em produção

4. Crie issues detalhadas com:

   • Labels apropriadas (bug, feature, enhancement)
   • Assignees responsáveis
   • Milestones para organizar releases
   • Templates para padronizar reports

Use Conventional Commits para histórico organizado:

• feat: adicionar autenticação com Google
• fix: corrigir erro de validação no formulário
• docs: atualizar documentação da API
• style: ajustar responsividade do header
• refactor: otimizar queries do banco de dados
• test: adicionar testes para componente Login

• LICENSE - Licença do projeto (MIT, Apache, etc.)
• .gitignore - Arquivos ignorados pelo Git
• package.json - Dependências e scripts bem configurados
• .env.example - Exemplo de variáveis de ambiente
• CONTRIBUTING.md - Guia para contribuidores
• CHANGELOG.md - Histórico de mudanças

• Linting: ESLint, Prettier para código limpo
• Testes: Jest, Vitest, Cypress para qualidade
• Types: TypeScript para tipagem estática
• Performance: Otimização de imagens, lazy loading
• Acessibilidade: Semantic HTML, ARIA labels

• Hosting: Vercel, Netlify, GitHub Pages
• Domain: Domínio personalizado quando possível
• Analytics: Google Analytics, Plausible
• Monitoring: Sentry para error tracking
• Performance: PageSpeed Insights, Core Web Vitals

• Wiki: Documentação técnica detalhada
• Storybook: Para componentes (se aplicável)
• OpenAPI: Para APIs REST
• Diagramas: Arquitetura, fluxos, banco de dados

Confira projetos do portal que seguem essas boas práticas:

• Projetos de disciplina
• Projetos de pesquisa
• Projetos de extensão
• Projetos com homepage
• Projetos open source

Um projeto bem estruturado não apenas demonstra conhecimento técnico, mas também profissionalismo e atenção aos detalhes que são muito valorizados no mercado de trabalho!

Contribuições são muito bem-vindas! Você pode:

• ✅ Adicionar seus dados pessoais e projetos
• ✅ Corrigir informações incorretas
• ✅ Melhorar a documentação
• ✅ Reportar bugs ou sugerir melhorias
• ✅ Contribuir com código (componentes, features, etc.)

Todas as contribuições para este projeto são realizadas através de Pull Requests (PRs). Este processo garante qualidade, permite revisão colaborativa e mantém o histórico organizado. Siga o passo a passo abaixo para contribuir de forma efetiva:

1. Fork este repositório (ifpb/projects → seu-username/projects)

2. Clone seu fork localmente:

   git clone https://github.com/seu-username/projects.git
   cd projects

3. Configure o upstream para manter seu fork atualizado:

   git remote add upstream https://github.com/ifpb/projects.git

Antes de fazer mudanças, sempre sincronize com o repositório original:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

• Adicione seu arquivo de pessoa em src/content/people/
• Adicione seus projetos em src/content/projects/
• Siga os exemplos e formatos descritos nas seções anteriores

Antes de enviar o PR, teste suas mudanças localmente:

# Instale as dependências
npm install
# Construa o projeto (verifica se não há erros)
npm run build
# Visualize o resultado
npm run preview

Se não houver erros, abra o navegador no endereço sugerido pelo terminal para ver como ficaram seus dados.

# Adicione os arquivos
git add .
# Faça o commit com uma mensagem descritiva
git commit -m "content: Adicionando [Seu Nome] e projeto [Nome do Projeto]"
# Envie para seu fork
git push origin main

1. Acesse seu fork no GitHub
2. Clique em "New Pull Request"
3. Preencha título e descrição explicando as mudanças
4. Envie o PR e aguarde a revisão

Use prefixos descritivos nas mensagens de commit:

Conteúdo:

• content: Adicionando pessoa [Nome]
• content: Adicionando projeto [Nome do Projeto]
• content: Atualizando informações de [Nome]
• content: Removendo pessoa/projeto [Nome]

Correções:

• fix: Corrigindo erro em [arquivo]
• fix: Corrigindo links quebrados
• fix: Ajustando validação de esquema

Funcionalidades:

• feat: Adicionando novo componente [nome]
• feat: Implementando busca avançada
• feat: Adicionando filtro por [critério]

Melhorias:

• refactor: Otimizando performance da página
• refactor: Melhorando acessibilidade
• refactor: Aprimorando UX do componente

Configuração:

• config: Atualizando dependências
• config: Configurando novo build script
• config: Ajustando configurações do Astro

Documentação:

• docs: Atualizando README com [informação]
• docs: Adicionando guia de [tópico]
• docs: Corrigindo documentação de [seção]

Estilos:

• style: Ajustando layout da página
• style: Melhorando responsividade
• style: Padronizando componentes

# Desenvolvimento com hot-reload
npm run dev
# Build para produção
npm run build
# Preview da build
npm run preview
# Build + Preview
npm run buildpreview
# Build + Pagefind + Preview (com busca)
npm run buildpreviewpf
# Carregar avatars do GitHub
npm run load:github:avatar

src/
├── content/ # Dados em YAML
│ ├── people/ # Pessoas (estudantes, professores)
│ ├── projects/ # Projetos
│ ├── courses/ # Cursos do IFPB
│ ├── subjects/ # Disciplinas
│ └── config.ts # Esquemas de validação
├── components/ # Componentes React/Astro
├── helpers/ # Funções utilitárias
├── layouts/ # Layouts das páginas
├── pages/ # Rotas do site
└── styles/ # Estilos globais

O portal atualmente indexa:

• Pessoas (estudantes, professores, colaboradores)
• Projetos de diferentes categorias
• Busca rápida com Pagefind
• Filtros avançados por curso, campus, tecnologia
• Geração estática para performance máxima

Este projeto é open source. Veja o arquivo de licença para mais detalhes.

💡 Gostou da ideia? Compartilhe com seus colegas e professores! Vamos construir juntos o maior catálogo de projetos do IFPB! 🚀