diff --git a/.github/workflows/update-changelog.yml b/.github/workflows/update-changelog.yml new file mode 100644 index 0000000..baa7e70 --- /dev/null +++ b/.github/workflows/update-changelog.yml @@ -0,0 +1,55 @@ +name: Update Changelog + +on: + push: + branches: + - main + +permissions: + contents: write + +jobs: + update-changelog: + name: Update Unreleased section + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Generate GitHub App Token + id: generate-token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.APP_CHANGELOG_ID }} + private-key: ${{ secrets.APP_CHANGELOG_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 0 + token: ${{ steps.generate-token.outputs.token }} + + - name: Generate changelog for Unreleased + uses: orhun/git-cliff-action@v4 + with: + config: pyproject.toml + args: --verbose --github-token ${{ secrets.GITHUB_TOKEN }} + env: + OUTPUT: CHANGELOG.md + GITHUB_REPO: ${{ github.repository }} + + - name: Check for changes + id: check-changes + run: | + if git diff --quiet CHANGELOG.md; then + echo "has_changes=false" >> $GITHUB_OUTPUT + else + echo "has_changes=true" >> $GITHUB_OUTPUT + fi + + - name: Commit and push changes + if: steps.check-changes.outputs.has_changes == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add CHANGELOG.md + git commit -m "docs: update CHANGELOG.md [skip ci]" + git push diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a6d24f..47d5149 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,121 +8,175 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added - -- Utilitário `convert_name_to_uf` -- Utilitário `is_valid_legal_nature` [#641](https://github.com/brazilian-utils/python/issues/641) -- Utilitário `get_legal_nature_description` [#641](https://github.com/brazilian-utils/python/issues/641) -- Utilitário `list_all_legal_nature` [#641](https://github.com/brazilian-utils/python/issues/641) -- Utilitário `is_valid_cnh` [#651](https://github.com/brazilian-utils/brutils-python/pull/651) -- Utilitário `is_valid_renavam` [#652](https://github.com/brazilian-utils/brutils-python/pull/652) - -### Fixed - -- Suporte a anotações modernas no `brutils/cep.py` [#637](https://github.com/brazilian-utils/python/pull/637) +- Automatiza geração do CHANGELOG com git-cliff +- Add close-stale-issues-v1.yml by @niltonpimentel02 in [#661](https://github.com/brazilian-utils/python/pull/661) +- Add Natureza Jurídica utilities by @MatheusPaivaa in [#653](https://github.com/brazilian-utils/python/pull/653) +- Renavam add is_valid_renavam function with validation, tests, and docs by @Fontebasso-JV in [#652](https://github.com/brazilian-utils/python/pull/652) +- Adiciona suporte a anotações modernas em voter_id by @felipecolen in [#638](https://github.com/brazilian-utils/python/pull/638) +- Adiciona suporte a anotações modernas em legal_process by @felipecolen in [#634](https://github.com/brazilian-utils/python/pull/634) +- CNH add is_valid_cnh function with validation, tests, and docs by @willkraemer in [#651](https://github.com/brazilian-utils/python/pull/651) +- Adiciona utilitário convert_name_to_uf by @morais90 in [#606](https://github.com/brazilian-utils/python/pull/606) + +### Changed +- Remover diretório 'types' que não está mais sendo utilizado by @rochamrcs in [#650](https://github.com/brazilian-utils/python/pull/650) +- Migrar type hints de license_plate.py de acordo com PEP 484 by @lucasjl in [#646](https://github.com/brazilian-utils/python/pull/646) +- Migração de type hints para anotações modernas by @camilotmundim in [#637](https://github.com/brazilian-utils/python/pull/637) +- Adiciona suporte a anotações modernas em phone.py by @willkraemer in [#636](https://github.com/brazilian-utils/python/pull/636) +- Adiciona img de capa aos arquivos README by @camilamaia in [#612](https://github.com/brazilian-utils/python/pull/612) +- Add commit message for release pr by @niltonpimentel02 in [#602](https://github.com/brazilian-utils/python/pull/602) ### Fixed - -- Suporte a anotações modernas `legal_process` [#622](https://github.com/brazilian-utils/brutils-python/pull/634) - -### Fixed - -- Suporte a anotações modernas `voter_id` [#623](https://github.com/brazilian-utils/brutils-python/pull/638) +- Corrigir conflito entre módulo local types e módulo padrão types by @rochamrcs in [#647](https://github.com/brazilian-utils/python/pull/647) +- Teste intermitente by @camilamaia in [#605](https://github.com/brazilian-utils/python/pull/605) +- Add new options to bot by @niltonpimentel02 in [#603](https://github.com/brazilian-utils/python/pull/603) +- Delete cleanup-inactive-issues.yml by @niltonpimentel02 in [#600](https://github.com/brazilian-utils/python/pull/600) +- Delete stale.yml by @niltonpimentel02 in [#598](https://github.com/brazilian-utils/python/pull/598) + +### New Contributors +* @MatheusPaivaa made their first contribution in [#653](https://github.com/brazilian-utils/python/pull/653) +* @Fontebasso-JV made their first contribution in [#652](https://github.com/brazilian-utils/python/pull/652) +* @felipecolen made their first contribution in [#638](https://github.com/brazilian-utils/python/pull/638) +* @willkraemer made their first contribution in [#651](https://github.com/brazilian-utils/python/pull/651) +* @rochamrcs made their first contribution in [#650](https://github.com/brazilian-utils/python/pull/650) +* @lucasjl made their first contribution in [#646](https://github.com/brazilian-utils/python/pull/646) +* @ronaldofas made their first contribution in [#643](https://github.com/brazilian-utils/python/pull/643) +* @camilotmundim made their first contribution in [#637](https://github.com/brazilian-utils/python/pull/637) +* @luizweb made their first contribution in [#645](https://github.com/brazilian-utils/python/pull/645) +* @guyrux made their first contribution in [#640](https://github.com/brazilian-utils/python/pull/640) ## [2.3.0] - 2025-10-07 ### Added - -- Utilitário `convert_code_to_uf` [#410](https://github.com/brazilian-utils/brutils-python/pull/410) -- Utilitário `is_holiday` [#446](https://github.com/brazilian-utils/brutils-python/pull/446) -- Utilitário `convert_date_to_text`[#415](https://github.com/brazilian-utils/brutils-python/pull/415) -- Utilitário `get_municipality_by_code` [412](https://github.com/brazilian-utils/brutils-python/pull/412) -- Utilitário `get_code_by_municipality_name` [#411](https://github.com/brazilian-utils/brutils-python/pull/411) -- Utilitário `format_currency` [#434](https://github.com/brazilian-utils/brutils-python/pull/434) -- Utilitário `convert_real_to_text` [#525](https://github.com/brazilian-utils/brutils-python/pull/525) -- Utilitário `convert_uf_to_name` [#554](https://github.com/brazilian-utils/brutils-python/pull/554) - -### Deprecated - -- **BREAKING CHANGES** Suporte ao Python 3.8 [#236](https://github.com/brazilian-utils/brutils-python/pull/561) -- **BREAKING CHANGES** Suporte ao Python 3.9 [#236](https://github.com/brazilian-utils/brutils-python/pull/561) +- Remove deprecated python versions by @niltonpimentel02 in [#561](https://github.com/brazilian-utils/python/pull/561) +- Add convert_uf_to_name by @niltonpimentel02 in [#554](https://github.com/brazilian-utils/python/pull/554) +- Add validate-pr-title-v1.yml by @niltonpimentel02 in [#553](https://github.com/brazilian-utils/python/pull/553) +- Conversão de Moeda Real para Texto by @dinalivia in [#525](https://github.com/brazilian-utils/python/pull/525) +- Adicionar automação para gerenciar PRs inativos com GitHub Actions by @tiagornandrade in [#479](https://github.com/brazilian-utils/python/pull/479) +- Retorna codigo do ibge do nome do municipio e da uf by @CarduCaldeira in [#411](https://github.com/brazilian-utils/python/pull/411) + +### Changed +- Busca de municípios by @camilamaia in [#595](https://github.com/brazilian-utils/python/pull/595) +- Improve functions format_currency, convert_real_to_text and tests by @niltonpimentel02 in [#577](https://github.com/brazilian-utils/python/pull/577) +- Unifica date e date-utils by @camilamaia in [#576](https://github.com/brazilian-utils/python/pull/576) +- Módulo uf.py by @camilamaia in [#575](https://github.com/brazilian-utils/python/pull/575) +- Add new contact method by @niltonpimentel02 in [#570](https://github.com/brazilian-utils/python/pull/570) +- Update convert_date_to_text to return None when invalid input by @niltonpimentel02 in [#569](https://github.com/brazilian-utils/python/pull/569) +- Padroniza changelog by @camilamaia in [#560](https://github.com/brazilian-utils/python/pull/560) +- Arruma a ordem dos utilitários do IBGE by @camilamaia in [#557](https://github.com/brazilian-utils/python/pull/557) +- Adicionando MAINTAINING.md by @camilamaia in [#427](https://github.com/brazilian-utils/python/pull/427) + +### New Contributors +* @niltonpimentel02 made their first contribution in [#596](https://github.com/brazilian-utils/python/pull/596) +* @renata-machado made their first contribution in [#500](https://github.com/brazilian-utils/python/pull/500) +* @gabriel-lima258 made their first contribution in [#532](https://github.com/brazilian-utils/python/pull/532) +* @laistdomiciano made their first contribution in [#530](https://github.com/brazilian-utils/python/pull/530) +* @Joaolpridolficarvalho made their first contribution in [#516](https://github.com/brazilian-utils/python/pull/516) +* @dinalivia made their first contribution in [#525](https://github.com/brazilian-utils/python/pull/525) +* @tiagornandrade made their first contribution in [#489](https://github.com/brazilian-utils/python/pull/489) +* @devid8642 made their first contribution in [#491](https://github.com/brazilian-utils/python/pull/491) +* @jaimenunes made their first contribution in [#480](https://github.com/brazilian-utils/python/pull/480) +* @alphabraga made their first contribution in [#442](https://github.com/brazilian-utils/python/pull/442) +* @morais90 made their first contribution in [#434](https://github.com/brazilian-utils/python/pull/434) +* @vianaz made their first contribution in [#455](https://github.com/brazilian-utils/python/pull/455) +* @FloraSauerbronn made their first contribution in [#439](https://github.com/brazilian-utils/python/pull/439) +* @CarduCaldeira made their first contribution in [#411](https://github.com/brazilian-utils/python/pull/411) +* @BeneBr made their first contribution in [#415](https://github.com/brazilian-utils/python/pull/415) +* @carlos-moreno made their first contribution +* @melissawm made their first contribution in [#409](https://github.com/brazilian-utils/python/pull/409) ## [2.2.0] - 2024-09-12 -### Added - -- Utilitário `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) -- Utilitário `get_cep_information_from_address` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) -- Utilitário `format_voter_id` [#363](https://github.com/brazilian-utils/brutils-python/pull/363) -- Utilitário `generate_voter_id` [#220](https://github.com/brazilian-utils/brutils-python/pull/220) +### New Contributors +* @gtkacz made their first contribution in [#376](https://github.com/brazilian-utils/python/pull/376) ## [2.1.1] - 2024-01-06 -### Fixed - -- `generate_legal_process` [#325](https://github.com/brazilian-utils/brutils-python/pull/325) -- `is_valid_legal_process` [#325](https://github.com/brazilian-utils/brutils-python/pull/325) -- Import do utilitário `convert_license_plate_to_mercosul` [#324](https://github.com/brazilian-utils/brutils-python/pull/324) -- Import do utilitário `generate_license_plate` [#324](https://github.com/brazilian-utils/brutils-python/pull/324) -- Import do utilitário `get_format_license_plate` [#324](https://github.com/brazilian-utils/brutils-python/pull/324) - ## [2.1.0] - 2024-01-05 ### Added - -- Suporte ao Python 3.12 [#245](https://github.com/brazilian-utils/brutils-python/pull/245) -- Utilitário `convert_license_plate_to_mercosul` [#226](https://github.com/brazilian-utils/brutils-python/pull/226) -- Utilitário `format_license_plate` [#230](https://github.com/brazilian-utils/brutils-python/pull/230) -- Utilitário `format_phone` [#231](https://github.com/brazilian-utils/brutils-python/pull/231) -- Utilitário `format_pis` [#224](https://github.com/brazilian-utils/brutils-python/pull/224) -- Utilitário `format_legal_process` [#210](https://github.com/brazilian-utils/brutils-python/pull/210) -- Utilitário `generate_license_plate` [#241](https://github.com/brazilian-utils/brutils-python/pull/241) -- Utilitário `generate_phone` [#295](https://github.com/brazilian-utils/brutils-python/pull/295) -- Utilitário `generate_pis` [#218](https://github.com/brazilian-utils/brutils-python/pull/218) -- Utilitário `generate_legal_process` [#208](https://github.com/brazilian-utils/brutils-python/pull/208) -- Utilitário `get_format_license_plate` [#243](https://github.com/brazilian-utils/brutils-python/pull/243) -- Utilitário `is_valid_email` [#213](https://github.com/brazilian-utils/brutils-python/pull/213) -- Utilitário `is_valid_license_plate` [#237](https://github.com/brazilian-utils/brutils-python/pull/237) -- Utilitário `is_valid_phone` [#147](https://github.com/brazilian-utils/brutils-python/pull/147) -- Utilitário `is_valid_pis` [#216](https://github.com/brazilian-utils/brutils-python/pull/216) -- Utilitário `is_valid_legal_process` [#207](https://github.com/brazilian-utils/brutils-python/pull/207) -- Utilitário `is_valid_voter_id` [#235](https://github.com/brazilian-utils/brutils-python/pull/235) -- Utilitário `remove_international_dialing_code` [192](https://github.com/brazilian-utils/brutils-python/pull/192) -- Utilitário `remove_symbols_license_plate` [#182](https://github.com/brazilian-utils/brutils-python/pull/182) -- Utilitário `remove_symbols_phone` [#188](https://github.com/brazilian-utils/brutils-python/pull/188) -- Utilitário `remove_symbols_pis` [#236](https://github.com/brazilian-utils/brutils-python/pull/236) -- Utilitário `remove_symbols_legal_process` [#209](https://github.com/brazilian-utils/brutils-python/pull/209) - -### Removed - -- **BREAKING CHANGE** Suporte ao Python 3.7 [#236](https://github.com/brazilian-utils/brutils-python/pull/236) +- Gerar número de telefone fixo aleatório by @MarcelFox in [#249](https://github.com/brazilian-utils/python/pull/249) +- Suporte ao python 3.12 by @camilamaia in [#245](https://github.com/brazilian-utils/python/pull/245) +- Adiciona `format_pis` #206 by @patricia-salles in [#224](https://github.com/brazilian-utils/python/pull/224) +- Adiciona `get_license_plate_format` by @kaioduarte in [#243](https://github.com/brazilian-utils/python/pull/243) +- Add is_valid_license_plate by @kaioduarte in [#240](https://github.com/brazilian-utils/python/pull/240) +- Remover Símbolos do PIS by @kaioduarte in [#239](https://github.com/brazilian-utils/python/pull/239) +- Add generate_pis by @kaioduarte in [#218](https://github.com/brazilian-utils/python/pull/218) +- Add is_valid_pis by @kaioduarte in [#216](https://github.com/brazilian-utils/python/pull/216) +- Validate license plate by @hebertn88 in [#214](https://github.com/brazilian-utils/python/pull/214) +- Add is_email_valid by @Anurag-Nagpal in [#213](https://github.com/brazilian-utils/python/pull/213) + +### Changed +- Refactor no utilitário de validar título eleitoral by @camilamaia in [#296](https://github.com/brazilian-utils/python/pull/296) + +### Feature +- Titulo eleitoral by @VPeron in [#235](https://github.com/brazilian-utils/python/pull/235) +- Gerar um numero de celular aleatório #191 by @jhonatacaiob in [#232](https://github.com/brazilian-utils/python/pull/232) +- Formatando numero de telefone #189 by @jhonatacaiob in [#231](https://github.com/brazilian-utils/python/pull/231) +- Validação de telefone by @antoniamaia in [#150](https://github.com/brazilian-utils/python/pull/150) + +### Refactor +- Using regex to enhance phone validation by @antoniamaia in [#154](https://github.com/brazilian-utils/python/pull/154) +- Incluindo `Test` no nome das Classes by @antoniamaia in [#149](https://github.com/brazilian-utils/python/pull/149) +- Alterando os métodos de `assert` python para unittest by @antoniamaia in [#148](https://github.com/brazilian-utils/python/pull/148) + +### Doc +- Arrumando license_plate para ter apenas um método is_valid by @camilamaia in [#294](https://github.com/brazilian-utils/python/pull/294) + +### New Contributors +* @MarcelFox made their first contribution in [#291](https://github.com/brazilian-utils/python/pull/291) +* @joseevilasio made their first contribution in [#276](https://github.com/brazilian-utils/python/pull/276) +* @cuducos made their first contribution in [#273](https://github.com/brazilian-utils/python/pull/273) +* @VPeron made their first contribution in [#235](https://github.com/brazilian-utils/python/pull/235) +* @magnunleno made their first contribution in [#241](https://github.com/brazilian-utils/python/pull/241) +* @patricia-salles made their first contribution in [#224](https://github.com/brazilian-utils/python/pull/224) +* @jhonatacaiob made their first contribution in [#232](https://github.com/brazilian-utils/python/pull/232) +* @kaioduarte made their first contribution in [#243](https://github.com/brazilian-utils/python/pull/243) +* @pontes-guilherme made their first contribution in [#223](https://github.com/brazilian-utils/python/pull/223) +* @hebertn88 made their first contribution in [#214](https://github.com/brazilian-utils/python/pull/214) +* @Anurag-Nagpal made their first contribution in [#213](https://github.com/brazilian-utils/python/pull/213) +* @giovannism20 made their first contribution in [#188](https://github.com/brazilian-utils/python/pull/188) ## [2.0.0] - 2023-07-23 ### Added +- Add parse cnpj method by @antoniamaia in [#58](https://github.com/brazilian-utils/python/pull/58) +- Add parse_cpf by @camilamaia in [#57](https://github.com/brazilian-utils/python/pull/57) +- Is_valid_cnpj by @antoniamaia in [#36](https://github.com/brazilian-utils/python/pull/36) +- Is_valid_cpf by @camilamaia in [#34](https://github.com/brazilian-utils/python/pull/34) + +### Changed +- Create a folder with old documentation by @antoniamaia in [#71](https://github.com/brazilian-utils/python/pull/71) +- English readme by @camilamaia in [#60](https://github.com/brazilian-utils/python/pull/60) +- Improve imports usability for cnpj by @antoniamaia in [#48](https://github.com/brazilian-utils/python/pull/48) +- Improve imports usability for cpf by @camilamaia in [#47](https://github.com/brazilian-utils/python/pull/47) +- Add CONTRIBUTING.md by @camilamaia in [#28](https://github.com/brazilian-utils/python/pull/28) +- Change the default readme to the english one by @camilamaia +- Add black by @camilamaia in [#22](https://github.com/brazilian-utils/python/pull/22) +- Add FUNDING.yml by @camilamaia + +### Feature +- Implementando a função `remove_symbols_cep` by @antoniamaia in [#126](https://github.com/brazilian-utils/python/pull/126) +- Implementando o método `format_cep` by @antoniamaia in [#125](https://github.com/brazilian-utils/python/pull/125) +- `generate_cep` by @antoniamaia in [#124](https://github.com/brazilian-utils/python/pull/124) +- Validação CEP by @antoniamaia in [#123](https://github.com/brazilian-utils/python/pull/123) + +### Fixed +- Make install by @antoniamaia in [#32](https://github.com/brazilian-utils/python/pull/32) +- Fixed statistically negligible bug in generators by @luizberti + +### Packaging +- Remove python 2 from classifiers by @camilamaia + +### New Contributors +* @camilamaia made their first contribution in [#128](https://github.com/brazilian-utils/python/pull/128) +* @antoniamaia made their first contribution in [#126](https://github.com/brazilian-utils/python/pull/126) +* @dependabot[bot] made their first contribution in [#103](https://github.com/brazilian-utils/python/pull/103) +* @luizberti made their first contribution + +[unreleased]: https://github.com/brazilian-utils/python/compare/v2.3.0...HEAD +[2.3.0]: https://github.com/brazilian-utils/python/compare/v2.2.0...v2.3.0 +[2.2.0]: https://github.com/brazilian-utils/python/compare/v2.1.1...v2.2.0 +[2.1.1]: https://github.com/brazilian-utils/python/compare/v2.1.0...v2.1.1 +[2.1.0]: https://github.com/brazilian-utils/python/compare/v2.0.0...v2.1.0 -- Utilitário `is_valid_cep` [123](https://github.com/brazilian-utils/brutils-python/pull/123) -- Utilitário `format_cep` [125](https://github.com/brazilian-utils/brutils-python/pull/125) -- Utilitário `remove_symbols_cep` [126](https://github.com/brazilian-utils/brutils-python/pull/126) -- Utilitário `generate_cep` [124](https://github.com/brazilian-utils/brutils-python/pull/124) -- Utilitário `is_valid_cpf` [34](https://github.com/brazilian-utils/brutils-python/pull/34) -- Utilitário `format_cpf` [54](https://github.com/brazilian-utils/brutils-python/pull/54) -- Utilitário `remove_symbols_cpf` [57](https://github.com/brazilian-utils/brutils-python/pull/57) -- Utilitário `is_valid_cnpj` [36](https://github.com/brazilian-utils/brutils-python/pull/36) -- Utilitário `format_cnpj` [52](https://github.com/brazilian-utils/brutils-python/pull/52) -- Utilitário `remove_symbols_cnpj` [58](https://github.com/brazilian-utils/brutils-python/pull/58) - -### Deprecated - -- Utilitário `cpf.sieve` -- Utilitário `cpf.display` -- Utilitário `cpf.validate` -- Utilitário `cnpj.sieve` -- Utilitário `cnpj.display` -- Utilitário `cnpj.validate` - -[Unreleased]: https://github.com/brazilian-utils/brutils-python/compare/v2.3.0...HEAD -[2.3.0]: https://github.com/brazilian-utils/brutils-python/releases/tag/v2.3.0 -[2.2.0]: https://github.com/brazilian-utils/brutils-python/releases/tag/v2.2.0 -[2.1.1]: https://github.com/brazilian-utils/brutils-python/releases/tag/v2.1.1 -[2.1.0]: https://github.com/brazilian-utils/brutils-python/releases/tag/v2.1.0 -[2.0.0]: https://github.com/brazilian-utils/brutils-python/releases/tag/v2.0.0 + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61b6a21..038f82c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,20 +19,52 @@ O importante é que você saiba: sua participação é muito bem-vinda, e cada c 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) -- [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. Atualizar READMEs](#10-atualizar-readmes) -- [11. Faça o Commit e Envie as Suas Alterações](#11-faça-o-commit-e-envie-as-suas-alterações) -- [12. Adicione Entradas no CHANGELOG.md](#12-adicione-entradas-no-changelogmd) -- [13. Crie um PR no GitHub](#13-crie-um-pr-no-github) -- [14. Atualizar a Sua Branch se Necessário](#14-atualizar-a-sua-branch-se-necessário) +- [Contribuindo](#contribuindo) + - [💌 Quer contribuir, mas não se sente à vontade?](#-quer-contribuir-mas-não-se-sente-à-vontade) + - [Primeira Contribuição](#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) + - [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) + - [Instalação com poetry](#instalação-com-poetry) + - [Requisitos](#requisitos) + - [Instalação com pip](#instalação-com-pip) + - [Requisitos](#requisitos-1) + - [Utilizando Localmente](#utilizando-localmente) + - [Testes](#testes) + - [Testes no Windows](#testes-no-windows) + - [Instalar o Chocolatey](#instalar-o-chocolatey) + - [Instalar o `make`](#instalar-o-make) + - [Instalar o Poetry](#instalar-o-poetry) + - [Instalar as dependências do projeto](#instalar-as-dependências-do-projeto) + - [Verificar e configurar o `Makefile`](#verificar-e-configurar-o-makefile) + - [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) + - [Escreva Novos Testes](#escreva-novos-testes) + - [Certifique-se de que Todos os Testes Passam](#certifique-se-de-que-todos-os-testes-passam) + - [Teste manualmente](#teste-manualmente) + - [10. Atualizar READMEs](#10-atualizar-readmes) + - [11. Faça o Commit e Envie as Suas Alterações](#11-faça-o-commit-e-envie-as-suas-alterações) + - [12. Crie um PR no GitHub](#12-crie-um-pr-no-github) + - [Escreva um Título Descritivo para o PR](#escreva-um-título-descritivo-para-o-pr) + - [Forneça uma Descrição Detalhada do PR](#forneça-uma-descrição-detalhada-do-pr) + - [Vincule o PR à Issue Relacionada](#vincule-o-pr-à-issue-relacionada) + - [Verifique o Template de Descrição do PR](#verifique-o-template-de-descrição-do-pr) + - [13. Atualizar a Sua Branch se Necessário](#13-atualizar-a-sua-branch-se-necessário) + - [Lançar uma Nova Versão](#lançar-uma-nova-versão) + - [1. Criar uma Issue de Release](#1-criar-uma-issue-de-release) + - [Crie a Issue](#crie-a-issue) + - [Crie uma Branch](#crie-uma-branch) + - [Faça o Commit](#faça-o-commit) + - [2. Criar um Release PR](#2-criar-um-release-pr) + - [Atualizar a Versão da Biblioteca](#atualizar-a-versão-da-biblioteca) + - [Atualizar o CHANGELOG.md](#atualizar-o-changelogmd) + - [Crie o PR](#crie-o-pr) + - [Faça o Merge do PR](#faça-o-merge-do-pr) + - [3. Deploy via GitHub](#3-deploy-via-github) ### 1. Crie uma Conta no GitHub @@ -492,162 +524,14 @@ To github.com:brazilian-utils/brutils-python.git Faça as alterações e commits necessários e envie-os quando estiverem prontos. -### 12. Adicione Entradas no CHANGELOG.md +**Observação sobre o CHANGELOG:** O CHANGELOG.md é gerado automaticamente a partir dos commits usando [git-cliff](https://git-cliff.org/). Quando seu PR for mesclado na branch `main`, as mudanças aparecerão automaticamente na seção `[Unreleased]` do CHANGELOG. Por isso, é importante seguir o padrão de [Conventional Commits](https://www.conventionalcommits.org/) nas suas mensagens de commit: -#### O que é um changelog? +- `feat:` para novas funcionalidades (aparecerá em "Added") +- `fix:` para correções de bugs (aparecerá em "Fixed") +- `refactor:` ou `perf:` para mudanças em funcionalidades existentes (aparecerá em "Changed") +- `docs:`, `test:`, `ci:`, `chore:` são ignorados no changelog -Um changelog é um arquivo que contém uma lista organizada cronologicamente de mudanças notáveis para cada versão de um projeto. - -#### Por que manter um changelog? - -Para facilitar para usuários e contribuintes verem exatamente quais mudanças notáveis foram feitas entre cada release (ou versão) do projeto. - -#### Quem precisa de um changelog? - -Pessoas. Sejam consumidores ou desenvolvedores, os usuários finais de software são seres humanos que se importam com o que está no software. Quando o software muda, as pessoas querem saber por que e como. - -#### Onde está o changelog do brutils? - -O changelog do brutils está disponível em [CHANGELOG.md][changelog] - -#### Princípios orientadores - -- Changelogs são para humanos, não máquinas. -- Deve haver uma entrada para cada versão. -- Os mesmos tipos de mudanças devem ser agrupados. -- Versões e seções devem ser linkáveis. -- A versão mais recente vem primeiro. -- A data de lançamento de cada versão é exibida. - -#### O que justifica uma entrada no changelog? - -- Correções de segurança: Devem ser documentadas com o tipo definido como "segurança" para alertar os usuários sobre questões de segurança resolvidas. -Exemplo: “Corrigido um vulnerabilidade crítica que permitia a execução remota de código.” - -- Mudanças voltadas ao usuário: Alterações que afetam diretamente a forma como os usuários interagem com o software, incluindo novas funcionalidades, alterações em funcionalidades existentes ou melhorias na interface. -Exemplo: “Adicionada uma nova opção de filtro na página de resultados para facilitar a busca.” - -- Melhorias significativas de desempenho: Devem ser registradas quando resultam em melhorias notáveis na velocidade ou na eficiência do software que impactam a experiência do usuário. -Exemplo: “O tempo de carregamento da página inicial foi reduzido em 40% após a otimização do backend.” - -- Alterações que afetam a compatibilidade: Mudanças que ajustam o software para manter a compatibilidade com outras ferramentas, sistemas ou versões. -Exemplo: “Atualizada a biblioteca X para a versão 2.0 para suportar a nova versão do Python.” - -- Mudanças na API pública: -Alterações que afetam como os desenvolvedores interagem com a API pública do software, seja adicionando novas rotas ou alterando as existentes. -Exemplo: “Adicionada uma nova rota /api/v1/users para gerenciamento de usuários.” - -- Alterações nas dependências: Atualizações ou mudanças nas dependências do projeto que podem afetar o comportamento ou a compatibilidade do software. -Exemplo: “Atualizado o pacote de dependência Y para a versão 3.1.4, que inclui correções importantes de segurança.” - -#### O quê NÃO deve ir no changelog - -Embora o changelog seja uma ferramenta valiosa para documentar mudanças, algumas informações não devem ser incluídas. Aqui estão alguns exemplos do que não deve aparecer no changelog: - -- Mudanças Internas de Código: Alterações que não afetam o comportamento do usuário final, como refatorações de código interno que não alteram a funcionalidade, não precisam ser documentadas no changelog. Exemplo: “Refatoração de funções internas” ou “Correção testes inconsistentes.” - -- Melhorias de Desempenho Não Notáveis: Melhorias de desempenho que não resultam em mudanças perceptíveis ou benefícios claros para o usuário final não precisam de uma entrada específica. Exemplo: “Otimização de algoritmos internos.” - -- Correções de Bugs Menores: Correções para bugs que não afetam o uso geral ou a experiência do usuário final podem ser omitidas. Exemplo: “Correção de um pequeno erro de digitação no código.” - -- Mudanças Somente de Documentação: Alterações que afetam apenas a documentação, sem modificar o comportamento do software, geralmente não precisam ser incluídas no changelog. Exemplo: “Atualização do README.md para refletir novas dependências.” - -- Detalhes Técnicos Excessivos: Informações excessivamente técnicas que não são relevantes para o usuário final ou não oferecem contexto sobre o impacto da mudança devem ser evitadas. Exemplo: “Mudança no gerenciamento de memória na classe X.” - -- Entradas de Mantenedor: Mudanças que são relacionadas apenas ao processo de desenvolvimento ou manutenção interna, como ajustes de configuração de ferramentas de CI/CD, geralmente não são relevantes para o changelog. Exemplo: “Atualização na configuração do GitHub Actions.” - -- Uma correção de bug introduzida e corrigida na mesma release não precisa de uma entrada no changelog. - -Evite incluir essas informações no changelog para manter o documento focado e útil para os usuários e contribuintes do projeto. - -#### Escrevendo boas entradas no changelog - -Uma boa entrada no changelog deve ser descritiva e concisa. Deve explicar a mudança a um leitor que não tem nenhum contexto sobre a mudança. Se for difícil ser ao mesmo tempo conciso e descritivo, opte por ser mais descritivo. - -- **Ruim**: Ir para a ordem do projeto. -- **Bom**: Mostrar os projetos estrelados do usuário no topo do dropdown “Ir para o projeto”. - -O primeiro exemplo não dá contexto sobre onde a mudança foi feita, nem por que, nem como beneficia o usuário. - -- **Ruim**: Copiar (algum texto) para a área de transferência. -- **Bom**: Atualizar o tooltip de “Copiar para a área de transferência” para indicar o que está sendo copiado. - -Novamente, o primeiro exemplo é muito vago e não fornece contexto. - -- **Ruim**: Corrige e melhora problemas de CSS e HTML no gráfico de mini pipeline e dropdown de builds. -- **Bom**: Corrigir tooltips e estados de hover no gráfico de mini pipeline e dropdown de builds. - -O primeiro exemplo está muito focado nos detalhes de implementação. O usuário não se importa que mudamos CSS e HTML, ele se importa com o resultado final dessas mudanças. - -- **Ruim**: Remover valores nulos no Array de objetos Commit retornados por find_commits_by_message_with_elastic -- **Bom**: Corrigir erros 500 causados por resultados do Elasticsearch referenciando commits já recolhidos pelo garbage collector. - -O primeiro exemplo foca em como corrigimos algo, não no que foi corrigido. A versão reescrita descreve claramente o benefício final para o usuário (menos erros 500) e quando isso acontece (ao buscar commits com Elasticsearch). - -Use seu melhor julgamento e tente se colocar na posição de alguém lendo o changelog compilado. Essa entrada agrega valor? Oferece contexto sobre onde e por que a mudança foi feita? - -### Como adicionar uma entrada no changelog - -O changelog está disponível no arquivo [CHANGELOG.md][changelog]. - -Primeiro, você precisa identificar o tipo da sua mudança. Tipos de mudanças: - -- `Added` para novas funcionalidades. -- `Changed` para mudanças em funcionalidades existentes. -- `Deprecated` para funcionalidades que serão removidas em breve. -- `Fixed` para qualquer correção de bugs. -- `Removed` para funcionalidades que foram removidas. -- `Security` em caso de vulnerabilidades. - -Você deve sempre adicionar novas entradas no changelog na seção `Unreleased`. No momento do release, moveremos as mudanças da seção `Unreleased` para uma nova seção de versão. - -Portanto, dentro da seção `Unreleased`, você deve adicionar sua entrada na seção apropriada por tipo. Se ainda não houver uma seção para o tipo da sua mudança, você deve adicioná-la. - -Vamos ver alguns exemplos. Suponhamos que você tenha uma nova mudança `Fixed` para adicionar, e o arquivo atual do CHANGELOG.md está assim: - -```md -## [Unreleased] -### Added -- Utilitário `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) - -### Changed -- Utilitário `fmt_voter_id` renomeado para `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) -``` - -Você precisará adicionar uma nova seção `Fixed` e incluir a nova entrada lá: - -```md -## [Unreleased] -### Added -- Utilitário `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) - -### Changed -- Utilitário `fmt_voter_id` renomeado para `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) - -### Fixed -- Minha mensagem de changelog aqui. [#]() -``` - -Note que a ordem das seções por tipo importa. Temos um lint que verifica isso, então as seções devem ser ordenadas alfabeticamente. Primeiro `Added`, depois `Changed`, terceiro `Deprecated` e assim por diante. - -Agora, digamos que você tem mais uma entrada para adicionar e o tipo dela é `Added`. Como já temos uma seção para isso, você devve apenas adicionar uma nova linha: - -```md -## [Unreleased] -### Added -- Utilitário `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) -- Minha outra mensagem de changelog aqui. [#]() - -### Changed -- Utilitário `fmt_voter_id` renomeado para `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) - -### Fixed -- Minha mensagem de changelog aqui. [#]() -``` - -_Este conteúdo é baseado no [site do keep a changelog][keep-a-changelog], já que seguimos suas diretrizes._ - -### 13. Crie um PR no GitHub +### 12. Crie um PR no GitHub [Crie um PR no GitHub][github-creating-a-pr] para enviar suas alterações para revisão. Para garantir que seu Pull Request (PR) seja claro, eficaz e revisado rapidamente, siga estas boas práticas: @@ -678,18 +562,18 @@ Este PR adiciona o utilitário convert_uf_to_text para converter códigos de est - Para mais detalhes, consulte a [documentação do GitHub sobre fechamento automático de issues](https://docs.github.com/pt/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). #### Verifique o Template de Descrição do PR -- Certifique-se de que seu PR segue o template de descrição do repositório. Verifique todos os itens obrigatórios, como cobertura de testes, atualizações de documentação ou entradas no changelog. +- Certifique-se de que seu PR segue o template de descrição do repositório. Verifique todos os itens obrigatórios, como cobertura de testes e atualizações de documentação. - **Exemplo de Checklist**: (mostrando como fica quando preenchido): - [x] Alterações no código foram testadas. - [x] Documentação (READMEs) foi atualizada. -- [ ] Entrada no changelog foi adicionada (marque apenas se aplicável). +- [x] Mensagens de commit seguem o padrão Conventional Commits. - **Nota sobre a Sintaxe**: - Use [x] para marcar itens concluídos e [ ] para itens não concluídos, sem espaços dentro dos colchetes (ex.: [ x ] ou [x ] não será renderizado corretamente no GitHub). - **Benefícios**: - Seguir o template garante que o PR esteja completo e pronto para revisão. - Reduz a necessidade de idas e vindas com revisores, acelerando o processo de mesclagem. -### 14. Atualizar a Sua Branch se Necessário +### 13. Atualizar a Sua Branch se Necessário [Certifique-se de que sua branch esteja atualizado com o main][github-sync-pr] @@ -728,10 +612,7 @@ 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](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/antoniamaia/brutils-python/blob/eac770e8b213532d2bb5948d117f6f4684f65be2/CHANGELOG.md?plain=1#L76) +Execute `git cliff --bump --output CHANGELOG.md` #### Crie o PR diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md index 1579e27..44e5902 100644 --- a/CONTRIBUTING_EN.md +++ b/CONTRIBUTING_EN.md @@ -19,20 +19,44 @@ What matters is that you know: your participation is very welcome, and every con How to make your first contribution: -- [1. Create a GitHub Account](#1-create-a-github-account) -- [2. Find an Issue to Work On](#2-find-an-issue-to-work-on) -- [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. Update READMEs](#10-update-readmes) -- [11. Commit and push your Changes](#11-commit-and-push-your-changes) -- [12. Add changelog Entries](#12-add-changelog-entries) -- [13. Create a GitHub PR](#13-create-a-github-pr) -- [14. Update your branch if Needed.](#14-update-your-branch-if-needed) +- [Contributing](#contributing) + - [💌 Want to contribute, but don’t feel comfortable?](#-want-to-contribute-but-dont-feel-comfortable) + - [First Contribution](#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) + - [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) + - [Installation with poetry](#installation-with-poetry) + - [Requirements](#requirements) + - [Installation with pip](#installation-with-pip) + - [Requirements](#requirements-1) + - [Using locally](#using-locally) + - [Tests](#tests) + - [8. Make your changes](#8-make-your-changes) + - [9. Test your changes](#9-test-your-changes) + - [Write new tests](#write-new-tests) + - [Make sure all tests passed](#make-sure-all-tests-passed) + - [Test it manually](#test-it-manually) + - [11. Commit and push your changes](#11-commit-and-push-your-changes) + - [12. Create a GitHub PR](#12-create-a-github-pr) + - [Write a Descriptive PR Title](#write-a-descriptive-pr-title) + - [Provide a Detailed PR Description](#provide-a-detailed-pr-description) + - [Link the PR to the Related Issue](#link-the-pr-to-the-related-issue) + - [Verify the PR Description Template](#verify-the-pr-description-template) + - [13. Update your branch if needed.](#13-update-your-branch-if-needed) + - [Release a New Version](#release-a-new-version) + - [1. Create a Release Issue](#1-create-a-release-issue) + - [Create the Issue](#create-the-issue) + - [Create a Branch](#create-a-branch) + - [2. Create a Release PR](#2-create-a-release-pr) + - [Update the Library Version](#update-the-library-version) + - [Update the CHANGELOG.md](#update-the-changelogmd) + - [Create the PR](#create-the-pr) + - [Merge the PR](#merge-the-pr) + - [3. Deploy via GitHub](#3-deploy-via-github) ### 1. Create a GitHub Account @@ -388,167 +412,14 @@ To github.com:brazilian-utils/brutils-python.git Make the necessary changes and commits and push them when ready. -### 12. Add changelog entries +**Note about CHANGELOG:** The CHANGELOG.md is automatically generated from commits using [git-cliff](https://git-cliff.org/). When your PR is merged into the `main` branch, your changes will automatically appear in the `[Unreleased]` section of the CHANGELOG. Therefore, it's important to follow the [Conventional Commits](https://www.conventionalcommits.org/) pattern in your commit messages: -#### What is a changelog? +- `feat:` for new features (will appear in "Added") +- `fix:` for bug fixes (will appear in "Fixed") +- `refactor:` or `perf:` for changes to existing features (will appear in "Changed") +- `docs:`, `test:`, `ci:`, `chore:` are ignored in the changelog -A changelog is a file that contains a chronologically organized list of notable changes for each version of a project. - -#### Why maintain a changelog? - -To make it easier for users and contributors to see exactly what notable changes have been made between each release (or version) of the project. - -#### Who needs a changelog? - -People. Whether they are consumers or developers, the end users of software are human beings who care about what’s in the software. When the software changes, people want to know why and how. - -#### Where is the brutils changelog? - -The brutils changelog is available at [CHANGELOG.md][changelog]. - -#### Guiding principles - -- Changelogs are for humans, not machines. -- There should be an entry for every version. -- The same types of changes should be grouped together. -- Versions and sections should be linkable. -- The most recent version comes first. -- The release date of each version is displayed. - -#### What justifies an entry in the changelog? - -- Security fixes: These should be documented with the type labeled as “security” to alert users to resolved security issues. -Example: “Fixed a critical vulnerability that allowed remote code execution.” - -- User-facing changes: Changes that directly affect how users interact with the software, including new features, changes to existing features, or UI improvements. -Example: “Added a new filter option on the results page to make searching easier.” - -- Significant performance improvements: Should be recorded when they result in noticeable improvements in speed or efficiency that impact the user experience. -Example: “The home page loading time was reduced by 40% after backend optimization.” - -- Changes affecting compatibility: Adjustments to maintain compatibility with other tools, systems, or versions. -Example: “Updated library X to version 2.0 to support the new version of Python.” - -- Changes to the public API: Changes that affect how developers interact with the public API, such as adding new routes or modifying existing ones. -Example: “Added a new /api/v1/users route for user management.” - -- Dependency changes: Updates or changes to the project’s dependencies that may affect software behavior or compatibility. -Example: “Updated dependency package Y to version 3.1.4, which includes important security fixes.” - -#### What should NOT go in the changelog - -Although the changelog is a valuable tool for documenting changes, some information should not be included. Here are some examples of what should not appear in the changelog: - -- Internal Code Changes: Changes that do not affect the end-user experience, such as internal refactoring that does not alter functionality, need not be documented. -Example: “Refactored internal functions” or “Fixed inconsistent tests.” - -- Non-notable performance improvements: Performance improvements that do not result in noticeable changes or clear benefits for the end user do not need to be included. -Example: “Optimized internal algorithms.” - -- Minor bug fixes: Bug fixes that do not impact the general use or end-user experience can be omitted. -Example: “Fixed a small typo in the code.” - -- Documentation-only changes: Changes that affect only the documentation, without modifying the software behavior, usually don’t need to be included. -Example: “Updated README.md to reflect new dependencies.” - -- Excessive technical details: Overly technical information that is irrelevant to the end user or does not provide context on the impact of the change should be avoided. -Example: “Changed memory management in class X.” - -- Maintainer entries: Changes related only to the development or internal maintenance process, such as CI/CD tool configuration adjustments, are generally not relevant for the changelog. -Example: “Updated GitHub Actions configuration.” - -- A bug introduced and fixed in the same release does not need a changelog entry. - -Avoid including this information to keep the changelog focused and useful for project users and contributors. - -#### Writing good changelog entries - -A good changelog entry should be both descriptive and concise. It should explain the change to a reader with no prior context about the change. If it’s hard to be both concise and descriptive, lean toward being more descriptive. - -- **Bad** : Go to the project order. -- **Good**: Display the user’s starred projects at the top of the “Go to project” dropdown. - -The first example provides no context on where the change was made, why it was made, or how it benefits the user. - -- **Bad**: Copy (some text) to the clipboard. -- **Good**: Update the tooltip of “Copy to clipboard” to indicate what is being copied. - -Again, the first example is too vague and provides no context. - -- **Bad**: Fix and improve CSS and HTML issues in the mini pipeline graph and builds dropdown. -- **Good**: Fix tooltips and hover states in the mini pipeline graph and builds dropdown. - -The first example is too focused on implementation details. Users don’t care that we changed CSS and HTML, they care about the final result of those changes. - -- **Bad**: Remove null values in the Commit object array returned by find_commits_by_message_with_elastic. -- **Good**: Fix 500 errors caused by Elasticsearch results referencing commits already collected by the garbage collector. - -The first example focuses on how we fixed something, not on what was fixed. The rewritten version clearly describes the final benefit to the user (fewer 500 errors) and when it happens (when searching for commits with Elasticsearch). - -Use your best judgment and try to put yourself in the position of someone reading the compiled changelog. Does this entry add value? Does it provide context on where and why the change was made? - -#### How to add an entry to the changelog - -The changelog is available in the [CHANGELOG.md][changelog] file. - -First, you need to identify the type of your change. Types of changes: - -- `Added` for new features. -- `Changed` for changes to existing features. -- `Deprecated` for features that will soon be removed. -- `Fixed` for any bug fixes. -- `Removed` for features that were removed. -- `Security` in case of vulnerabilities. - -You should always add new entries to the changelog in the `Unreleased` section. At the time of release, we will move the changes from the `Unreleased` section to a new version section. - -So, within the `Unreleased` section, you should add your entry to the appropriate section by type. If there is no section yet for the type of your change, you should add one. - -Let’s see some examples. Suppose you have a new `Fixed` change to add, and the current CHANGELOG.md file looks like this: - -```md -## [Unreleased] -### Added -- Utility `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) - -### Changed -- Utility `fmt_voter_id` renamed to `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) -``` - -You would need to add a new `Fixed` section and include your new entry there: - -```md -## [Unreleased] -### Added -- Utility `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) - -### Changed -- Utility `fmt_voter_id` renamed to `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) - -### Fixed -- My changelog message here. [#]() -``` - -Note that the order of sections by type matters. We have a lint that checks this, so the sections must be ordered alphabetically. First `Added`, then `Changed`, third `Deprecated`, and so on. - -Now, let’s say you have another entry to add, and its type is `Added`. Since we already have a section for that, you should just add a new line: - -```md -## [Unreleased] -### Added -- Utility `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358) -- My other changelog message here. [#]() - -### Changed -- Utility `fmt_voter_id` renamed to `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221) - -### Fixed -- My changelog message here. [#]() -``` - -This content is based on the [Keep a Changelog][keep-a-changelog] site, as we follow its guidelines. - -### 13. Create a GitHub PR +### 12. Create a GitHub PR [Create a GitHub PR][github-creating-a-pr] to submit your changes for review. To ensure your Pull Request (PR) is clear, effective, and reviewed quickly, follow these best practices: @@ -579,18 +450,18 @@ This PR adds the convert_uf_to_text utility to convert Brazilian state codes (e. - For more details, see the [GitHub documentation on closing issues automatically](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). #### Verify the PR Description Template -- Ensure your PR follows the repository’s PR description template (if provided). Check all required items, such as test coverage, documentation updates, or changelog entries. +- Ensure your PR follows the repository's PR description template (if provided). Check all required items, such as test coverage and documentation updates. - **Example Checklist**: (showing how it looks when completed): - [x] Code changes are tested. - [x] Documentation (READMEs) is updated. -- [ ] Changelog entry is added. +- [x] Commit messages follow Conventional Commits pattern. - **Syntax Note**: - Use [x] to mark completed items and [ ] for incomplete ones, with no spaces inside the brackets (e.g., [ x ] or [x ] will not render correctly on GitHub). - **Benefits**: - Adhering to the template ensures your PR is complete and ready for review. - It reduces back-and-forth with reviewers, speeding up the merge process. -### 14. Update your branch if needed. +### 13. Update your branch if needed. [Ensure your branch is up to date with main][github-sync-pr]. @@ -622,22 +493,19 @@ in the `pyproject.toml` file: https://github.com/brazilian-utils/brutils-python/ #### Update the CHANGELOG.md -Add a title for the new version with the new number and the current date, as seen in [this example](https://github.com/brazilian-utils/brutils-python/blob/main/CHANGELOG.md?plain=1#L9). - -And add the version links, like [this example](https://github.com/antoniamaia/brutils-python/blob/eac770e8b213532d2bb5948d117f6f4684f65be2/CHANGELOG.md?plain=1#L76) +Run `git cliff --bump --output CHANGELOG.md` #### Create the PR Create a PR named `Release v` containing the two changes mentioned above. In the description of the Pull Request, add the modified section of the changelog. - [Example of Release PR](https://github.com/brazilian-utils/brutils-python/pull/128) #### Merge the PR Once the PR is accepted and passes all checks, merge it. -### 2. Deploy via GitHub +### 3. Deploy via GitHub The new version release in production is done automatically when a [new release is created][creating-releases] on GitHub. diff --git a/Makefile b/Makefile index 6c9f4e5..241431f 100644 --- a/Makefile +++ b/Makefile @@ -26,4 +26,18 @@ ifeq ($(OS),Windows_NT) @set PYTHONDONTWRITEBYTECODE=1 && poetry run python -m unittest discover tests/ -v else @PYTHONDONTWRITEBYTECODE=1 poetry run python3 -m unittest discover tests/ -v -endif \ No newline at end of file +endif + +changelog: + @command -v git-cliff >/dev/null 2>&1 || { \ + echo "Error: git-cliff is not installed."; \ + echo ""; \ + echo "To install git-cliff, visit: https://git-cliff.org/docs/installation"; \ + echo ""; \ + echo "Quick install options:"; \ + echo " - cargo install git-cliff"; \ + echo " - brew install git-cliff (macOS)"; \ + echo " - Or download from: https://github.com/orhun/git-cliff/releases"; \ + exit 1; \ + } + @git cliff -o CHANGELOG.md diff --git a/pyproject.toml b/pyproject.toml index b36bcb6..e03173b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,100 @@ lint.extend-select = ["I"] [tool.ruff.lint.per-file-ignores] "__init__.py" = ["F401"] +[tool.git-cliff.changelog] +header = """ +# Changelog\n +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n +""" +body = """ +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} + +{% if version -%} + ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }} +{% else -%} + ## [Unreleased] +{% endif -%} + +{% for group, commits in commits | group_by(attribute="group") %} + ### {{ group | upper_first }} + {%- for commit in commits %} + - {{ commit.message | split(pat="\n") | first | upper_first | trim }}\ + {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%} + {% if commit.remote.pr_number %} in \ + [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}) \ + {%- endif -%} + {% endfor %} +{% endfor %} + +{%- if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %} + ### New Contributors +{%- endif -%} + +{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %} + * @{{ contributor.username }} made their first contribution + {%- if contributor.pr_number %} in \ + [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \ + {%- endif %} +{%- endfor %}\n + +{%- if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}{% raw %}\n{% endraw -%}{% endif %} + +""" +footer = """ +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} + +{% for release in releases -%} + {% if release.version -%} + {% if release.previous.version -%} + [{{ release.version | trim_start_matches(pat="v") }}]: \ + {{ self::remote_url() }}/compare/{{ release.previous.version }}...{{ release.version }} + {% endif -%} + {% else -%} + [unreleased]: {{ self::remote_url() }}/compare/{{ release.previous.version }}...HEAD + {% endif -%} +{% endfor %} + +""" +trim = true + +[tool.git-cliff.git] +conventional_commits = true +filter_unconventional = false +commit_preprocessors = [ + { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" }, +] +commit_parsers = [ + { message = "^feat", group = "Added" }, + { message = "^fix", group = "Fixed" }, + { message = "^docs", group = "Changed" }, + { message = "^refactor", group = "Changed" }, + { message = "^style", group = "Changed" }, + { message = "^perf", group = "Changed" }, + { message = "^breaking", group = "Deprecated" }, + { message = "^test", skip = true }, + { message = "^ci", skip = true }, + { message = "^build", skip = true }, + { message = "^chore\\(release\\)", skip = true }, + { message = "^chore\\(deps\\)", skip = true }, + { message = "^chore: release", skip = true }, + { message = "^chore", skip = true }, + { body = ".*BREAKING CHANGE.*", group = "Breaking" }, +] +filter_commits = false +topo_order = false +sort_commits = "newest" + +[tool.git-cliff.remote.github] +owner = "brazilian-utils" +repo = "python" + [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"