Manifesto de fixação de dependências

Postura ratificada de como o Apothem declara, fixa e bloqueia dependências. Público: contribuidores e consumidores a jusante que precisam entender o modelo de reprodutibilidade.

PosturaCopy Anchor Link

O Apothem é uma CLI em Python com um pequeno conjunto de dependências de runtime, além de uma cadeia de ferramentas maior de desenvolvimento, auditoria, lançamento e documentação. As dependências de runtime usam limites inferiores conservadores em pyproject.toml; o site faz commit de site/package-lock.json; as GitHub Actions são fixadas por SHA imutável com comentários de versão e são atualizadas pelo Dependabot.

Ratificação de lançamentoCopy Anchor Link

BloqueioCopy Anchor Link

Os arquivos de bloqueio do Python dos próprios contribuidores são gerados sob demanda e não são commitados: o fechamento de runtime do Apothem é pequeno e a CLI oferece suporte a várias versões menores do Python. O CI é a exceção. Ele instala os arquivos bloqueados por hash em scripts/ci/: quatro bloqueios de dependências (requirements-ci-dev.txt, -runtime.txt, -test.txt e -prereqs.txt) e um bloqueio para cada ferramenta que os fluxos de trabalho executam (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt e -pre-commit.txt). python scripts/dev/refresh_ci_locks.py compila os nove em uma data de bloqueio menos um período de espera de 7 dias, igual ao do Dependabot, de modo que o CI testa as versões que tinham pelo menos uma semana na data de bloqueio, e atualizar os arquivos as faz avançar. Cada arquivo registra a data de bloqueio, o período de espera e a data de corte resultante, e --check reproduz essa data de corte. Uma correção de segurança urgente mais recente que o período de espera exige uma atualização com --cooldown-days 0, ou uma exceção ao período de espera para o pacote dela em scripts/dev/ci_lock_table.py, que remove o período de espera só para esse pacote. A execução semanal de pip-audit.yml audita as versões mais recentes que pyproject.toml permite, além dos nove bloqueios, consultando o serviço OSV sobre alertas de segurança. Os contribuidores continuam instalando com pip install -e ".[dev]".

# Astral uv:
uv pip install -e ".[dev,security,release]"
uv pip freeze > requirements.dev.lock

# pip-tools:
pip-compile --extra=dev --extra=security --extra=release -o requirements.dev.lock pyproject.toml

# Plain pip:
pip install -e ".[dev,security,release]"
pip freeze > requirements.dev.lock

O site é diferente: site/package-lock.json é commitado e o CI usa npm ci, de modo que o site de documentação renderizado tem um fechamento de Node reprodutível.

JustificativaCopy Anchor Link

• Por que fixações por faixa para o Python? A CLI oferece suporte a uma ampla matriz de Python, então pyproject.toml mantém pisos conservadores. O CI instala fechamentos bloqueados por hash dessas faixas, que o mantenedor atualiza com scripts/dev/refresh_ci_locks.py (a cadência prevista é semanal), e a execução semanal de pip-audit.yml resolve as versões permitidas mais recentes para revelar problemas com as ferramentas atuais.
• Por que um bloqueio de Node commitado? O site é um artefato estático implantado; o arquivo de bloqueio fornece builds npm ci deterministas para essa superfície pública.
• Por que Actions fixadas por SHA? As tags são mutáveis; os SHAs são imutáveis. O Dependabot propõe os incrementos de SHA e reescreve cada comentário de versão, enquanto o portão de lançamento registra qualquer retenção intencional.
• O que o bot de atualização não toca. As atualizações de versão do Dependabot (.github/dependabot.yml) cobrem as fixações das GitHub Actions, o arquivo de bloqueio do site, o arquivo de bloqueio do empacotador vsce (tools/vsce), o arquivo de bloqueio das CLIs de harness que o channel smoke instala (tools/channel-smoke), o pip bloqueado por hash que o CI instala (scripts/ci/requirements-ci-pip.txt) e os hooks de pre-commit. Os outros nove arquivos em scripts/ci são fechamentos regenerados por inteiro com scripts/dev/refresh_ci_locks.py; nenhum deles fixa o pip, e as atualizações de versão do Dependabot para essa pasta se limitam ao pip. Os pisos de runtime em pyproject.toml, os requisitos de lançamento bloqueados por hash, o fechamento vendorizado em src/apothem/_vendor/vendor.txt e os hooks de pre-commit fixados em sincronia com pyproject.toml mudam à mão, porque o incremento de uma única fixação quebraria os arquivos com os quais eles concordam. Os hooks do ruff e do mypy são dois deles: tests/scripts/test_ci_tool_locks.py falha até que a fixação exata do ruff em pyproject.toml, a rev do hook, o bloqueio do ruff e o bloqueio dev tenham a mesma versão, e até que a fixação exata do mypy, a rev do hook do mypy e as bibliotecas que esse hook lista correspondam ao bloqueio dev. Por isso, um pull request de segurança do Dependabot para qualquer uma das duas ferramentas é adaptado à mão. A versão major de @types/node do site acompanha o piso de Node dele (engines e .nvmrc, Node 22), de modo que o Dependabot propõe apenas as atualizações minor e patch dele; eleve essa versão major junto com o piso. As atualizações de versão deixam intactos os blocos overrides do npm. As atualizações de segurança do Dependabot ainda cobrem todos os manifestos, de modo que um pull request de segurança pode propor uma dessas fixações, ou mover um override; adapte-o à mão ou feche-o.
• Mesclando um pull request do Dependabot. O padrão de squash do repositório usa o título do PR. Alguns títulos do Dependabot, principalmente os agrupados que nomeiam um diretório, ultrapassam o assunto de squash de 72 caracteres; a verificação PR Title os aponta, e uma troca de título os corrige. Um pull request que altera um arquivo de bloqueio de ferramenta não executa nenhum job de ci.yml, então o fluxo de trabalho de auditoria npm o audita e o instala, empacota a extensão do VS Code para o arquivo de bloqueio do vsce e executa os testes de lançamento do vsce, e o fluxo de trabalho do channel smoke é executado para o arquivo de bloqueio do channel-smoke. O fluxo de trabalho Markdown Lint executa o hook markdownlint em um pull request de hooks de pre-commit; os outros hooks não são exercitados no CI, então execute pre-commit run --all-files no branch dele antes de mesclá-lo.