Contribuir

Faz uma alteração pequena no sítio certo e envia-a como pull request.

Antes de começares

• Abre primeiro um issue, ou comenta um que já exista. Diz o que queres mudar e porquê.
• Espera por uma resposta, para não construíres algo que não vai ser aceite.
• Termina a Configuração para poderes compilar e executar o HolyArrs.

As perguntas vão para o Discord. As ideias vão para o r/HolyArrs. Os issues são para bugs e para o roadmap.

Envia o teu primeiro pull request

1. Descobre a que módulo pertence a tua alteração. Os nomes em Módulos coincidem com nomes de pastas, por isso um aviso de Discord errado é uma alteração em alerts.

2. Faz a alteração em app/backend/internal/<module>/ e em app/frontend/src/lib/<module>/. Limita-te a uma correção ou a uma funcionalidade.

3. Compila a app web e depois o programa, e experimenta a alteração no navegador. Vê Configuração.

4. Executa as verificações de Testes.

   Não deves ver nenhuma falha.

5. Se mudaste uma página, executa o projeto de ponta a ponta dela, por exemplo npm --prefix app/frontend run e2e -- --project=movies.

6. Abre o pull request. Liga o issue, diz o que mudou e como testaste, e acrescenta ou atualiza testes para a alteração.

7. No teu primeiro pull request, um bot pede-te que assines o acordo de licença de contribuidor. Responde com a frase que ele pede.

Nota

Manténs os direitos de autor do teu trabalho. O acordo permite que o HolyArrs seja oferecido sob a AGPL-3.0 e sob uma licença comercial. Tudo o que for integrado continua também disponível sob a AGPL-3.0. O texto está em .github/CLA.md.

Opções

Onde vai cada alteração

Alteração	Vai para
Uma rota nova	Módulos
Um módulo novo	Módulos. Abre primeiro um issue
Uma funcionalidade retida	Configuração
Uma versão	Publicar versões. Só para mantenedores

Como é um bom pull request

• Escreve comentários que digam porque o código faz o que faz. Sem números de roadmap, datas, nomes nem travessões longos nos comentários.
• Não mexas nas palavras da app, a não ser que o issue seja sobre as palavras.
• Deixa como estão os caminhos de API já publicados, os nomes de campos, as chaves de definições, os nomes de tabelas e os nomes de tarefas. Acrescenta, nunca renomeies.

Se não funcionar

Sintoma. Uma verificação de estrutura falha. Causa. A mensagem indica o ficheiro e a regra. Solução. Move o código, ou passa dados simples a partir do módulo superior. Vê Módulos.

Sintoma. A app web parece antiga. Causa. O programa serve a compilação que tem incluída. Solução. Compila a app web outra vez antes do programa.

Sintoma. Os testes de ponta a ponta não arrancam. Causa. O navegador de testes não está instalado. Solução. Executa npx --prefix app/frontend playwright install chromium.

Para especialistas

Regras que um pull request tem de cumprir

• Um módulo só fala com outro através do serviço dele (Go) ou do seu index.ts (web). Nunca através do armazém (store) ou dos ficheiros dele.
• O SQL vive só nos ficheiros store*.go de um módulo, sobre as tabelas desse módulo.
• Uma parte da web só vai para lib/ui quando 2 ou mais módulos a usam.
• Sem pacotes util, common, shared ou helpers.
• Todas as chamadas para fora passam por core/outbound.

Os testes verificam estas regras, por isso uma importação errada faz a compilação falhar. A lista completa e os nomes das verificações estão em Módulos.

O que o CI executa

Tarefa	Executa
Web	check, lint, test, build e a suite de ponta a ponta
Go	go build, go vet e go test -timeout 60m ./... em amd64 e arm64, nativamente e sob emulação
Race	go test -race ./...
Contract	A correspondência com openapi.json, verificações de âmbito em todas as rotas, a suite de gestores de transferências
Fault and scale	Execuções de falha, escrita lenta, serviço externo avariado e memória
Image	Uma imagem de desenvolvimento compila, arranca e indica a sua versão

Os detalhes das execuções longas estão em Testes.

Relacionado

• Configuração
• Testes
• Arquitetura