Skip to content

Latest commit

 

History

History
281 lines (186 loc) · 9.17 KB

CONTRIBUTING.md

File metadata and controls

281 lines (186 loc) · 9.17 KB
Raw

PORTUGUÊS | ENGLISH

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 PyFlunt 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 PyFlunt:

$ cd pyflunt

E crie um novo branch:

$ git checkout -b <issue_number>

7. Execute o PyFlunt Localmente

Instalação

Requisitos

Crie um virtualenv para o PyFlunt e ative-o:

$ poetry shell

Instale as dependências:

$ poetry install
$ poetry pre-commit-install

Utilizando Localmente

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

Testes

$ poetry 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

    Methods:
	-------
    - foobar(w): Short explanation here

    """

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

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

        Parameters
		----------
        `w`: str
            Short explanation here

        Returns:
        --------
        `value`: str
            Short explanation here

        Notes:
        ------
        - Describe conditions here

        Exemples:
        ---------
        ```python
        obj = Exemple(1)
        obj.foobar(2)  >> Returns
        ```
        """
        ...
        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 poetry 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

Atualizar Workflow

Edite o arquivo release.yml na linha 46 com a nova versão (ex: v2.0.0), linha 47 com o nome da release (ex: Release v2.0.0) e da linha 49 em diante adicione o trecho do changelog alterado. release.yml

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

Após aprovação da PR e merge na main o lançamento da nova versão em produção será feita automaticamente via Github Actions.

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 PyFlunt do PyPI e teste se tudo está funcionando conforme o esperado.