DevOps ‐ Documentation - QuantumBitBR/API_5SEM GitHub Wiki
Padrão de Documentação - Equipe QuantumBitBR
Introdução
Este documento define o padrão de documentação utilizado pela Equipe QuantumBitBR no GitHub Wiki, com o objetivo de garantir consistência, clareza e facilidade de manutenção.
A documentação do projeto será feita no GitWiki descrevendo todo o processo de desenvolvimento do produto usando o SCRUM, divido em paginas dentro da GitWiki. Cada página do Wiki será focada em um tópico específico, conforme descrito nas próximas seções do documento.
A documentação abrange todo o ciclo do projeto: o que será feito, como será feito, quais tecnologias e processos serão utilizados.
Estrutura Geral
1º Seção: DevOps
Foco: Processos, ferramentas e decisões técnicas.
Esta seção será dedicada à documentação relacionada à implementação de práticas DevOps pela equipe, cada membro dentro da equipe QuantumBitBr tem sua responsabilidade no DevOps e terá uma pagina dedicada para sua parte da implementação mostrando como será feito esse processo dentro da equipe.
Divisão da Pagina:
-
Visão Geral
-
Objetivo: Explicar o conceito da prática de DevOps e quais seriam as qualidade e importâncias da implementação desse processo dentro da equipe (ex: CI/CD, IaC, Testes Automatizados).
-
Relevância para o projeto: Descrever a importância e impacto da prática no contexto do projeto, como quais foram os pros e contras da implementação dentro da equipe, também descrever quais foram as dificuldades e problemas, caso houver, dentro do processo.
-
-
Implementação
-
O que foi feito: Explicação de como foi feito a implementação dentro do grupo junto de uma explicação básica e breve de como é a implementação técnica dentro do processo da equipe(ex: arquivos
.yml, scripts Terraform). -
Desafios e soluções: Problemas enfrentados e como foram resolvidos.
Exemplo:
A configuração inicial do GitHub Actions falhava devido a permissões inadequadas no IAM da AWS. Ajustamos as permissões e adicionamos um role com escopo reduzido.
-
-
Justificativas
-
Tecnologias Escolhidas: Comparativo breve entre tecnologias alternativas, quais as diferenças entre elas.
Exemplo:
GitHub Actions foi preferido ao Jenkins por sua integração nativa com o GitHub e menor overhead de manutenção.
-
Decisões de Arquitetura: Justificativas técnicas das escolhas feitas.
Exemplo:Optamos por containers Docker para uniformizar ambientes de desenvolvimento e produção.
-
2º Seção: Produto & Desenvolvimento
Foco: Regras do time e detalhes técnicos do produto, como padrões e fluxos de braches para que todo o projeto tenha um padrão e possa ser seguido e visualizado sem problemas por toda a equipe.
Páginas da seção:
-
Regras de Desenvolvimento
- Padrões de Código: Convenções adotadas por toda a equipe de desenvolvimento(ex: padrão de commits, nomenclaturas).
- Fluxo de Branches: Diagrama do fluxo de trabalho das branches com Mermaid, são exemplos de como uma equipe pode separar a branches e fazer suas atividades individuas e depois implementa-las ao projeto sem problemas.
graph TD Dev -->|merge| Main Feature --> Dev Hotfix --> Main
-
Solução do Produto
-
Visão geral do problema e solução encontrada.
- Contexto do Problema: Descreva em 2-3 linhas o cenário onde o problema ocorre e quem é afetado.
- Problema: Especifique de forma clara qual é o desafio enfrentado ou a falha existente.
- Objetivo da Solução: Explique o que a equipe pretende resolver com o projeto.
- Solução Proposta: Resuma como a solução foi implementada (tecnologias, arquitetura, diferencial).
- Benefícios Esperados: Liste rapidamente os impactos positivos da solução (ex: mais desempenho, menos falhas).
-
3º Seção Entregas do Produto
Descrição: Esta seção tem como objetivo documentar as entregas que representaram marcos significativos(versões do projeto) ou que são entregas cruciais para o projeto. O foco é apresentar um resumo claro dos resultados mais impactantes e dos desafios superados em momentos estratégicos. Podendo ser dividida cada pagina de entregas sendo um período do projeto como semestral, trimestral ou mensal.
A página principal no GitWiki será um catálogo dessas entregas durante esse período escolhido pela equipe, utilizando âncoras internas para os detalhes, mantendo tudo em uma única página, mas com foco no que realmente importa.
Template ilustrativo de como seria cada pagina de entregas:
- 1º Semestre de 2025
| Marco/Sprint | Período | Objetivo Principal | Entregas Chave (Principais) |
| -------------------------------------- | ------------- | --------------------------------------- | ------------------------------------------------- |
| [Sprint 3 - MVP do Módulo X](#sprint3) | 01/04 - 15/04 | Lançamento do Produto Mínimo Viável(MVP)| US-02 (Funcionalidade X), US-02(Integração Y)
| [Sprint 8 - Kubernetes](#sprint8) | 01/04 - 15/04 | Lançamento do Produto Mínimo Viável | US-05 (Funcionalidade X), US-06(Integração Y)
<a id="sprint3"></a>
## Sprint 3 - Lançamento do MVP do Módulo X
**Período:** 01/04 - 15/04
**Objetivo:** Lançamento do Produto Mínimo Viável (MVP) do Módulo X para testes iniciais com usuários.
### Entregas
- **US-05:** Implementação da funcionalidade principal do Módulo X [(#commit123)](link_para_commit_ou_PR)
- **US-06:** Integração com o serviço de autenticação Y [(#commit456)](link_para_commit_ou_PR)
- **Bugfix:** Resolução de problemas críticos de cadastro de usuário.
### Burndown
### Desafios e Soluções
- **Desafio:** Atraso na entrega de uma API externa essencial para a funcionalidade principal.
- **Solução:** Implementamos um *mock* da API para permitir o desenvolvimento paralelo e garantir o progresso da sprint.
---
<a id="sprint8"></a>
## Sprint 8 - Migração para Kubernetes
**Período:** 10/04 - 24/04
**Objetivo:** Substituir deployment monolítico por clusters Kubernetes.
### Entregas
- **US-22:** Configuração do EKS [(#commit123)](link)
- **US-23:** Autoscaling horizontal
### Burndown
### Desafios
- Problemas com persistent storage (resolvido com EBS)