Golden Rules

# 🏆 Golden Rules: Configuração Obrigatória para Novos Repositórios FinOps

Este guia detalha as configurações de qualidade, segurança e padronização que são obrigatórias para todo novo repositório criado pelo time FinOps. Seguir estas regras garante a integração imediata com nossos fluxos de CI/CD, versionamento semântico e padrões de código.

1. Padronização da Versão do Node.js

Manter a versão do Node.js atualizada e explícita é crucial para a consistência do ambiente e o aproveitamento das Golden Images do time de Plataformas.

Ações Obrigatórias

Atualização Local:
- Utilize o NVM (Node Version Manager).
- Execute: nvm use <version> ou nvm install <version>.
- Limpeza: Apague os arquivos de lock (package-lock.json ou yarn.lock) e a pasta node_modules.
Atualização no package.json:
- Atualize a seção engines com a versão mais recente e homologada (Exemplo usando Node 24):
```
"engines": {
  "node": "24",
  "npm": ">=11"
}
```
Instalação: Execute npm i e realize testes locais para confirmar a retrocompatibilidade das dependências.

Atenção: Se houver arquivos de deploy específicos, Dockerfile ou configurações de CI/CD relacionadas à versão do Node.js, contate o time de Plataformas ou consulte as documentações sobre o uso das Golden Images.

2. Padrão de Commits (Commitlint)

Garantir que todas as mensagens de commit sigam um padrão consistente (Convenional Commits) é vital para a automação do Semantic Release e a geração do CHANGELOG.

Ações Obrigatórias

Instalação de Dependências:

npm install --save-dev @commitlint/config-conventional@19.5.0 @commitlint/cli@19.5.0 conventional-changelog-conventionalcommits@8.0.0

Criação do Arquivo de Configuração: Crie o arquivo commitlint.config.js na raiz do repositório com o seguinte conteúdo:

export default {
    extends: ["@commitlint/config-conventional"],
    rules: {
        // Regras customizadas para o time
        "header-max-length": [0, "always", 72], // Limite de 72 caracteres para o header
        "body-min-length": [0, "always", 10],   // Requer corpo com no mínimo 10 caracteres
        "body-max-line-length": [0],            // Desabilita o limite de linha para o corpo
        "type-enum": [
            0,
            "always",
            [
                "feat",     // Nova funcionalidade
                "fix",      // Correção de bug
                "perf",     // Melhoria de performance
                "style",    // Alteração de estilo (formatação)
                "refactor", // Refatoração de código
                "chore",    // Tarefas diversas (build, configs)
                "test",     // Adição ou refatoração de testes
                "docs",     // Alteração na documentação
                "ci",       // Alteração em configs de CI/CD
                "build"     // Alterações em dependências ou build
            ],
        ],
        "type-case": [0, "always", "lowerCase"], // Tipos devem ser em letras minúsculas
    },
};

3. Ganchos de Pré-Commit (Husky)

O Husky automatiza a execução de checks (como o Commitlint, Linter e Testes) antes que o código seja efetivamente comitado ou pushed, garantindo a qualidade.

Ações Obrigatórias

Instalação e Inicialização:

npm install --save-dev husky

npx husky init

Configuração do Gancho para o Commitlint: Adicione o hook para validar a mensagem do commit (garantindo que o Commitlint seja executado):
```
echo npx --no-install commitlint --edit \"\$1\" > .husky/commit-msg
```

Próximos Passos: Configure outros hooks essenciais (ex: pre-commit para rodar linter ou testes) conforme as necessidades do repositório.

4. Automação de Versionamento e Publicação (Semantic Release)

O Semantic Release automatiza a criação de versões (tags), a geração do Registro de Alterações (CHANGELOG) e a publicação de releases com base nos padrões de commit.

Ações Obrigatórias

Instalação de Dependências:

npm install --save-dev semantic-release@24.2.0 @semantic-release/github@10.3.3 @semantic-release/npm@ @semantic-release/git@10.0.1 @semantic-release/commit-analyzer@13.0.0 @semantic-release/release-notes-generator@14.0.1 @semantic-release/changelog@6.0.3

Criação do Arquivo de Configuração (.releaserc.js): Crie o arquivo .releaserc.js na raiz com o conteúdo padrão que define a lógica de release e a geração do CHANGELOG:

