Skip to content

Latest commit

 

History

History
263 lines (170 loc) · 8.91 KB

CONTRIBUTING.md

File metadata and controls

263 lines (170 loc) · 8.91 KB

Contribuindo

Obrigado por dedicar o seu tempo para contribuir! 🙇‍♀️🙇‍♂️ Toda ajuda é bem-vinda!

Primeira Contribuição

Como fazer a sua primeira contribuição:

1. Crie uma Conta no GitHub

Certifique-se de ter uma conta no GitHub e esteja logado nela.

2. Encontre uma Issue para Trabalhar

Visite a página de issues do brutils e encontre uma issue com a qual você gostaria de trabalhar e que ainda não tenha sido atribuída a ninguém.

Deixe um comentário na issue perguntando se você pode trabalhar nela. Algo como: "Olá, posso trabalhar nessa issue?".

Aguarde até que alguém atribua a issue a você. Uma vez atribuída, você pode prosseguir para a próxima etapa.

Sinta-se à vontade para fazer qualquer pergunta na página da issue antes ou durante o processo de desenvolvimento.

Ao começar a contribuir para o projeto, é recomendável que você pegue uma issue por vez. Isso ajuda a garantir que outras pessoas também tenham a oportunidade de colaborar e evita que recursos fiquem inativos por muito tempo.

3. Instale o Git

Certifique-se de ter o Git instalado.

4. Faça um Fork do Projeto

Faça um fork do repositório brutils.

5. Clone o Seu Fork

Clone o seu fork localmente.

6. Crie um Novo Branch

Entre na pasta do brutils:

$ cd brutils-python

E crie um novo branch:

$ git checkout -b <issue_number>

7. Execute o brutils Localmente

Instalação

Requisitos

Crie um virtualenv para o brutils e ative-o:

$ make shell

Observação: Você precisa executar make shell toda vez que abrir uma nova janela ou aba do terminal.

Instale as dependências:

$ make install

Utilizando Localmente

Agora você pode usá-lo da mesma forma descrita no arquivo README.md.

Testes

$ make test

8. Faça as Suas Alterações

Agora é a etapa em que você pode implementar as suas alterações no código.

É importante notar que documentamos o nosso código usando docstrings. Módulos, classes, funções e métodos devem ser documentados. Suas alterações também devem ser bem documentadas e refletir docstrings atualizadas, caso algum dos parâmetros tenha sido alterado para um classe/atributo ou mesmo funções.

Todas as docstring devem estar em Inglês. Fique à vontade para utilizar o Google Tradutor caso precise. Iremos sugerir mudanças na tradução se necessário, então não se preocupe com possíveis erros de inglês.

Seguimos o padrão abaixo para manter consistência nas docstrings:

class Example:
    """Explain the purpose of the class

    Attributes:
        x[dict]: Short explanation here
        y[type, optional]: Short explanation here

    """

    def __init__(self, x, y=None):
        self.x = x
        self.y = y

    def foobar(self, w):
        """Purpose if the function

        Args:
            w[str]: Short explanation here

        Returns:
            value[str]: Short explanation here

        """
        ...
        return value

Algo a se ter em mente ao documentar o código com docstrings é que você pode ignorar docstrings em decoradores de propriedade e métodos mágicos.

9. Teste as Suas Alterações

Escreva Novos Testes

Certifique-se de ter criado os testes necessários para cada nova alteração que você fez.

Certifique-se de que Todos os Testes Passaram

Execute todos os testes com make test e certifique-se de que todos passaram.

Os PRs não serão mesclados se houver algum teste faltando ou falhando.

10. Faça o Commit e Envie as Suas Alterações

Faça o commit das alterações:

$ git commit -a -m "<commit_message>"

Push o seu commit para o GitHub:

$ git push --set-upstream origin <issue_number>

Crie a quantidade de alterações/commits que você precisa e os envie.

11. Adicione Entradas no CHANGELOG.md

Adicione uma entrada no CHANGELOG.md.

12. Crie um PR no GitHub

Crie um PR no GitHub.

13. Atualize o Seu Branch se Necessário

Certifique-se de que seu branch esteja atualizado com o main

Lançar uma Nova Versão

Aqui você encontrará como lançar uma nova versão em produção do brutils:

1. Criar uma Issue de Release

Crie a Issue

Para a criação da issue, pode ser utilizado o template de feature, sendo o nome da issue Release v<versão>. Exemplo

Crie uma Branch

O nome da branch criada para o release é relacionado ao número da Issue, como mostra este exemplo

2. Criar um Release PR

Atualizar a Versão da Biblioteca

Incremente o número da versão, seguindo o Versionamento Semântico, no arquivo pyproject.toml:

Atualizar o CHANGELOG.md

Adicione um título para a nova versão com o novo número e a data atual, como neste exemplo.

E adicione os links da versão, como neste exemplo

Crie o PR

Crie um PR com o nome Release v<versão> contendo as duas alterações acima. Na descrição da Pull Request, adicione o trecho do changelog alterado.

Exemplo de Release PR

Faça o Merge do PR

Assim que o PR for aceito e passar em todas as verificações, faça o merge.

3. Deploy via GitHub

O lançamento da nova versão em produção é feita automaticamente quando uma nova release é criada no GitHub.

  • Preencha o campo tag version com: v<versão> (por exemplo, v2.0.0).
  • Preencha o campo release title com o mesmo valor que a versão da tag (por exemplo, v2.0.0).
  • Preencha o campo release description com o conteúdo copiado do arquivo CHANGELOG.md da seção de versão correspondente.

Exemplos reais estão disponíveis em: https://github.com/brazilian-utils/brutils-python/releases

Quando o Deploy via GitHub for concluído, a nova versão também será lançada automaticamente no PyPI. Baixe a nova versão do brutils do PyPI e teste se tudo está funcionando conforme o esperado.