Setup de desenvolvimento¶
Para quem vai contribuir com código, não apenas consumir o pacote — para isso, veja Getting Started. Leia também Como contribuir antes de abrir um PR.
Clonar com os submodules¶
O Bootstrap e o @govbr-ds/core são git submodules em vendor/, fixados
por tag (DP-01/DP-03 em Requisitos de software):
git clone --recurse-submodules https://github.com/abrasileirado/dsgovbr-bootstrapped.git
Se já clonou sem --recurse-submodules:
git submodule update --init --recursive
Instalar e compilar¶
npm install
npm run build
Gera:
dist/dsgovbr-bootstrapped.css,.min.csse.css.map— artefatos do pacote.docs/assets/css/dsgovbr-bootstrapped.css— cópia usada pelas páginas de documentação (docs/componentes/,docs/exemplos/); é gerada a cada build e não é versionada (.gitignore).docs/componentes/*.html— gerado a partir do template emsrc/site/layout.htmle dos fragmentos emsrc/site/componentes/(issue #15); também não é versionado. Para criar uma página nova, edite os fragmentos emsrc/site/componentes/, não os arquivos gerados — ver Desenvolvimento.
Visualizar as páginas de componentes localmente¶
As páginas carregam o CSS por caminho relativo (../assets/css/...), o que
não funciona abrindo o arquivo direto no navegador (file://). Depois de
npm run build:
npm run serve # node scripts/serve.js — serve docs/ em http://127.0.0.1:4173/
Abra http://127.0.0.1:4173/componentes/index.html. O servidor serve só
docs/, a mesma raiz que o GitHub Pages publica: referenciar um arquivo fora
de docs/ (ex.: ../../vendor/...) dá 404 aqui e no site — foi um bug real,
agora coberto por teste. Se você usa o Claude Code neste projeto, o
.claude/launch.json já aponta para esse mesmo servidor.
Atualizando os submodules (Bootstrap / GOV.BR DS)¶
Os submodules são fixados por tag estável (vX.Y.Z) deliberadamente —
nunca aponte para a branch padrão ou para um commit solto. O Dependabot
não cobre submodules por tag (isso já causou um bump indevido, revertido),
então a detecção é do workflow .github/workflows/upstream-check.yml: toda
segunda ele roda scripts/check-upstream.js e abre a issue “Atualizar
vendor/ para vX.Y.Z” quando há tag estável mais nova. Para conferir na
hora: node scripts/check-upstream.js. Política completa: DP-09 em
requisitos.
Checklist de atualização (a partir da issue aberta)¶
Mudança de major? Trate como decisão nova (revisar tokens, SCSS, markup) antes de seguir.
Avançar a tag:
cd vendor/bootstrap # ou vendor/govbr-ds-core git fetch --tags git checkout vX.Y.Z cd ../.. git add vendor/bootstrap # ou vendor/govbr-ds-core
npm run buildenpm testprecisam passar. O teste de deriva de tokens (tests/tokens.test.js) confere cada valor desrc/scss/_tokens.scsscontra o GOV.BR DS: se falhar, atualize o token (e a origem citada no comentário) ou registre por que o valor foi mantido.Consumidor limpo (
test:package) também roda dentro denpm test.Revalidar visualmente as páginas de
docs/componentes/.Atualizar a versão citada em
docs/requisitos.rst(DP-01/DP-03),THIRD_PARTY_NOTICES.mde, se for o Bootstrap, nos comentários desrc/scss/index.scss.Subir a versão do pacote e publicar (ver “Publicação planejada” em desenvolvimento).
Se algo quebrar, mantenha a tag atual e registre o motivo na issue.
Contribuindo com um componente¶
Ver a lista de verificações por componente em Desenvolvimento e as diretrizes de PR em Como contribuir.