Writing a good patch

Write separate changes

É 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.

Preferably, each fix that addresses an issue should be in its own patch/commit with its own description/commit message stating exactly what they correct so that all changes can be selectively applied by the maintainer or other interested parties.

Furthermore, separate changes enable bisecting much better for tracking issues and regression in the future.

Documentação

Documentation can be a tedious task; however, it is necessary for someone to complete it. It makes things a lot easier if you submit the documentation together with code changes. Please remember to document methods, complex code blocks, or user-visible features.

Veja também

Contribua para a documentação do Weblate

Test cases

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.

Veja também

Conjunto de testes e integração contínua do Weblate

Mensagens de submissão

Os commits do Git devem seguir a especificação de Conventional Commits.

Verificação de tipo

Any new code should utilize PEP 484 type hints. We are using mypy to check them because it has a Django plugin that makes type checking of Django apps practical.

New and changed code should not introduce new mypy failures where current Django typing support makes that practical. The code base is not yet completely covered by type annotations, and some Django constructs are difficult to annotate precisely. CI therefore enforces mypy only for selected modules and reports other findings separately.

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.

The easiest approach to enforce all this is to install prek. This is a third-party reimplementation of the pre-commit tool used by Weblate. It is included in the development dependencies declared in pyproject.toml, so installing those dependencies makes prek available.

To check all files manually, run:

uv run prek run --all-files

If you prefer the original pre-commit client, it uses the same configuration from .pre-commit-config.yaml.

Coding securely

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.

This is independent of whether AI is used or not.

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.

We can accept code written with the help of AI into the project, but the code must still follow coding standards, be written clearly, be documented, feature test cases, and adhere to all the normal requirements we have.