export.default = {
  branches: [
    "main"
  ],
  plugins: [
    [
      "@semantic-release/commit-analyzer",
      {
        preset: "conventionalcommits",
        "releaseRules": [
          { "type": "feat", "release": "minor" },
          { "type": "fix", "release": "patch" },
          { "type": "perf", "release": "patch" },
          { "type": "style", "release": "patch" },
          { "type": "refactor", "release": "minor" },
          { "type": "chore", "release": "patch" }
        ],
        "parserOpts": {
          "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
        }
      }
    ],
    [
      "@semantic-release/release-notes-generator",
      {
        preset: "conventionalcommits",
        presetConfig: {
          types: [
            { type: 'feat', section: '✨ Recursos' },
            { type: 'fix', section: '🐛 Defeitos' },
            { type: 'perf', section: '⚡️ Melhorias de desempenho', hidden: false },
            { type: 'style', section: '💄 Alterações estéticas', hidden: false },
            { type: 'refactor', section: '🔨 Refatorações', hidden: false },
            { type: 'chore', section: '🚧 Tarefas diversas', hidden: true },
            { type: 'docs', section: '📝 Documentações', hidden: false },
            { type: 'test', section: '🧪 Testes', hidden: true }
          ],
        },
      }
    ],
    [
      "@semantic-release/changelog",
      {
        changelogFile: "docs/CHANGELOG.md",
        changelogTitle:
          "# Registro de Alterações\n\nMantenha-se atualizado com as últimas novidades e melhorias!",
      },
    ],
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        assets: ["docs/CHANGELOG.md"],
        message: "build: 🚀 Lançamento da versão v${nextRelease.version} [skip ci]",
      },
    ],
    "@semantic-release/github",
    [
      "@semantic-release/git",
      {
        message: "build: 🚀 Lançamento da versão v${nextRelease.version} [skip ci]",
      },
    ],
  ],
};

Criação do Workflow de CI/CD:

Criação do Workflow de CI/CD: Crie o arquivo .github/workflows/semantic-release.yml (ou ajuste o pipeline existente) com a lógica de release automatizada:

on:
  push:
  branches:
    - main
  workflow_dispatch:

name: semantic-release

jobs:
  release:
  name: Release
  runs-on: ch-tech-iac
  environment:
    name: release
  steps:
    - name: Checkout
    uses: actions/checkout@v5
    with:
      fetch-depth: 0
      token: ${{ secrets.GIT_HUB_TOKEN }}

    - name: Setup Node
    uses: actions/setup-node@v4
    with:
      node-version-file: .nvmrc
      cache: npm
      registry-url: https://npm.pkg.github.com/

    - name: Install Dependencies
    run: npm i --force
    env:
      NODE_AUTH_TOKEN: ${{ secrets.GHA_PACKAGES }}

    - name: Execute Semantic Release
    env:
      GITHUB_TOKEN: ${{ secrets.GIT_HUB_TOKEN }}
      HUSKY: '0'
      GIT_AUTHOR_NAME: 'grupoboticario'
      GIT_AUTHOR_EMAIL: 'finops-devs-aaaamilhsh6xbttsddqzw5fxiu@grupoboticario.org.slack.com'
      GIT_COMMITTER_NAME: 'grupoboticario'
      GIT_COMMITTER_EMAIL: 'finops-devs-aaaamilhsh6xbttsddqzw5fxiu@grupoboticario.org.slack.com'
    run: npx semantic-release

Próximos Passos (Checklist Adicional)

Além das regras acima, todo repositório deve ser criado com os seguintes artefatos:

README.md: Documentação mínima com instruções de setup local, scripts e contribuição.
Template de Pull Request: Arquivo na pasta .github/PULL_REQUEST_TEMPLATE.md para padronizar as submissões.

5. Template de Pull Request

Padronizar as submissões de código garante clareza, rastreabilidade e facilita o processo de revisão.

Arquivo Obrigatório

Crie o arquivo .github/PULL_REQUEST_TEMPLATE.md com o seguinte conteúdo:

## 🔨 What does this PR do?

<!--
Remove this comment and describe the motivation for this PR and its business importance.
Include a detailed description of changes, testing instructions, and relevant context.
List all dependencies required for this change.
-->

## 🔗 References

<!--
Include links to related stories, tasks, or GitHub issues.
-->

- Task/Story:

## 🧐 Type of change

- [ ] 🚑 **Patch**: Bug fix (no breaking changes)
- [ ] 🚀 **Patch**: Performance/CI/CD improvements (no breaking changes)
- [ ] ✨ **Minor**: New feature (no breaking changes)
- [ ] 💥 **Major**: Breaking changes (requires major version update)

## 🧪 How was it tested

<!--
Describe which tests were performed and the results obtained.
-->

## 🏁 Developer's Checklist

- [ ] Code follows project style guidelines
- [ ] Code review completed
- [ ] Documentation updated
- [ ] Tests created for the solution
- [ ] Comfortable with code quality and solution approach

## 👀 Reviewer's Checklist

- [ ] PR purpose is clear
- [ ] Business flow is understood
- [ ] Technical implementation is sound
- [ ] Test coverage is adequate

## ✅ Ready to Merge?

- [ ] 2+ approvals received
- [ ] All discussions resolved
- [ ] No `wip` or `block` labels
- [ ] Safe to merge to `main` branch

SonarQube: Integração configurada no pipeline de CI/CD para análise contínua de qualidade e segurança do código.