From bfca220dbe411dd9745c1815502b5cefff5cc137 Mon Sep 17 00:00:00 2001 From: Camila Maia Date: Fri, 22 Sep 2023 13:34:54 +0100 Subject: [PATCH] Adicionar instrucoes de como criar o primeiro PR (#160) --- CONTRIBUTING.md | 183 ++++++++++++++++++++++++++++++++++++++++----- CONTRIBUTING_EN.md | 164 ++++++++++++++++++++++++++++++++++++++-- 2 files changed, 322 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b99b392..bd7a1031 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,83 @@ -# Contributing +# Contribuindo -Obrigada por disponibilizar seu tempo para contribuir! 🙇‍♀️🙇‍♂️ Toda ajuda é bem-vinda! +Obrigado por dedicar o seu tempo para contribuir! 🙇‍♀️🙇‍♂️ Toda ajuda é bem-vinda! -## Instalação -### Requisitos -- [Python 3.7+][python] -- [Poetry][poetry] +# Primeiro Pull Request -'Fork' ou clone o repositório e entre na pasta do projeto: +Como enviar um pull request: -```shell -$ git clone git@github.com:brazilian-utils/brutils-python.git +- [1. Crie uma Conta no GitHub](#1-crie-uma-conta-no-github) +- [2. Encontre uma Issue para Trabalhar](#2-encontre-uma-issue-para-trabalhar) +- [3. Instale o Git](#3-instale-o-git) +- [4. Faça um Fork do Projeto](#4-faça-um-fork-do-projeto) +- [5. Clone o Seu Fork](#5-clone-o-seu-fork) +- [6. Crie um Novo Branch](#6-crie-um-novo-branch) +- [7. Execute o brutils Localmente](#7-execute-o-brutils-localmente) +- [8. Faça as Suas Alterações](#8-faça-as-suas-alterações) +- [9. Teste as Suas Alterações](#9-teste-as-suas-alterações) +- [10. Faça o Commit e Envie as Suas Alterações](#10-faça-o-commit-e-envie-as-suas-alterações) +- [11. Adicione Entradas no Changelog](#11-adicione-entradas-no-changelog) +- [12. Crie um PR no GitHub](#12-crie-um-pr-no-github) +- [13. Atualize o Seu Branch se Necessário](#13-atualize-o-seu-branch-se-necessário) + +### 1. Crie uma Conta no GitHub + +Certifique-se de ter uma [conta no GitHub][github-join] e esteja logado nela. + +### 2. Encontre uma Issue para Trabalhar + +Visite a [página de issues do brutils][brutils-issues] 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. + +### 3. Instale o Git + +Certifique-se de ter o [Git instalado][install-git]. + +### 4. Faça um Fork do Projeto + +[Faça um fork do repositório brutils][github-forking]. + +### 5. Clone o Seu Fork + +[Clone][github-cloning] o seu fork localmente. + +### 6. Crie um Novo Branch + +Entre na pasta do brutils: + +```bash $ cd brutils-python ``` -Crie uma [virtualenv][virtualenv] para brutils e ative: +E crie um novo branch: + +```bash +$ git checkout -b +``` + +### 7. Execute o brutils Localmente +## Instalação +### Requisitos + +- [Python 3.7+][python] +- [Poetry][poetry] + +Crie um [virtualenv][virtualenv] para o brutils e ative-o: ```shell $ make shell ``` -**Nota: Você vai precisar rodar `make shell` todas as vezes que abrir um novo terminal.** +**Observação: Você precisa executar `make shell` toda vez que abrir uma nova janela ou aba do terminal.** Instale as dependências: @@ -28,13 +85,9 @@ Instale as dependências: $ make install ``` -## Usando localmente - -```shell -$ make run-python -``` +## Utilizando Localmente -Agora, você pode usá-lo [da mesma forma descrita no arquivo README.md](/README.md#usage) +Agora você pode usá-lo [da mesma forma descrita no arquivo README.md](/README.md#utilização). ## Testes @@ -42,6 +95,102 @@ Agora, você pode usá-lo [da mesma forma descrita no arquivo README.md](/README $ 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][docstring-definition]. +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: + +```python +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: + +```bash +$ git commit -a -m "" +``` + +Push o seu commit para o GitHub: + +```bash +$ git push --set-upstream origin +``` + +Crie a quantidade de alterações/commits que você precisa e os envie. + +### 11. Adicione Entradas no Changelog + +[Adicione uma entrada no CHANGELOG][keep-a-changelog]. + +### 12. Crie um PR no GitHub + +[Crie um PR no GitHub][github-creating-a-pr]. + +### 13. Atualize o Seu Branch se Necessário + +[Certifique-se de que seu branch esteja atualizado com o main][github-sync-pr] + +[brutils-issues]: https://github.com/brazilian-utils/brutils-python/issues +[docstring-definition]: https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring +[github-cloning]: https://docs.github.com/pt/repositories/creating-and-managing-repositories/cloning-a-repository +[github-creating-a-pr]: https://docs.github.com/pt/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request +[github-forking]: https://docs.github.com/pt/get-started/quickstart/contributing-to-projects +[github-join]: https://github.com/join +[github-sync-pr]: https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch +[install-git]: https://git-scm.com/book/pt-br/v2/Come%C3%A7ando-Instalando-o-Git +[keep-a-changelog]: https://keepachangelog.com/pt-BR/1.0.0/ [poetry]: https://python-poetry.org/docs/#installation [python]: https://www.python.org/downloads/ [virtualenv]: https://virtualenv.pypa.io/en/latest/ diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md index 8ba4a3b2..c8bbe83a 100644 --- a/CONTRIBUTING_EN.md +++ b/CONTRIBUTING_EN.md @@ -2,18 +2,74 @@ Thanks for taking the time to contribute! 🙇‍♀️🙇‍♂️ Every little bit of help counts! -## Installation -### Requirements -- [Python 3.7+][python] -- [Poetry][poetry] +# First Pull Request -Fork or clone the repository and enter into the project's folder: +How to submit a pull request: -```shell -$ git clone git@github.com:brazilian-utils/brutils-python.git +- [1. Create a GitHub Account](#1-create-a-github-account) +- [2. Find an Issue to Work With](#2-find-an-issue-to-work-with) +- [3. Install Git](#3-install-git) +- [4. Fork the Project](#4-fork-the-project) +- [5. Clone your Fork](#5-clone-your-fork) +- [6. Create a New Branch](#6-create-a-new-branch) +- [7. Run brutils locally](#7-run-brutils-locally) +- [8. Make your changes](#8-make-your-changes) +- [9. Test your changes](#9-test-your-changes) +- [10. Commit and push your changes](#10-commit-and-push-your-changes) +- [11. Add changelog entries](#11-add-changelog-entries) +- [12. Create a GitHub PR](#12-create-a-github-pr) +- [13. Update your branch if needed.](#13-update-your-branch-if-needed) + +### 1. Create a GitHub Account + +Make sure you have a [GitHub account][github-join] and you are logged in with it. + +### 2. Find an Issue to Work With + +Visit the [brutils issues page][brutils-issues] and find an issue you would like to work with +and no one assigned to it yet. + +Send a comment in the issue asking to work with it. Something like: "hey, can I work on this?". + +Wait until someone assign you to the ticket. Once you are assigned to it, you can move to the next +step. + +Please, feel free to ask any questions in the issue's page before or during the development +process. + +### 3. Install Git + +Make sure you have [Git installed][install-git]. + +### 4. Fork the Project + +[Fork the brutils repository][github-forking]. + +### 5. Clone your Fork + +[Clone][github-cloning] your fork locally. + +### 6. Create a New Branch + +Go into the brutils folder: + +```bash $ cd brutils-python ``` +And create a new branch: + +```bash +$ git checkout -b +``` + +### 7. Run brutils locally +## Installation +### Requirements + +- [Python 3.7+][python] +- [Poetry][poetry] + Create a [virtualenv][virtualenv] for brutils and activate it: ```shell @@ -34,7 +90,7 @@ $ make install $ make run-python ``` -Now, you can use it [in the same way described in the README.md file](/README_EN.md#usage) +Now, you can use it [in the same way described in the README.md file](/README_EN.md#usage). ## Tests @@ -42,6 +98,98 @@ Now, you can use it [in the same way described in the README.md file](/README_EN $ make test ``` +### 8. Make your changes + +Now is the step where you can implement your changes in the code. + +It is important to notice that we document our code using [docstrings][docstring-definition]. +Modules, classes, functions, and methods should be documented. Your changes should also be well +documented and should reflect updated docstrings if any of the params were changed for a +class/attributes or even functions. + +We follow the given pattern below to keep consistency in the docstrings: + +```python +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 + +``` + +One last thing to keep in mind while self-documenting code with docstrings that you can ignore +docstrings in property decorators and magic methods. + +### 9. Test your changes + +#### Write new tests + +Make sure you have created the necessary tests for every new change you made. + +#### Make sure all tests passed + +Run all the tests with `make test` and make sure that they all passed. + +**PRs will not be merged if there is any test missing or failing.** + +### 10. Commit and push your changes + +Commit the changes: + +```bash +$ git commit -a -m "" +``` + +Push your commit to GitHub: + +```bash +$ git push --set-upstream origin +``` + +Create the number of changes/commits you need and push them. + +### 11. Add changelog entries + +[Add a CHANGELOG entry][keep-a-changelog]. + +### 12. Create a GitHub PR + +[Create a GitHub PR][github-creating-a-pr]. + +### 13. Update your branch if needed. + +[Make sure your branch is updated with main][github-sync-pr]. + +[brutils-issues]: https://github.com/brazilian-utils/brutils-python/issues +[docstring-definition]: https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring +[github-cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository +[github-creating-a-pr]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request +[github-forking]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects +[github-join]: https://github.com/join +[github-sync-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch +[install-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[keep-a-changelog]: https://keepachangelog.com/en/1.1.0/ [poetry]: https://python-poetry.org/docs/#installation [python]: https://www.python.org/downloads/ [virtualenv]: https://virtualenv.pypa.io/en/latest/