Conventional Commits (components)

Utilize as abas abaixo para consultar cada tipo de commit, sua finalidade, exemplos de uso em laboratório e os comandos correspondentes.

feat

feat — Nova funcionalidade

Quando usar: Adicionar uma nova funcionalidade ao firmware.

Contexto de laboratório: Implementar leitura de sensor, controle de atuador, conexão Wi-Fi, etc.

Exemplos

git commit -m "feat(sensor): adiciona leitura do DHT22 com média móvel"

git commit -m "feat(wifi): configura conexão automática ao Wi-Fi da sala

Usa credenciais definidas em platformio.ini e tenta
reconexão a cada 10 segundos em caso de falha."

git commit -m "feat(display): implementa tela de status no OLED"

fix

fix — Correção de bug

Quando usar: Corrigir um comportamento incorreto ou erro no código.

Contexto de laboratório: Overflow de buffer, pinagem errada no Wokwi, conversão incorreta de valores, etc.

Exemplos

git commit -m "fix(uart): corrige overflow no buffer de recepção"

git commit -m "fix(wokwi): resolve erro de pinagem do LED no diagrama

Alinha o pino GPIO2 do ESP32 com o LED no arquivo
diagram.json do simulador."

git commit -m "fix(sensor): corrige conversão de umidade relativa"

docs

docs — Documentação

Quando usar: Alterações que afetam apenas a documentação (README, comentários, diagramas, etc.).

Contexto de laboratório: Atualizar instruções de montagem, documentar pinos ou flags de compilação.

Exemplos

git commit -m "docs: atualiza README com instruções de montagem no breadboard"

git commit -m "docs(platformio): documenta flags de compilação usadas no laboratório"

git commit -m "docs: adiciona diagrama de ligação do sensor DHT22"

style

style — Formatação / estilo

Quando usar: Mudanças que não afetam a lógica (indentação, espaços, formatação).

Contexto de laboratório: Aplicar clang-format, padronizar estilo de código da turma.

Exemplos

git commit -m "style: aplica formatação clang-format em todos os arquivos .cpp/.h"

git commit -m "style(main): ajusta indentação e remove espaços em branco extras"

refactor

refactor — Refatoração

Quando usar: Reorganizar o código sem alterar o comportamento externo (nem bugfix nem feature).

Contexto de laboratório: Separar lógica em arquivos, extrair funções, melhorar legibilidade.

Exemplos

git commit -m "refactor(display): extrai funções de desenho para oled.cpp"

git commit -m "refactor: move constantes de pinos para config.h"

git commit -m "refactor(wifi): separa lógica de conexão em módulo próprio"

perf

perf — Performance

Quando usar: Melhorias de desempenho (tempo de execução, consumo de memória, etc.).

Contexto de laboratório: Otimizar leituras de ADC, reduzir tempo de amostragem, economizar RAM.

Exemplos

git commit -m "perf(adc): reduz tempo de amostragem do ADC em 30%"

git commit -m "perf(sensor): implementa média móvel para reduzir ruído sem aumentar latência"

test

test — Testes

Quando usar: Adicionar ou corrigir testes (unitários, de integração, etc.).

Contexto de laboratório: Criar testes de validação de sensores, debounce, faixas de valores.

Exemplos

git commit -m "test(sensor): adiciona teste de validação de faixa de temperatura"

git commit -m "test: cria teste unitário para função de debounce"

build

build — Sistema de build / dependências

Quando usar: Mudanças no sistema de build, platformio.ini, dependências ou bibliotecas.

Contexto de laboratório: Atualizar plataforma, adicionar bibliotecas, alterar flags de compilação.

Exemplos

git commit -m "build: atualiza plataforma espressif32 para versão 6.5.0"

git commit -m "build(deps): adiciona biblioteca ArduinoJson 7.0.0"

git commit -m "build: configura monitor_speed = 115200 no platformio.ini"

ci

ci — Integração Contínua

Quando usar: Configurações de CI/CD (GitHub Actions, GitLab CI, etc.).

Contexto de laboratório: Automatizar build e testes do projeto ESP32.

Exemplos

git commit -m "ci: adiciona workflow de build no GitHub Actions"

git commit -m "ci: configura job de verificação de formatação com clang-format"

chore

chore — Manutenção

Quando usar: Tarefas de manutenção que não afetam o código-fonte principal.

Contexto de laboratório: Atualizar .gitignore, limpar arquivos temporários do Wokwi/PlatformIO.

Exemplos

git commit -m "chore: atualiza .gitignore para ignorar arquivos do PlatformIO"

git commit -m "chore(wokwi): limpa arquivos temporários gerados pela simulação"

git commit -m "chore: remove arquivos .bak e temporários do projeto"

revert

revert — Reversão

Quando usar: Desfazer um commit anterior.

Contexto de laboratório: Reverter alteração que quebrou a simulação no Wokwi ou o build.

Exemplos

git commit -m "revert: reverte feat(wifi): configura conexão automática

Este commit causava travamento no Wokwi quando o
Access Point da sala estava indisponível.

Refs: abc1234"

git commit -m "revert: desfaz alteração que quebrou o diagrama do Wokwi"

---

import ConventionalCommitsTypes from "@site/src/components/ConventionalCommitsTypes";

## Conventional Commits (components)

<ConventionalCommitsTypes />

Conventional Commits em Projetos de Firmware e Sistemas Embarcados

