From 00ff3ec4140aa9229f4ea83c9da1af6449005fdb Mon Sep 17 00:00:00 2001 From: Camila Maia Date: Fri, 22 Sep 2023 15:49:27 +0100 Subject: [PATCH] Adicionando instrucoes de como lancar uma nova versao (#161) --- CONTRIBUTING.md | 64 ++++++++++++++++++++++++++++++++++++++++++---- CONTRIBUTING_EN.md | 59 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 115 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd7a1031..669eb83e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,9 +2,11 @@ Obrigado por dedicar o seu tempo para contribuir! 🙇‍♀️🙇‍♂️ Toda ajuda é bem-vinda! -# Primeiro Pull Request +- [Primeira Contribuição](#primeira-contribuição) +- [Lançar uma Nova Versão](#lançar-uma-nova-versão) +# Primeira Contribuição -Como enviar um pull request: +Como fazer a sua primeira contribuição: - [1. Crie uma Conta no GitHub](#1-crie-uma-conta-no-github) - [2. Encontre uma Issue para Trabalhar](#2-encontre-uma-issue-para-trabalhar) @@ -16,7 +18,7 @@ Como enviar um pull request: - [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) +- [11. Adicione Entradas no CHANGELOG.md](#11-adicione-entradas-no-changelogmd) - [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) @@ -170,9 +172,9 @@ $ git push --set-upstream origin Crie a quantidade de alterações/commits que você precisa e os envie. -### 11. Adicione Entradas no Changelog +### 11. Adicione Entradas no CHANGELOG.md -[Adicione uma entrada no CHANGELOG][keep-a-changelog]. +[Adicione uma entrada no CHANGELOG.md][keep-a-changelog]. ### 12. Crie um PR no GitHub @@ -182,7 +184,58 @@ Crie a quantidade de alterações/commits que você precisa e os envie. [Certifique-se de que seu branch esteja atualizado com o main][github-sync-pr] +# Lançar uma Nova Versão + +Aqui você encontrará como lançar uma nova versão em produção do brutils: + +- [1. Criar um Release PR](#1-criar-um-release-pr) +- [2. Deploy via GitHub](#2-deploy-via-github) + +### 1. Criar um Release PR + +#### Atualizar a Versão da Biblioteca + +Incremente o número da versão, seguindo o [Versionamento Semântico][semantic-versioning], +no arquivo `pyproject.toml`: + +- https://github.com/brazilian-utils/brutils-python/blob/main/pyproject.toml#L3 + +#### 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](https://github.com/brazilian-utils/brutils-python/blob/main/CHANGELOG.md?plain=1#L9). + +E adicione os links da versão, como [neste exemplo](https://github.com/brazilian-utils/brutils-python/blob/bc10b7242bd939cc445070f7e937e3ad187ff95a/CHANGELOG.md?plain=1#L33-L34) + +#### Crie o PR + +Crie um PR com o nome `Release v` contendo as duas alterações acima. + +[Exemplo de Release PR](https://github.com/brazilian-utils/brutils-python/pull/128) + +#### Faça o Merge do PR + +Assim que o PR for aceito e passar em todas as verificações, faça o merge. + +### 2. Deploy via GitHub + +O lançamento da nova versão em produção é feita automaticamente quando uma +[nova release é criada][creating-releases] no GitHub. + +- Preencha o campo `tag version` com: `v` (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][brutils-on-pypi]. Baixe a nova versão do brutils do PyPI e teste se tudo está +funcionando conforme o esperado. + [brutils-issues]: https://github.com/brazilian-utils/brutils-python/issues +[brutils-on-pypi]: https://pypi.org/project/brutils/ +[creating-releases]: https://docs.github.com/pt/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release [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 @@ -193,4 +246,5 @@ Crie a quantidade de alterações/commits que você precisa e os envie. [keep-a-changelog]: https://keepachangelog.com/pt-BR/1.0.0/ [poetry]: https://python-poetry.org/docs/#installation [python]: https://www.python.org/downloads/ +[semantic-versioning]: https://semver.org/lang/pt-BR/ [virtualenv]: https://virtualenv.pypa.io/en/latest/ diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md index c8bbe83a..5c46dcec 100644 --- a/CONTRIBUTING_EN.md +++ b/CONTRIBUTING_EN.md @@ -2,9 +2,12 @@ Thanks for taking the time to contribute! 🙇‍♀️🙇‍♂️ Every little bit of help counts! -# First Pull Request +- [First Contribution](#first-contribution) +- [Release a New Version](#release-a-new-version) -How to submit a pull request: +# First Contribution + +How to make your first contribution: - [1. Create a GitHub Account](#1-create-a-github-account) - [2. Find an Issue to Work With](#2-find-an-issue-to-work-with) @@ -171,7 +174,7 @@ Create the number of changes/commits you need and push them. ### 11. Add changelog entries -[Add a CHANGELOG entry][keep-a-changelog]. +[Add a changelog entry][keep-a-changelog] to CHANGELOG.md. ### 12. Create a GitHub PR @@ -181,7 +184,56 @@ Create the number of changes/commits you need and push them. [Make sure your branch is updated with main][github-sync-pr]. +# Release a New Version + +Here you will find how to deploy a new production version of brutils: + +- [1. Create a Release PR](#1-create-a-release-pr) +- [2. Deploy via GitHub](#2-deploy-via-github) + +### 1. Create a Release PR + +#### Bump the lib Version + +Increment the version number, following the [Semantic Versioning][semantic-versioning], +in the `pyproject.toml` file: https://github.com/brazilian-utils/brutils-python/blob/main/pyproject.toml#L3 + +#### Update the CHANGELOG.md + +Add a new version title with the new version number and the current date, like +[this](https://github.com/brazilian-utils/brutils-python/blob/main/CHANGELOG.md?plain=1#L9). + +And add the version links, like [this](https://github.com/brazilian-utils/brutils-python/blob/bc10b7242bd939cc445070f7e937e3ad187ff95a/CHANGELOG.md?plain=1#L33-L34) + +#### Create the PR + +Create a PR named `Release v` containing these two changes above. + +[Example of Release PR](https://github.com/brazilian-utils/brutils-python/pull/128) + +#### Merge the PR + +Once the PR has been accepted and passed on all checks, merge it. + +### 2. Deploy via GitHub + +Deploy production is automatically done when a [new release is created][creating-releases] on GitHub. + +- The `tag version` should be `v` (e.g `v2.0.0`). +- The `release title` should be the same as tag version (e.g `v2.0.0`). +- The `release description` should be the content copied from the CHANGELOG.md file from the +corresponding version section. + +Real examples are available at: https://github.com/brazilian-utils/brutils-python/releases + +When the Deploy on GitHub is done, the new version will be also automatically deployed on +[PyPI][brutils-on-pypi]. Download the new brutils version from PyPI and test if everything is +working as expected. + + [brutils-issues]: https://github.com/brazilian-utils/brutils-python/issues +[brutils-on-pypi]: https://pypi.org/project/brutils/ +[creating-releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release [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 @@ -192,4 +244,5 @@ Create the number of changes/commits you need and push them. [keep-a-changelog]: https://keepachangelog.com/en/1.1.0/ [poetry]: https://python-poetry.org/docs/#installation [python]: https://www.python.org/downloads/ +[semantic-versioning]: https://semver.org/ [virtualenv]: https://virtualenv.pypa.io/en/latest/