Toolbox Quand je suis content, je commit

Et j'inaugure la section "Toolbox" avec un retour de tests sur commitizen (et je réponds comme ça à un challenge de l'enfer).

Cette référence est sponsorisée par @alonahAmelie

Bref, je me suis encore perdu sur Twitter, et, quelque part, entre deux références à la Cité de la Peur et un gif de catch (tmtc) Amélie m’envoie ce tweet :

Merci Amélie. Merci.

https://c.tenor.com/jEtYKBM-IN0AAAAC/daenerys-targaryen-smile.gif

En fait, les choses tombent plutôt bien, car ce challenge impromptu m’a donné une idée pour inaugurer ma nouvelle section “ToolBox”. (Cheh).

Ce que je me suis amusé à tester

Et c’est non seulement raccord avec le challenge (MERCI Amélie) mais en plus, c’est mon dernier coup de cœur.

Ce coup de cœur, c’est commitizen !

Ok, c’est quoi ?

C’est un CLI super bien pensé qui te permet :

  • De nommer tes commits en respectant la spécification Conventional Commits ❤️  (Amélie en parle aussi dans son article)

  • De créer ou mettre à jour le CHANGELOG.md, basé sur la convention de nommage des commits. Tu aimes les changelogs. Les changelogs, c’est le bien. Fais des changelogs.

  • D’automatiser le versioning et les tags de version, toujours en fonction des commits, et même d’attribuer le changelog en cours à un tag. Tu aimes les changelogs. Les changelogs, c’est le bien. Fais des changelogs.

Le petit bonus sur la cerise, sur le gâteau, sur le plateau, sur la table de ton salon

Et oui, parce que ce n’est pas tout, non, non, non !

Commitizen s’intègre super bien avec git-flow. Ce faisant, tu pourras bénéficier du versioning et du changelog auto à chaque release git-flow 😀

Le tuto

Bon maintenant que je t’ai donné l’eau à la bouche, on va se lancer sur un tuto des familles. Tu verras, c’est pas long.

1. Installation

D’abord, on va installer le merdier (affectueux) tu vas aller ici : https://commitizen-tools.github.io/commitizen/ et là tu as plusieurs choix :

  • Avec pip (oui c’est un paquet python) : sudo pip3 install -U Commitizen
  • Avec homebrew si t’es mac-addict : brew install commitizen

2. Initialiser un repo

Donc maintenant que tu as cz installé, on va aller sur ton terminal préféré, dans un dossier vierge. Dedans on va se faire juste un fichier index.json (ou ce que tu veux, on n’est pas sectaires ici). Et on va y écrire :

1{
2    "foo": "bar"
3}

Très inspiré n’est-ce pas ?

Ensuite on initialise git dessus avec git init.

1➜  test git init
2Initialized empty Git repository in [..]/test/.git/

On initialise aussi commitizen avec cz init (peut être fait après).

1cz init

Il nous demande de choisir un nom de fichier de conf :

1? Please choose a supported config file: (default: pyproject.toml) (Use arrow keys)
2   pyproject.toml
3   .cz.toml
4   .cz.json
5   cz.json
6   .cz.yaml
7 » cz.yaml

On met ce qu’on veut, ici j’aime bien le yaml, mais c’est pareil, on ne va pas l’éditer ici.

On choisit la convention de commits à appliquer :

1? Please choose a supported config file: (default: pyproject.toml) cz.yaml
2? Please choose a cz (commit rule): (default: cz_conventional_commits) (Use arrow keys)
3 » cz_conventional_commits
4   cz_jira
5   cz_customize

On peut choisir le format du tag de version (le défaut me convient mais je t’invite à lire la doc si tu veux changer) :

1? Please choose a supported config file: (default: pyproject.toml) cz.yaml
2? Please choose a cz (commit rule): (default: cz_conventional_commits) cz_conventional_commits
3No Existing Tag. Set tag to v0.0.1
4? Please enter the correct version format: (default: "$version")

Il nous demande s’il installe les hooks de pre-commit (aller courage c’est bientôt fini).

La doc pour les pre-commit est ici, en gros cela permet de lancer automatiquement un vérification de convention sur les commits existants (de ce que j’ai compris).

 1? Please choose a supported config file: (default: pyproject.toml) cz.yaml
 2? Please choose a cz (commit rule): (default: cz_conventional_commits) cz_conventional_commits
 3No Existing Tag. Set tag to v0.0.1
 4? Please enter the correct version format: (default: "$version")
 5? Do you want to install pre-commit hook? Yes
 6commitizen pre-commit hook is now installed in your '.git'
 7 
 8You can bump the version and create changelog running:
 9 
