release-new-version

name

release-new-version

description

Release a new version of an official API Entreprise / API Particulier SDK to its package registry (rubygems for Ruby). Covers version bump, CHANGELOG update, release PR, tag conventions, and the OIDC-published workflow. Use when the user mentions "release", "publier", "publish sdk", "bump version sdk", "nouvelle version sdk", "rubygems", or asks to ship a new version of `api_entreprise` / `api_particulier` (Ruby today, more languages to come).

Release a new SDK version

Source of truth for Ruby : clients/ruby/README.md §"Publier une version sur rubygems.org". Read it before deviating.

Scope

One gem at a time. api_entreprise and api_particulier versionnent indépendamment — ne jamais coupler les deux dans une même release.

Prérequis par gem (à valider au moins une fois)

Ces points sont des prérequis externes au repo. Si l'un manque, le workflow échoue de façon souvent silencieuse ou cryptique. Vérifier avant de pousser un tag sur un gem qui n'a jamais été release via le workflow.

1. Trusted publisher OIDC sur rubygems — https://rubygems.org/profile/oidc/trusted_publishers doit avoir une entrée pour le gem avec exactement :

   • GitHub Repository : datagouv/apistration
   • Workflow Filename : clients-ruby.yml (pas clients-ruby-release.yml, pas autre chose — doit matcher le nom de fichier sous .github/workflows/)
   • Environment : rubygems

   Mismatch → erreur explicite à l'étape configure-rubygems-credentials : No trusted publisher configured for this workflow found on https://rubygems.org for audience rubygems.org.

2. Branch policy de l'environment rubygems typée tag (cf. Gotchas).

3. Rakefile + rake dev dep dans le gem (clients/ruby/<gem>/Rakefile + gem 'rake' dans le Gemfile group :development). Le Rakefile doit require 'bundler/gem_tasks' et, pour fonctionner avec rubygems/release-gem@v1, no-op release:source_control_push quand CI=true (cf. Rakefile en place). Sans Rakefile : can't find executable rake for gem rake.

4. Premier release manuel déjà effectué pour réserver le nom du gem sur rubygems (cf. clients/ruby/README.md §Prérequis).

Workflow (Ruby)

1. Branche release dédiée

   git checkout -b release/api-<entreprise|particulier>-<X.Y.Z>
   

2. Bump clients/ruby/<gem>/lib/<gem>/version.rb. SemVer :

   • patch : régénération scaffolding, changement OpenAPI rétro-compatible (paramètre devient optionnel, nouveau champ de réponse).
   • minor : nouvel endpoint, nouvelle méthode publique.
   • major : breaking change (paramètre requis ajouté, méthode supprimée, renommage).

3. CHANGELOG clients/ruby/<gem>/CHANGELOG.md — format Keep a Changelog :

   • Convertir [Unreleased] en [X.Y.Z] - YYYY-MM-DD quand la section contient le contenu releasé, sinon ajouter une nouvelle section [X.Y.Z] au-dessus de [Unreleased] (qui reste vide).
   • Sections : Added / Changed / Deprecated / Removed / Fixed / Security. Référencer le SHA upstream qui motive la release.

4. Tests locaux

   cd clients/ruby/<gem> && bundle exec rspec
   

   Le Gemfile.lock est modifié par le bundle (<gem> (X.Y.Z)) — l'inclure dans le commit.

5. Commit unique

   git commit -m "Release <gem> X.Y.Z"
   

   Message détaillé sur le pourquoi (changement upstream, breaking, etc.).

6. PR vers develop — review obligatoire, squash-merge.

7. Tag le commit de merge sur develop (pas la branche release jetable — sinon le tag pointe sur un commit orphelin) :

   git checkout develop && git pull
   git tag ruby-api-<entreprise|particulier>-v<X.Y.Z>
   git push origin ruby-api-<entreprise|particulier>-v<X.Y.Z>
   