Em projetos de firmware e sistemas embarcados (PlatformIO + VS Code + Wokwi para ESP32), a adoção da Convenção Conventional Commits traz clareza, facilita a geração automática de changelogs e melhora a colaboração em atividades de laboratório.

Este documento apresenta a classificação dos tipos de commits e exemplos práticos orientados para o contexto de sala de aula.

Estrutura Básica

<tipo>[escopo opcional]: <descrição curta>

[corpo opcional]

[rodapé(s) opcional(is)]

Regras importantes

• A descrição deve ser escrita no imperativo e em minúsculas (exceto nomes próprios).
• Máximo recomendado de 72 caracteres na primeira linha.
• O escopo é opcional e geralmente indica o módulo ou componente afetado (sensor, wifi, platformio, display, etc.).
• Use o corpo para explicar o porquê da mudança, não apenas o o quê.

Classificação dos Tipos

Tipo	Quando usar	Exemplo de contexto em laboratório
feat	Nova funcionalidade	Implementar leitura de sensor DHT22
fix	Correção de bug	Corrigir overflow no buffer UART
docs	Alterações apenas em documentação	Atualizar README com diagrama de conexão
style	Formatação, espaços, ponto e vírgula (sem mudança de lógica)	Ajustar indentação do código PlatformIO
refactor	Mudança de código que não corrige bug nem adiciona feature	Separar lógica de Wi-Fi em arquivo próprio
perf	Melhoria de performance	Otimizar leitura ADC com media móvel
test	Adição ou correção de testes	Criar teste unitário para função de debounce
build	Mudanças no sistema de build ou dependências externas	Atualizar versão da biblioteca FastLED
ci	Configuração de integração contínua	Adicionar workflow de build no GitHub Actions
chore	Tarefas de manutenção que não afetam o código-fonte	Atualizar .gitignore ou limpar arquivos temporários
revert	Reverter um commit anterior	Desfazer commit que quebrou o simulador Wokwi

Exemplos Práticos para Atividades de Laboratório

1. feat – Nova funcionalidade

feat(sensor): adiciona leitura do DHT22 com média móvel

Implementa leitura periódica a cada 2 segundos e calcula
média das últimas 5 amostras para reduzir ruído.

feat(wifi): configura conexão automática ao Wi-Fi da sala

Usa credenciais definidas em platformio.ini e tenta
reconexão a cada 10 segundos em caso de falha.

2. fix – Correção de bug

fix(uart): corrige overflow no buffer de recepção

Aumenta o tamanho do buffer de 64 para 256 bytes e
adiciona verificação de espaço disponível antes de escrever.

fix(wokwi): resolve erro de pinagem do LED no diagrama

Alinha o pino GPIO2 do ESP32 com o LED no arquivo
diagram.json do simulador.

3. docs – Documentação

docs: atualiza README com instruções de montagem no breadboard

Inclui foto da montagem física e tabela de pinos utilizados.

docs(platformio): documenta flags de compilação usadas no laboratório

4. refactor – Reorganização de código

refactor(display): extrai funções de desenho para oled.cpp

Melhora legibilidade do arquivo principal main.cpp.

5. build – Sistema de build e dependências

build: atualiza plataforma espressif32 para versão 6.5.0

Necessário para suporte correto ao ESP32-S3 no Wokwi.

build(deps): adiciona biblioteca ArduinoJson 7.0.0

6. chore – Manutenção

chore: atualiza .gitignore para ignorar arquivos do PlatformIO

Adiciona .pio/ e .vscode/settings.json.

chore(wokwi): limpa arquivos temporários gerados pela simulação

7. test – Testes

test(sensor): adiciona teste de validação de faixa de temperatura

Verifica se valores fora de -40°C a 80°C são descartados.

8. perf – Performance

perf(adc): reduz tempo de amostragem do ADC em 30%

Utiliza leitura em modo contínuo em vez de single-shot.

9. style – Estilo de código

style: aplica formatação clang-format em todos os arquivos .cpp/.h

10. revert – Reversão

revert: reverte "feat(wifi): configura conexão automática"

Este commit causava travamento no Wokwi quando o
Access Point da sala estava indisponível.

Refs: abc1234

Boas Práticas para o Laboratório

1. Um commit = uma intenção clara
   Evite misturar correção de bug com nova feature no mesmo commit.

2. Commits pequenos e frequentes
   Ideal para acompanhamento pelo professor durante a aula.

3. Escopo útil
   Use escopos consistentes: sensor, actuator, wifi, display, platformio, wokwi, docs.

4. Mensagens em português ou inglês?
   Defina com a turma no início do semestre. O importante é manter consistência.

5. Ferramentas recomendadas

   • Extensão Conventional Commits no VS Code
   • commitizen ou cz-cli para auxiliar na criação
   • standard-version ou semantic-release para gerar changelog automaticamente

Exemplo de Histórico de Commits de uma Aula

feat(sensor): implementa leitura do DHT22
fix(sensor): corrige conversão de umidade relativa
docs: adiciona diagrama de ligação do sensor
refactor: move constantes de pinos para config.h
build: adiciona biblioteca DHT sensor library
chore: atualiza platformio.ini com monitor_speed = 115200

---

Dica para o professor

Peça aos alunos que enviem o histórico de commits (git log --oneline) ao final da atividade. Isso facilita a avaliação do processo de desenvolvimento, não apenas do código final.

Referência oficial