Objetivo
Orientar mudanças pequenas e seguras em bibliotecas .NET, preservando a baseline de build, testes, empacotamento e compatibilidade pública.
Quando usar
- Alterações em código sob
/src. - Mudanças comportamentais que exigem atualização de testes em
/tests. - Ajustes em
.csproj, PackageId, metadados NuGet ou documentação XML. - Inclusão, remoção ou atualização de dependências.
- Mudanças em tipos ou membros públicos.
Quando não usar
- Refatoração puramente estrutural sem mudança funcional: use
dotnet-refactoring-engineer. - Auditoria de cobertura: use
coverage-analysis. - Auditoria de qualidade dos testes: use
test-anti-patterns. - Mudanças apenas em workflows ou release: use
ci-release-governance.
Processo
- Leia
AGENTS.mde os arquivos diretamente relacionados à mudança. - Identifique o projeto de produção e os testes correspondentes.
- Verifique se a mudança altera comportamento observável ou API pública.
- Escolha o menor ajuste coerente com os padrões existentes.
- Atualize ou adicione testes para mudanças comportamentais.
- Para dependências, altere versões somente em
Directory.Packages.propse regenere lock files por restore. - Atualize
CHANGELOG.mdse houver impacto relevante para consumidores. - Se a mudança afetar empacotamento ou contrato público, valide o pacote.
- Revise o diff e remova alterações não relacionadas.
Validação
Baseline a partir da raiz:
dotnet tool restore
dotnet restore --locked-mode
dotnet format --verify-no-changes --no-restore
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build
Para mudanças de dependência, regenere antes os lock files:
dotnet restore --force-evaluate
dotnet restore --locked-mode
Para mudanças em API pública, metadados ou packaging:
dotnet pack --configuration Release --no-build --output artifacts/packages
dotnet run --file scripts/verify-package.cs -- artifacts/packages
Restrições
- Não adicione
Version=emPackageReference. - Não edite
packages.lock.jsonmanualmente. - Não transforme membros internos em públicos apenas para facilitar testes.
- Não introduza dependência de domínio, infraestrutura ou framework sem necessidade reutilizável clara.
- Não quebre API pública de forma incidental.
- Não reduza warnings, testes, auditoria ou validações para contornar falhas.
- Não faça push, release ou publicação sem solicitação explícita.
Critério de qualidade
Uma boa mudança resolve o problema com diff limitado, preserva contratos não envolvidos, possui testes proporcionais ao risco e deixa restore, build, test e packaging coerentes com a baseline.