Guia do Contribuidor

Obrigado pelo seu interesse em melhorar este projeto. Este projeto é de código aberto sob a licença GPL-3 e contribuições são bem-vindas na forma de relatórios de bugs, solicitações de recursos e pull requests.

Aqui está uma lista de recursos importantes para contribuidores:

Issues🔗

Issues pode ser usado para sugestões de melhorias, relatórios de bugs e dúvidas.

Como relatar um bug🔗

Reportar bugs em Issues.

Ao registrar um problema, certifique-se de responder a estas perguntas:

Qual sistema operacional e versão do Python você está usando?
Qual versão deste projeto você está usando?
O que você fez?
O que você esperava ver?
O que você viu em vez disso?

A melhor maneira de corrigir seu bug é fornecer um caso de teste e/ou etapas para reproduzir o problema.

Como configurar seu ambiente de desenvolvimento🔗

Você precisa do Python 3.9+, poetry e Nox.

Como testar o projeto🔗

Execute o conjunto de testes completo:

nox -s tests

Execute os testes para apenas uma versão do Python:

nox -s tests -p 3.13

Execute os testes para apenas um entre o renardo e o foxdot:

nox -t renardo
nox -t foxdot

Os testes de unidade estão localizados no diretório tests/ e são escritos usando a estrutura de testes pytest.

Como documentar as alterações🔗

Esta sendo usado o mkdocs-material para criar a documetação do projeto junto do mkdocstrings para documentar a API no formato numpydoc.

A documentação do projeto está localizado no diretório docs/. Num primeiro momento, caso sejá preciso mexer nela, isso pode ser feito apenas em docs/en/ em inglês.

A documentação da API é feito na próprio docstring no padrão numpydoc.

Você pode subir um servidor da documentação localmente para ver as alterações em tempo real antes de submetê-las. Use o comando abaixo para iniciar o servidor:

nox -s docs

Traduções🔗

Contruições nas traduções são sempre bem-vindas.

O plugin do mkdocs mkdocs-static-i18n é usado para criar a estrutura de tradução. No arquivo mkdocs.yml na seção plugins esta localizado as configurações de internacionalização. Um ponto de atenção é o languages, caso você for adicionar um novo idioma, começe por lá:

Exemplo:

plugins:
  - i18n:
      # ...
      languages:
        - locale: en
          default: true
          name: English
        - locale: es
          name: Español

Você também pode traduzir a descrição do site e sua barra de navegação.

plugins:
  - i18n:
      # ...
      languages:
        - locale: en
          default: true
          name: English
        - locale: es
          name: Español
          nav_translations:
            "Contributor Guide": Guía para Contribuyentes

Após isso crie um diretório com o mesmo nome do locale em questão dentro do docs/.

mkdir docs/es

A estrutura de arquivos desse diretório deve seguir a mesma que as outras (pelo menos a seção que for ser traduzida, caso não exista será usada a seção padrão em inglês).

docs
├── assets
│  ...
├── en
│  ├── api
│  │  ├── chord.md
│  │  └── pchord.md
│  ├── changelog.md
│  ├── contributing.md
│  ├── index.md
│  └── tutorial
│     ├── theory.md
│     └── usage.md
└── es
   ├── contributing.md
   ├── index.md
   └── tutorial
      ├── theory.md
      └── usage.md

Dessa forma a internacionalização pode ser feita.

Como enviar alterações🔗

Abra um pull request para enviar alterações a este projeto.

Seu pull request precisa atender às seguintes diretrizes para ser aceito:

O CI deve passar sem erros e avisos.
Inclui testes unitários. Este projeto mantém a cobertura do código.
Se suas alterações adicionarem funcionalidade, atualize a documentação adequadamente.

Sinta-se à vontade para enviar com antecedência - sempre podemos repetir isso.