Guia de Desenvolvimento do Repositório de Código#
Código de Conduta#
Escrever um bom código não se resume apenas ao que você escreve, mas também a como escreve. Durante os testes de integração contínua, diversas ferramentas verificam seu código quanto a erros de estilo. Um bom estilo de programação é um dos requisitos para enviar código ao Xinference.
Além disso, não faça alterações repentinas no código, pois isso pode causar problemas em uma grande quantidade de códigos de usuários. Portanto, precisamos manter a compatibilidade reversa tanto quanto possível para evitar falhas em larga escala.
Correção automática de erros de formato#
Além disso, a integração contínua usará hooks do pre-commit para executar ferramentas de verificação de formato de código, como black, flake8, isort. Qualquer aviso gerado por essas verificações resultará em falha na integração contínua. Portanto, é recomendável executar essas verificações por conta própria antes de enviar o código. Isso pode ser feito instalando o pre-commit no diretório raiz do repositório Xinference:
pip install pre-commit
Em seguida, execute o comando:
pre-commit install
Depois de instalado, você pode garantir que todas as verificações de estilo sejam executadas automaticamente a cada commit, sem precisar executá-las manualmente uma por uma. Além disso, o uso do pre-commit também facilita a manutenção da sincronização quando nossas verificações de código forem alteradas.
Observe que, se necessário, você pode pular essas verificações usando o comando git commit --no-verify.
Se você não quiser incluir o pre-commit como parte do seu fluxo de trabalho, ainda pode executar o comando abaixo para usá-lo na verificação:
pre-commit run --files <files you have modified>
sem precisar executar pre-commit install previamente.
Se você deseja executar uma verificação em todos os arquivos submetidos recentemente, pode usar o seguinte comando:
pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files
sem precisar executar pre-commit install previamente.
Nota
Você pode considerar executar periodicamente o comando pre-commit gc para limpar repositórios que não estão mais em uso.
Retrocompatibilidade#
Por favor, mantenha a compatibilidade com versões anteriores tanto quanto possível. Se considerar que uma alteração é necessária, explique claramente o motivo no pull request. Além disso, tenha cuidado ao alterar assinaturas de métodos e adicione avisos de depreciação quando necessário. Adicione também diretivas de depreciação do Sphinx para funções ou métodos obsoletos.
Você também precisa
Escreva um novo caso de teste em que um aviso seja emitido ao chamar um parâmetro obsoleto.
Atualize todos os exemplos de teste e códigos existentes do Xinference para usar os novos parâmetros.
Type hints#
Xinference incentiva fortemente o uso de dicas de tipo no estilo PEP 484. Novos desenvolvimentos devem incluir dicas de tipo, e pull requests que anotem código existente também são aceitáveis!
Desenvolvimento Orientado a Testes#
O Xinference dá grande importância aos testes e incentiva fortemente os contribuidores a adotarem o Desenvolvimento Orientado por Testes (TDD). Esse processo de desenvolvimento “depende da repetição de ciclos de desenvolvimento muito curtos: primeiro, o desenvolvedor escreve um caso de teste automatizado (inicialmente falho) para definir a melhoria ou nova funcionalidade desejada, e depois usa o mínimo de código para passar nesse teste.” Portanto, antes de realmente escrever qualquer código, você deve escrever seus casos de teste. Normalmente, os casos de teste podem ser obtidos a partir da issue original do GitHub. No entanto, vale a pena considerar situações adicionais e escrever os casos de teste correspondentes.
Após enviar o código para o Xinference, frequentemente é solicitado adicionar exemplos de teste. Portanto, é muito importante adquirir o hábito de escrever exemplos de teste com antecedência, para que não surjam problemas.