Release Process

[nbougalis]

The transition of the repo to the XRP Ledger Foundation is complete, but that's only one step. Having documented and established processes and guidelines for things like merging pull requests, creating releases, the general release process etc. is important not only for the long-term health and success of the project but to contributors, both existing and new.

The team at Ripple had a process which we used (albeit not always to the letter; to be clear, it's not perfect; far from it, in fact. But it has been refined over several years, and it may make a good starting point for a discussion among maintainers, developers and anyone else interested in participating.

I hope that this will be a engaging and exciting (but civil!) discussion which will allow us to distill our thoughts into a better process for us to adopt going forward.

Please note that some parts of this document, like the announcement generation script, are outdated or even obsolete.

---

The three primary branches are develop, release, and master. In the most common case, new development is merged into the develop branch. Release candidates (RC) are merged to the develop and release branches and final releases are merged to the develop, release, and master branches. The master branch always contains the most recently released version of rippled.

Beta

A beta release reflects a synchronization point during development towards a release. The beta release should have no known defects based on unit tests and local development but has not yet gone through extensive integration testing on the devnet/mainnet.

Prepare a beta branch

If there are commits that are on the release branch but not in the develop branch, then merge those commits into the develop branch first. This can happen when additional RCs are created during the release cycle for a previous release while newer betas are cut for the current release cycle.

Prepare a working develop-next branch for the beta.

$ git checkout develop
$ git pull upstream develop # upstream is a git remote for https://github.com/XRPLF/rippled.git
$ git checkout -b develop-next
$ git push --set-upstream origin develop-next

Choose a set of PRs to include. Selected PRs should have at least two approving reviews and no vetos. It would be helpful if maintainers apply the "Passed" label.

For each PR, find the author's fork and branch. Check that no unexpected changes have been added to the branch since it was marked pass.

$ git fetch author branch  # author is a git remote for https://github.com/author/rippled.git
$ git checkout author/branch
$ git rebase --preserve-merges origin/develop-next

# if there are changesets to [FOLD], use $ git rebase -i to squash them
# if there are conflicts, go back to the developer, or use $ git rebase -i

$ git checkout develop-next

# Here you get a long message from Git ending with:
#
# git branch <branch> <commit>
#
# Note that commit ID, and then execute:

$ git merge --ff-only <commit>

Update the version number in src/ripple/protocol/impl/BuildInfo.cpp:

index 90cb0ec7d..0a44b0e8e 100644
@@ -34,7 +34,7 @@ char const* const versionString =
     //  The build version number. You must edit this for each release
     //  and follow the format described at http://semver.org/
     //
-        "0.80.0"
+        "0.80.1"

 #if defined(DEBUG) || defined(SANITIZER)
        "+"

Commit and sign this change.

$ git add src/ripple/protocol/impl/BuildInfo.cpp
$ git commit -S<keyid>
$ git push

Propose the beta branch

Create a Pull Request on GitHub for this develop-next branch to merge into develop.

In the description of the Pull Request, include close GitHub commands for each open PR in the beta branch. For example:

If merged this PR will:

close: #123
close: #128

Verify CI passes.

Ensure that the code builds locally and syncs with the network.

Release the beta

To release, please DO NOT USE GITHUB WEB INTERFACE to close the PR. Instead:

# dry run to be sure things are ok
$ git push -vn upstream develop-next:develop
# push for real
$ git push upstream develop-next:develop

Verify that all the integrated Github PRs were automatically closed. Close any stragglers, leaving a comment with the hash of the tip of the beta branch.

Finally, the PR for the beta branch itself should have closed automatically. Close it manually if it didn't.

Release

A release is a new iteration of the software that we hope will be adopted and deployed by a majority of participants across the network. It culminates a series of beta releases (e.g. x.y.z-b1, x.y.z-b2,...). The release cycle itself may involve a series of release candidates (x.y.z-rc1,x.y.z-rc2,..) before the final release (x.y.z).

Release candidate

Create an initial release candidate, e.g. x.y.z-rc1 based on the current develop branch.

Follow the steps above for creating and proposing a beta branch, but do NOT release it.

The only new commits should be bug fixes for PRs already merged into the beta, and the signed commit that updates the version number.

Push the branch to close the PR. DO NOT USE THE GITHUB WEB INTERFACE. Do not push to develop if there is a newer beta on that branch for the next release cycle.

$ git push -vn upstream develop-next:develop
$ git push upstream develop-next:develop
$ git push -vn upstream develop-next:release
$ git push upstream develop-next:release

Test.

Deploy the release candidate to the devnet.

Perform stress and performance testing against the devnet.

Deploy the proposed release on at least some servers operating against the main network, and consider dogfooding (i.e. running a server yourself)

Final release

Prepare as above.

Once confident that all tests pass (including performance and stress tests!) with no regressions, prepare a short testing report, outlining the results. This is a pre-qualification requirement for the final release. (TODO: Consider improving on this item: test scope review, test case review, and final test report review. Verification is important, we should not only rely on unit tests.)

Create a new commit that updates the version appropriately and documents the changes in the RELEASENOTES.md file.

• Update the summary section. (TODO: Consider improvements here. One possible consideration is to ask developers to leave a better commit message if they think it should be mentioned in release notes, this way we can just take the commit message.)
• New and updated features sections should include features only. Prioritize amendments to be listed first. Then sort the new and updated features by their importance/impact on the network and list them in order. Not all items need to be listed.
• One thing we should always do in the release notes and blog posts is to have a dedicated section outlining the names of new amendments that are introduced.
• Bug fixes and Improvements section is similar to the "New and Updated Features" section: list amendments first then order them by importance/impact. Not all items need to be listed.

Once that is done, please propose a PR for review.

Run Nik's announcement generation script located here to generate the initial input for release announcements. (Improvements needed for the script: lifetime contributors should be automated, delete dupe for contributors and ungroup external vs rippled labs for contributions.)

The output of that script can be used as a starting point for blog posts (e.g. on xrpl.org) and mailing lists announcements (i.e. ripple-server mailing list)

The announcements should be released AT LEAST 24 hours ahead of the actual code push, but that may not be always possible (e.g. hotfixes). (TODO: consider improvements here, including potentially additional rounds of announcements for release candidates?)

The release should be pushed only after a maintainer has signed off on the final PR. Push branches but again DO NOT USE THE GITHUB WEB INTERFACE. Do not push to develop if there is a newer beta on that branch for the next release cycle.

$ git push upstream develop-next:develop
$ git push upstream develop-next:release
$ git push upstream develop-next:master

Also please tag and release in Github.

Use the command line:

# Change these commands to use the correct version number.
$ git tag 1.6.0
$ git push -v upstream 1.6.0:1.6.0

Go to https://github.com/xrplf/rippled/tags and add the release title and release notes. Use the same text in RELEASENOTES.md.

Or use the web interface. Use the same text in RELEASENOTES.md. Tag the commit that updates the version number with the final release version.

Hotfix

A hotfix release fixes a bug in an existing released version of rippled.

Follow the checklist for a release candidate, except branch off of the release branch. Some steps may be optional depending on the nature of the fix and the urgency of the release.

TODO: consider ways to improve this process, given the sensitivity around hotfixes, especially those that may relate to bug reports and the potential severity and impact of the issue being addressed.

[cbistriceanu]

Hi Nick, can you please let me know or provide any evidence on the current XRPL code where validators are not using the default Ripple list of UNL's? On the XRPL.org I can see that anyone spinning up a validator is able to change that default list of UNL's but I am wondering if new nodes and users are actually changing that XRPL recommended list and parties have and are changing the UNL's that connect to.

[MarkusTeufelberger]

UNLs are private to the node operator and if you find any evidence or way to construct a UNL for a validator you don't own please consider getting in touch with the security team at Ripple. You might also be eligible for a bug bounty.