10cz bump --changelog
11The configuration are all set.

C’est prêt !

https://c.tenor.com/4FSq8jODZAoAAAAd/salt-salt-bae.gif

3. Faire un commit

Et c’est parti pour le premier commit :

1git add .
2git status

On a bien le fichier index.json qui est prêt à être commit (hourra) on va pouvoir s’amuser avec commitizen.

Donc on va se dire que notre commit est une nouvelle feature qui permet à un.e utilisateur.trice d’ajouter un produit dans ses favoris.

1cz c

On dit que c’est une nouvelle feature.

 1? Select the type of change you are committing (Use arrow keys)
 2   fix: A bug fix. Correlates with PATCH in SemVer
 3 » feat: A new feature. Correlates with MINOR in SemVer
 4   docs: Documentation only changes
 5   style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
 6   refactor: A code change that neither fixes a bug nor adds a feature
 7   perf: A code change that improves performance
 8   test: Adding missing or correcting existing tests
 9   build: Changes that affect the build system or external dependencies (example scopes: pip, docker, npm)
10   ci: Changes to our CI configuration files and scripts (example scopes: GitLabCI)

Dans notre cas le scope c’est product.

1? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
2? What is the scope of this change? (class or file name): (press [enter] to skip)
3 product

Commitizen nous demande ensuite un petit résumé (court et à la forme impérative) :

1? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
2? What is the scope of this change? (class or file name): (press [enter] to skip)
3 product
4? Write a short and imperative summary of the code changes: (lower case and no period)
5 a user can bookmark a product

Tu peux aussi écrire des détails dans le corps de ton commit :

1? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
2? What is the scope of this change? (class or file name): (press [enter] to skip)
3 product
4? Write a short and imperative summary of the code changes: (lower case and no period)
5 a user can bookmark a product
6? Provide additional contextual information about the code changes: (press [enter] to skip)
7 As a user, I want to bookmark a product, to find it easily later on

On indique si c’est un breaking change (dans notre cas nope) :

1? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
2? What is the scope of this change? (class or file name): (press [enter] to skip)
3 product
4? Write a short and imperative summary of the code changes: (lower case and no period)
5 a user can bookmark a product
6? Provide additional contextual information about the code changes: (press [enter] to skip)
7 As a user, I want to bookmark a product, to find it easily later on
8? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No

Et on peut terminer par le footer du commit (genre l’Issue github liée au commit) :

 1? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
 2? What is the scope of this change? (class or file name): (press [enter] to skip)
 3 product
 4? Write a short and imperative summary of the code changes: (lower case and no period)
 5 a user can bookmark a product
 6? Provide additional contextual information about the code changes: (press [enter] to skip)
 7 As a user, I want to bookmark a product, to find it easily later on
 8? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No
 9? Footer. Information about Breaking Changes and reference issues that this commit closes: (press [enter] to skip)
10 Closes #1223

Et voilà un commit tout beau tout propre :

 1* commit c2c1d2e6d9d309847cb504e9e01a2b2850bc7bed (HEAD -> main)
 2  Author: Lorenzo Milesi <xxx@xxx.xx>
 3  Date:   Tue Jul 5 13:36:15 2022 +0200
 4 
 5      feat(product): a user can bookmark a product
 6 
 7      As a user, I want to bookmark a product, to find it easily later on
 8 
 9      Closes #1223
10(END)

3. Bumper sa version + changelog

Une fois plusieurs commits passés et les différents merges effectués (dans notre cas, on reste simple, mais c’est pareil), on peut aller bump un nouvelle version, créer le tag correspondant et enfin écrire un nouveau changelog :

1cz bump --changelog

Si c’est le premier tag, normalement commitizen va te poser quelques questions :

1Tag 0.0.1 could not be found.
2Possible causes:
3- version in configuration is not the current version
4- tag_format is missing, check them using 'git tag --list'
5 
6? Is this the first tag created? Yes

Sinon il calculera et génèrera directement le tag de version (et le changelog si tu lui as précisé)

1bump: version 0.0.1 → 0.1.0
2tag to create: 0.1.0
3increment detected: MINOR
4 
5Done!

Et voilà on a donc un tout nouveau tag 0.1.0et un tout nouveau CHANGELOG.md yey :

1➜  test git:(main) ✗ cat CHANGELOG.md
2## 0.1.0 (2022-07-05)
3 
4### Feat
5 
6- **product**: a user can bookmark a product

https://c.tenor.com/BnEKiDKJisEAAAAC/claire-dancing.gif

C’est tout pour moi, je te laisse découvrir ce super outil, et je te dis à la prochaine ;)

La bise 😘