Merge pull request #532 from bastelfreak/gem2

Add docs for gem publication

Author: bastelfreak

_docs/publish_gem.md

@@ -0,0 +1,81 @@
+---
+layout: post
+title: Setting up a gem for publication
+date: 2025-08-13
+summary: Steps to do to enable publication of a new gem
+---
+
+Those are the steps you have to take to publish a new gem:
+
+
+## Setup GitHub workflow
+
+Right now we don't have a way to sync workflows for each gem.
+Copy the [release workflow](https://github.com/voxpupuli/gem-workflow-test/blob/master/.github/workflows/release.yml) from our [boilerplate gem](https://github.com/voxpupuli/gem-workflow-test).
+This workflow will take care of:
+
+* Building the gem
+* Creating a GitHub and rubygems.org release
+* Attaching the gem to the GitHub release
+* Creating the changelog for the GitHub release
+* Waits until the new version is present on the rubygems.org cache
+
+### Configure rubygems.org
+
+**This needs to be done by a PMC member**
+
+Before the first release, trusted publishing needs to be configured on rubygems.org
+
+* login to rubygems.org with the voxpupui or openvoxproject account from gopass
+* go to https://rubygems.org/profile/oidc/pending_trusted_publishers
+* click "create"
+* add gem name, repo owner ("voxpupuli" or "OpenVoxProject"), repo name (usually same as gem name), workflow name (`release.yml`)
+* Set environment to `release` ([configured in our workflow](https://github.com/voxpupuli/gem-workflow-test/blob/96a29ada7ddea2ba0f27cbe0efd2194c7b9e7213/.github/workflows/release.yml#L71))
+
+This step has to be done at maximum 48h before the first release, or rubygems.org deletes the configuration
+The configuratin can be added again if rubygems.org deleted it.
+
+## Setup the GitHub Changelog configuration
+
+Copy the [config yaml](https://github.com/voxpupuli/gem-workflow-test/blob/master/.github/release.yml).
+This will ensure that all closed issues and PRs with labels are sorted into the correct categories.
+
+## Recommendations
+
+### dependabot
+
+We have a basic [dependabot config](https://github.com/voxpupuli/gem-workflow-test/blob/master/.github/dependabot.yml).
+It will raise PRs for updates on Ruby dependencies or github action dependencies.
+We highly recommend that you copy the file.
+
+### Gemfile
+
+We recommend that the Gemfile contains a `release` gem group:
+
+```ruby
+group :release, optional: true do
+  gem 'faraday-retry', '~> 2.1', require: false
+  gem 'github_changelog_generator', '~> 1.16.4', require: false
+end
+```
+
+### Rakefile
+
+With the `changelog` rake task, you can follow our [release documentation](https://voxpupuli.org/docs/releasing_gem/).
+Put the following in a Rakefile (adjust the `config.project` value):
+
+```ruby
+begin
+  require 'rubygems'
+  require 'github_changelog_generator/task'
+rescue LoadError
+else
+  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+    config.exclude_labels = %w[duplicate question invalid wontfix wont-fix skip-changelog dependencies]
+    config.user = 'voxpupuli'
+    config.project = 'json-schema'
+    gem_version = Gem::Specification.load("#{config.project}.gemspec").version
+    config.future_release = "#{gem_version}"
+  end
+end
+```

_docs/releasing_gem.md

@@ -5,17 +5,17 @@ date: 2023-02-25
 summary: How to perform a complete version release
 ---
 
-The release process is split into two parts. Part one can be done by anybody
-with a GitHub account. You do not need to be part of the Vox Pupuli GitHub
-organisation.
+The release process is split into two parts.
+Part one can be done by anybody with a GitHub account.
+You do not need to be part of the Vox Pupuli GitHub organisation.
 
 ## Part 1: Create a 'release pr'
 
-This pull request updates the changelog and bumps the version number to the
-target version. The version is set in the gemspec file in the root of the git
-repository. Sometimes it's a variable coming from something like
-`lib/$gem/version.rb`. An example is [beaker](https://github.com/voxpupuli/beaker/blob/f60ac9413f9c7976a6645ef9e1dd2afbcc6542de/beaker.gemspec#L8),
-([version.rb](https://github.com/voxpupuli/beaker/blob/master/lib/beaker/version.rb#L3)). This can be done from a fork.
+This pull request updates the changelog and bumps the version number to the target version.
+The version is set in the gemspec file in the root of the git repository.
+Sometimes it's a variable coming from something like `lib/$gem/version.rb`.
+An example is [beaker](https://github.com/voxpupuli/beaker/blob/f60ac9413f9c7976a6645ef9e1dd2afbcc6542de/beaker.gemspec#L8), ([version.rb](https://github.com/voxpupuli/beaker/blob/master/lib/beaker/version.rb#L3)).
+This can be done from a fork.
 
 Now you can install the changelog generator:
 
@@ -31,25 +31,24 @@ And in case you installed the gems before:
 bundle install; bundle update; bundle clean
 ```
 
-We can generate the changelog (in most cases, this requires a
-[GitHub access token (docs on how to create one)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line):
-the changelog generator expects the token in the environment variable `CHANGELOG_GITHUB_TOKEN`).
+We can generate the changelog (in most cases, this requires a [GitHub access token (docs on how to create one)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line): the changelog generator expects the token in the environment variable `CHANGELOG_GITHUB_TOKEN`).
 
 ```bash
 CHANGELOG_GITHUB_TOKEN='mytoken' bundle exec rake changelog
 ```
 
-The changelog generator checks for certain labels on closed issues and PRs since
-the last release and groups them together. If the changes were neither
-backwards-incompatible nor only bug fixes, make a minor release. Check the
-generated diff for the CHANGELOG.md. If your chosen release version doesn't
-match the generated changelog, update gemspec and run the changelog task again.
+The changelog generator checks for certain labels on closed issues and PRs since the last release and groups them together.
+If the changes were neither backwards-incompatible nor only bug fixes, make a minor release.
+Check the generated diff for the CHANGELOG.md.
+If your chosen release version doesn't match the generated changelog, update gemspec and run the changelog task again.
 
 Get community feedback on the release pr, label it with skip-changelog, get it merged.
 
 ## Part 2: Actually create the release
 
-Checkout an updated copy of voxpupuli master. Do not use a fork here. Or add voxpupuli as a additional remote to your fork.
+Checkout an updated copy of voxpupuli HEAD branch (main or master).
+Do not use a fork here.
+Or add voxpupuli as a additional remote to your fork.
 
 with the main repo
 
@@ -66,10 +65,8 @@ git switch master
 git pull --rebase voxpupuli master
 ```
 
-
-Check with `git tag -l` if the git tags are prefixed with a v or not. This varies
-by project (we often adopt gems from other people and don't want to change the
-versioning scheme in a project).
+Check with `git tag -l` if the git tags are prefixed with a v or not.
+This varies by project (we often adopt gems from other people and don't want to change the versioning scheme in a project).
 
 Create a new git tag with the new version: `git tag -s $version`
 
@@ -87,5 +84,4 @@ with a fork:
 git push voxpupuli $version
 ```
 
-
 Then a GitHub action will start to build the gem and publish it to GitHub Packages and RubyGems.org