Código-fonte do Weblate¶
O Weblate é desenvolvido no GitHub. É bem-vindo para criar um fork do código e abrir pull requests. Patches em qualquer outra forma também são bem-vindos.
Veja também
Consulte Componentes internos do Weblate para ver como o Weblate se parece por dentro.
Licença e direitos de autor¶
Ao contribuir código do projeto, concorda em colocar as suas mudanças e código novo sob o a licença do repositório, GPL-3.0-ou-posterior, salvo indicação contrária e concordada previamente. Novos ficheiros fonte devem seguir os direitos de autor existentes e o estilo de cabeçalho de licença SPDX.
Utilize uma licença diferente apenas quando há um motivo deliberado, como por exemplo ficheiros partilhados com repositórios que usam licenças mais permissivas.
Veja também
Licença weblate explica licenciamento em mais detalhe.
Escrever um bom patch¶
Escrever alterações separadas¶
É irritante quando tem uma correção de código gigante que diz que arranja 11 problemas estranhos, mas discussões e opiniões que não concordam com 10 ou 9 das mesmas já foram corrigidas de forma diferente. Depois a pessoa a juntar esta mudança precisa de extrair a única correção interessante de algures nesta pilha gigante de fontes, e isso cria muito trabalho adicional.
Preferencialmente, cada correção que aborda um problema deve estar no seu próprio patch/commit com a sua própria descrição/mensagem de commit que descreve exatamente o que corrigiram para que todas as mudanças possam ser seletivamente aplicadas pelo colaborador ou outros terceiros interessados.
Para além disso, mudanças separadas permitem a bissecção melhor para rastrear problemas e regressão no futuro.
Documentação¶
Documentação pode ser uma tarefa enfadonha; no entanto, é necessário que alguém a complete. Isto torna as coisas mais fáceis se submeter a documentação em conjunto com o código. Por favor lembre-se de documentar métodos, blocos de código complexos, ou funcionalidades visíveis para o utilizador.
Veja também
Casos de uso¶
Os testes permitem-nos verificar rapidamente que as funcionalidades estão a funcionar como é suposto. Para manter esta situação e melhorá-la, todas as novas funcionalidades e funções que são adicionadas precisam de ser testadas no conjunto de testes. Cada funcionalidade que é adicionada deve ter pelo menos um caso de teste válido que verifica que funciona conforme documentado.
Mensagens de submissão¶
Os commits do Git devem seguir a especificação de Conventional Commits.
Verificação de tipo¶
Qualquer novo código deverá utilizar as dicas de tipo PEP 484. Nós estamos a utilizar mypy para verificá-los porque têm um “”plug-in”” do Django que torna prática a verificação de tipos das aplicações do Django).
Código novo e mudado não deve introduzir novas falhas mypy onde o suporte de digitação Django atual torna isto prático. A base de código ainda não é completamente coberta por anotação de tipos, e algumas estruturas Django são difíceis de anotar de forma precisa. Então, o CI aplica mypy apenas para módulos selecionados e comunica outras conclusões separadamente.
Padrão de codificação e linting do código¶
O código deveria seguir as linhas diretrizes de codificação PEP 8 e deveria ser formatado utilizando o formatador de código ruff.
Para verificar a qualidade do código, pode utilizar o ruff, a sua configuração está guardada em pyproject.toml.
Ao suprimir um diagnóstico ruff, é preferível # ruff: ignore[rule-name] com o nome da regra legível para humanos. Coloque o comentário na linha acima da proposição ou bloco lógico quando isso não torna mais abrangente o escopo da supressão. Mantenha o comentário em linha quando movê-lo mudaria o escopo, afeta ordenação de importação, ou intromete-se no comentário de outra ferramenta disable-next e o seu código alvo.
A abordagem mais fácil para aplicar isto é instalar prek. Isto é uma re-implementação de terceiros da ferramenta pre-commit usada pelo Weblate. É incluída nas dependências de desenvolvimento declaradas em pyproject.toml, por isso instalar essas dependências torna prek disponível.
Para verificar todos os ficheiros manualmente, execute:
uv run prek run --all-files
Se prefere o cliente original pre-commit, utiliza a mesma configuração em .pre-commit-config.yaml.
Programação segura¶
Qualquer código para Weblate deve ser escrito com Princípios de Segurança por Design (inglês) em mente.
Linhas diretrizes de IA¶
Ao contribuir conteúdo para o projeto, dá-nos permissões para usá-la tal como está, e deve certificar-se que tem permissão para distribuir a mesma para nós. Ao submeter uma mudança para nós, concorda que as mudanças podem e devem ser adotadas pelo projeto e ser distribuídas sob a licença do projeto. Autores devem estar conscientes de forma explícita que cabe-lhes a responsabilidade de garantir que não seja submetido ao projeto qualquer código sem licença.
Isto é independente de se IA é utilizado ou não.
Ao contribuir para um pull request deve, claramente, certificar-se que a proposta é de boa qualidade e que o melhor esforço segue as nossas diretrizes. Uma regra de prática básica é que se alguém pode identificar que a contribuição foi feita com a ajuda de IA, tem mais trabalho a fazer.
Podemos aceitar código escrito com a ajuda de IA para o projeto, mas o código tem que seguir regras de programação, ser escrito de forma clara, estar documentado, incluir casos de teste, e aderir a todos os requisitos normais que temos.