8. Workflow .github/workflows/clients-ruby.yml se déclenche sur le tag :

   • vérifie tag_version == gemspec.version ;
   • relance rspec ;
   • publie via rubygems/release-gem@v1 (OIDC trusted publisher, environment rubygems).

   Surveiller la run, vérifier la version sur rubygems.org après succès.

Tags reconnus

Tag	Gem publié
ruby-api-entreprise-v<X.Y.Z>	api_entreprise
ruby-api-particulier-v<X.Y.Z>	api_particulier

Tag invalide → step "Resolve gem from tag" échoue et stoppe le workflow.

Gotchas

• Tag mal placé (sur la branche release jetable non mergée) : le commit n'est atteignable depuis aucune branche permanente. Toujours tagger après merge, sur develop.
• Version dans version.rb ≠ tag : le job release échoue à "Verify tag version matches gemspec version".
• Ne jamais committer Gemfile.lock sans avoir bumpé version.rb avant — divergence silencieuse.
• Le CHANGELOG.md initial des gems publiait le contenu sous [Unreleased] alors que 0.1.0 était déjà sur rubygems. Au premier patch, convertir [Unreleased] → [0.1.0] puis ajouter [0.1.1] au-dessus.
• Branch policy de l'environment rubygems doit être de type tag, pas branch. Si la policy ruby-api-<gem>-v* est typée branch (cas rencontré sur api_particulier à la 0.1.1), GitHub rejette le déploiement instantanément : zéro step exécuté, log introuvable (log not found), steps array vide via API. Vérifier :

  gh api repos/datagouv/apistration/environments/rubygems/deployment-branch-policies
  

  Si une entrée est mal typée :

  gh api -X DELETE repos/datagouv/apistration/environments/rubygems/deployment-branch-policies/<id>
  gh api -X POST   repos/datagouv/apistration/environments/rubygems/deployment-branch-policies \
    -f 'name=ruby-api-<gem>-v*' -f 'type=tag'
  

  Puis gh run rerun <run-id>.
• Le run reste en waiting tant que (1) le wait_timer (15 min) n'est pas écoulé et (2) un reviewer de la liste rubygems n'a pas approuvé. Voir gh api repos/datagouv/apistration/actions/runs/<id>/pending_deployments.
• Trusted publisher Workflow Filename qui ne matche pas : No trusted publisher configured for this workflow found on https://rubygems.org. Bug courant : entrée rubygems pointe sur un nom de workflow obsolète (clients-ruby-release.yml) alors que le fichier réel est clients-ruby.yml. Corriger sur rubygems, puis gh run rerun <id>.
• rake aborted! sur release:source_control_push avec error: src refspec refs/heads/HEAD does not match any : rubygems/release-gem@v1 checkout le tag (detached HEAD) puis lance bundle exec rake release, ce qui chaîne release:source_control_push qui essaie un git push origin HEAD impossible. Le Rakefile doit no-op cette tâche quand CI=true (le tag est déjà sur origin, c'est lui qui a déclenché la run).
• Re-trigger d'un workflow tag-based après fix : ne pas re-tagger en vX.Y.Z+1. Force-déplacer le tag existant vers le nouveau merge commit :

  git tag -f ruby-api-<gem>-v<X.Y.Z> <new-merge-sha>
  git push --force origin ruby-api-<gem>-v<X.Y.Z>
  

  Le push tag ré-émet l'event GitHub et redéclenche le workflow. Tant que la version n'a pas réellement été publiée sur rubygems, c'est légitime.

Étendre ce skill

Quand un nouveau langage rejoint clients/ (Node, Python, PHP, Java) : ajouter une section ## Workflow (<langage>) ici avec :

• chemin du fichier de version (package.json, pyproject.toml, etc.) ;
• format du tag attendu par le workflow CI correspondant ;
• registry cible (npm, PyPI, Packagist, Maven Central) ;
• éventuelles spécificités auth (OIDC, token secret, etc.).

Mettre à jour le description frontmatter pour citer le nouveau langage et ses triggers.