Netty.docs: Releasing new version

Before getting started

Read the OSSRH guide from Sonatype.
Create a GnuPG key to sign the artifacts.

Configure your ~/.m2/settings.xml contains the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <servers>
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>myusername</username>
      <password>mypassword</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>myusername</username>
      <password>mypassword</password>
    </server>
  </servers>
  ...
</settings>

Netty 4.x

The release procedure is currently a mix of executing a GitHub Action workflow and running a few scripts to finish the release process on macOS (64-bit). Install the required packages as well.

Start the release process using GitHub Actions

The release is mostly automated these days (and will be fully automated in the future hopefully). To start a release all you need to do is to run the GitHub Action release workflow. The workflow will take care of building all the native libraries and also the normal jars. Once complete it will automatically stage everything to the nexus staging repository. Monitor the GitHub Action release workflow and wait till it's complete.

Finish the release

Netty 4.x releases must be done by using OpenJDK8 which can be downloaded from AdoptOpenJDK. Once downloaded and installed create a JAVA8_HOME env which points to the installation.

For example:

export JAVA8_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home

Once this is done you are ready to finish the release.

First get the name of the current staged release (this release was staged by the GitHub workflow before).

./scripts/list_staged_release.sh

Now with this staging id you can run the script to finish the release. The script takes the staging id as first argument and the name of the tag as the second. So for example if you would try to finish the release of netty 4.1.64.Final you would run the following command:

./scripts/finish_release.sh ionetty-1395 netty-4.1.64.Final

Once the script completes the release of netty itself is done and it will be "promoted" to maven central.

Now it's time to copy over all the apidocs and xref files to the netty website (if you didn't checkout the website yet read [Update the web site|Releasing-new-version#update-the-web-site]).

For this we have another script that you need to run:

./scripts/generate_docs.sh ../netty-website netty-4.1.64.Final

What to do in case of failure ?

It is possible the scripts/finish_release.sh may fail as the validation failed:

[ERROR] Failed to execute goal org.sonatype.plugins:nexus-staging-maven-plugin:1.6.8:rc-close (default-cli) on project netty-parent: Could not perform action: there are failing staging rules!: Staging rules failure! -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
[ERROR]
[ERROR] After correcting the problems, you can resume the build with the command
[ERROR]   mvn <args> -rf :netty-parent

In this case login to https://oss.sonatype.org and check why the validation failed and fix it. Once done re-run the script.

Update the web site

Our official web site is built with Awestruct. Please make sure you are familiar with Awestruct and its related markup languages such as HAML and Markdown.

If you did not yet, clone the web site project:

git clone [email protected]:netty/netty-website.git
cd netty-website

If you don't have Awestruct installed yet the easiest way to do so is to use bundler:

gem install bundler

After this is done ensure you have all dependencies installed by executing bundle in the netty-website directory. This will take care of installing all the needed dependencies and Awestruct itself. Note, if you don't want bundler to install the dependencies system-wide, you can tell it to keep them local to the netty-website directory by running bundle config set --local path .bundle inside the netty-website directory.

bundle

_config/site.yml contains important metadata about the latest Netty versions. For example, it has the following section:

releases:
  - version: 4.1.65.Final
    date: 19-May-2021
    stable: stable
  - version: 4.0.56.Final
    date: 05-Feb-2018
    stable: true
  - version: 3.10.6.Final
    date: 29-Jun-2016
    stable: true

Update it with the new version number and release date.

After this add a new entry to the news/ folder which has the release details. Make sure the file name does not contains a dot (.) or a whitespace (e.g. OK: 2014-07-04-4-1-0-Beta1-released.html.md NOT OK: 2014-07-04-4.1.0.Beta1-released.html.md

Try to generate the web site to confirm that the new version shows up in the generated web site.

This can done via:

bundle exec awestruct -d -u https://netty.io

Now you should be able to access the website via http://localhost:4242.

If everything looks like expected its time to commit the changes:

git add *
git commit -m "Release 4.1.64.Final"
git push

After this the website will be automatically build and deployed by a GitHub action.

Netty/TomcatNative

TODO: Write me

Netty/Incubator/Transport/Native/io_uring

The release procedure is fully automated via GitHub Actions. To start a release all you need to do is to run the GitHub Action release workflow. The workflow will take care of building all the native libraries and also the normal jars. Once complete it will automatically stage everything to the nexus staging repository and release it to central maven.

Nothing needs to be done manually, that said you may consider writing a release announcement and push it to the website.

Netty/Incubator/Codec/Http3

Nothing needs to be done manually, that said you may consider writing a release announcement and push it to the website.

h3spec-maven-plugin

Nothing needs to be done manually, that said you may consider writing a release announcement and push it to the website.

Netty/Incubator/Codec/Quic

The release procedure is currently a mix of executing a GitHub Action workflow and running a few scripts to finish the release process on macOS (64-bit). Install the required packages as well.

Start the release process using GitHub Actions

Finish the release

Netty/Incubator/Codec/Quic releases must be done by using OpenJDK8 which can be downloaded from AdoptOpenJDK. Once downloaded and installed create a JAVA8_HOME env which points to the installation.

For example:

export JAVA8_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home

Once this is done you are ready to finish the release.

First get the name of the current staged release (this release was staged by the GitHub workflow before).

./scripts/list_staged_release.sh

./scripts/finish_release.sh ionetty-1398 netty-incubator-codec-quic-0.0.13.Final

Once the script completes the release of netty itself is done and it will be "promoted" to maven central.