O que você vai aprender#
- quais ferramentas instalar;
- como compilar e executar o programa a partir de um clone;
- os comandos que verificam a sua mudança antes de você enviá-la.
A ideia#
O repositório é um módulo Go com um front-end em web/ e o site de documentação em site/. O Task é o único ponto de entrada: os comandos que você executa na sua máquina são os que o pipeline do pull request executa. A indentação é uma tabulação de largura 4 (.editorconfig), exceto em arquivos cujo formato exige espaços, e o Git espera finais de linha LF.
Início rápido#
Instale estas ferramentas:
| Ferramenta | Usada para |
|---|---|
Go, a versão do go.mod | o núcleo, o motor, o serviço e o programa |
| Task | os comandos abaixo |
| golangci-lint | task lint para Go |
| Bun | web/ (o projeto usa o Bun ali, não o npm) |
| Node.js 24 e npm | site/ (o site de documentação mantém o npm) |
| FFmpeg 9 | os testes que codificam; a imagem de contêiner traz um fixado |
Depois, a partir da raiz do clone:
task setup
task ciO task setup confere as ferramentas e ativa os hooks de .githooks/: o hook de pre-commit verifica os arquivos Go e Markdown em stage, e o hook de pre-push atualiza as datas de "Last updated" do site. O task ci executa task lint, task vet, task test, task tidy:check e task notices:check.
Para executar o programa a partir do clone, compile o front-end com bun install e bun run build em web/ (o programa embute os arquivos que a compilação grava), depois go run ./web/cmd/app serve a partir da raiz. Ele se comporta como o binário.
| Comando | Faz |
|---|---|
task lint | Go, Markdown, o front-end web e o site |
task test | os testes Go (go test -short) |
task codegen | regenera os contratos, os tipos TypeScript e os fixadores do FFmpeg |
task site:build | compila o site e executa as suas verificações |
bun run check:thin-client (em web/) | as regras do cliente fino |
Erros comuns#
- Executar
npm installemweb/, oubunemsite/. Cada pasta tem um gerenciador de pacotes e um arquivo de bloqueio. - Pular o
task codegendepois de mudar um registro ou esquema: a verificaçãoGenerated filesfalha com um diff. Execute-o e faça o commit do resultado. - Mudar
go.mod,web/package.jsonou um arquivo de bloqueio semtask notices: otask notices:checkfalha até os avisos serem regenerados. - Compilar o site com uma versão do Node.js diferente da que o pipeline usa (24): outra versão principal pode mudar a saída das verificações da compilação.