dragonx/doc/release-process.md

DragonX Release Process

High-Level Philosophy

Beware of making high-risk changes (such as consensus changes, p2p layer changes and wallet/transaction changes) too close to a new release, because they will not get as much testing as they should. Don't merge large branches which haven't undergone lots of testing just before a release.

It is best to keep doc/relnotes/README.md up to date as changes and bug fixes are made. It's more work to summarize all changes and bugfixes just before the release.

Branch model

Development happens on the dev branch. Releases are cut on the default branch, master. Code changes should land on dev first and undergo testing before being merged into master.

Check for changes on master that should be on dev

Occasionally trivial changes are made directly on the master branch, such as documentation changes. In theory, no code changes should happen on master without being on dev first, but it's better to be safe than sorry. We want the dev branch which undergoes testing to be as close as possible to what the master branch will become, so we don't want to merge dev into master and just assume everything works. So it's best to merge the master branch into dev just before merging the dev branch into master.

To check if the master branch has any changes that the dev branch does not:

# this assumes you are working with https://git.dragonx.is/DragonX/dragonx as your remote
git checkout dev
git pull                  # make sure dev is up to date
git checkout master
git pull                  # make sure master is up to date
git diff dev...master     # look at the set of changes which exist in master but not dev

If the last command has no output, congrats, there is nothing to do. If the last command has output, then you should merge master into dev:

git checkout dev
git merge master
git push origin dev

Use the --no-ff flag when merging dev into master for a release (see below). The --no-ff flag makes sure to make a merge commit, no matter what, even if a "fast forward" could be done. For those in the future looking back, it's much better to see evidence of when branches were merged.

Git Issues

Look for Git issues that should be fixed in the next release. Especially low-risk and simple things, like documentation changes, improvements to error messages and RPC help output.

Pre-release checklist:

• Is this release changing consensus rules? Definitely update protocol version.

Protocol Safety Checks:

• Does PROTOCOL_VERSION in src/version.h need to be increased?
  • All releases with a consensus change should increase the value by 1
  • All releases with a large change to the networking (P2P) layer should increase the value by 1
  • This identifies a nodes protocol version to all other peers it connects to.
• Does MIN_PEER_PROTO_VERSION in src/version.h need to change?
  • If it does, new nodes will not be able to talk to nodes with a version less than MIN_PROTO_VERSION
• The main use of these is for newer nodes that know they do not want to talk to older nodes to prevent connecting to older nodes efficiently
• For instance, when a new release has different consensus rules than older nodes, MIN_PROTO_VERSION prevents wasting lots of network bandwidth talking to incompatible nodes which will eventually be banned for disagreeing on consensus rules

Release dependencies

Install deps on Linux:

apt-get install help2man devscripts

Release process

• If new seeds are being added or seeds are changing:
  • Edit contrib/seeds/nodes_main.txt
  • Run "make seeds"
  • Commit the result
• Update version in configure.ac and src/clientversion.h to update the dragonxd version
  • The new version MUST be higher than every version already tagged, including tags that were never built or published. Check with git tag -l --sort=-v:refname | head. Two trees stamped with the same CLIENT_VERSION are indistinguishable on the wire, in getnetworkinfo, and to the wallet's in-app updater — and a published archive that does not match its tag destroys the only provenance check users have.
  • In src/clientversion.h you update CLIENT_VERSION_* variables. Usually you will just update CLIENT_VERSION_REVISION
  • If there is a consensus change, it may be a good idea to update CLIENT_VERSION_MINOR or CLIENT_VERSION_MAJOR
  • To make a pre-release "beta" you can modify CLIENT_VERSION_BUILD but that is rarely done.
  • A CLIENT_VERSION_BUILD of 50 means "actual non-beta release"
  • Make sure to keep the values in configure.ac and src/clientversion.h the same. The variables are prefixed wth an underscore in configure.ac
• Run ./util/gen-manpages.sh, commit + push results
  • There is a hack in the script where you can hardcode a version number if dragonxd isn't compiled on this machine
  • Comment out the version line and uncomment the line above it with a hardcoded version number
  • PROTIP: Man page creation must be done after updating the version number and recompiling and before Debian package creation
  • TODO: How to regenerate html man pages?
• Update checkpoints in src/chainparams.cpp via util/checkpoints.pl
  • Run "./util/checkpoints.pl help" to get example usage
  • dragonxd must be running to run this script, since it uses dragonx-cli to get the data
  • Look for the line which marks the end of the mainnet checkpoint data in chainparams.cpp, that is where checkpoint data ends
  • Find the highest block height of checkpoint data, let's call it HEIGHT
  • Run ./util/checkpoints.pl 1000 HEIGHT &> checkpoints.txt to generate the latest checkpoint data
  • To copy the new data from checkpoints.txt into the file, one way in Vim is to type ":r checkpoints.txt" which will read in a file and paste it as the current cursor
  • You will see 3 lines of "stats" at the end of the output, you just pasted in the newest stats. Delete the old stats that should be the 3 lines under the current stats
  • Make sure the new code compiles, commit and push
  • Run ./util/checkpoints.pl help to see some basic help
    • By default it will generate checkpoints for every 1000 blocks, the "stride"
    • You can get a different "stride" by passing it in as the first arg to the script
    • To get checkpoint data for every 5000 blocks: ./util/checkpoints.pl 5000 &> checkpoints.txt
  • checkpoints.pl will just generate the data you need, it must be manually copied into the correct place
  • Checkpoints are a list of block heights and block hashes that tell a full node the correct block history of the blockchain
  • Checkpoints make block verification a bit faster, because nodes can say "is this block a descendant of a checkpoint block?" instead of doing full consensus checks, which take more time
  • Checkpoints also provide a bit of security against some attacks that would create malicious chainforks
    • They only provide limited security, because they talk about the past, not future block heights.
  • Try to generate checkpoints as close to the release as possible, so you can have a recent block height be protected.
    • For instance, don't update checkpoints and then do a release a month later. You can always update checkpoint data again or multiple times
• Update doc/relnotes/README.md
  • To get the stats of file changes: git diff --stat master...dev
• Do a fresh clone and fresh sync with new checkpoints
• Stop node, wait 20 minutes, and then do a partial sync with new checkpoints
• Merge dev into master: git checkout dev && git pull && git checkout master && git pull && git merge --no-ff dev && git push
  • The above command makes sure that your local dev branch is up to date before doing anything
  • The above command will not merge if "git pull" creates a merge conflict
  • The above command will not push if there is a problem with merging dev
• Make Gitea release with git tag from the master branch (make sure to merge dev in first)
  • Make sure git tag starts with a v such as v1.0.3
  • The tag MUST be annotated (git tag -a v1.3.0 -m 'DragonX v1.3.0'), not lightweight. util/genbuild.sh calls git describe without --tags, which only ever sees annotated tags — a lightweight tag makes the build stamp itself v<older-tag>-<sha> instead of the release version. v1.0.0 through v1.0.3 are lightweight, which is why their builds are labelled that way.
  • Verify before building: git describe must print exactly the tag, with no -<n>-g<sha> suffix.
• Use ./build.sh (container-based, see doc/build-containers.md) or util/gen-linux-binary-release.sh to make a Linux release binary
• Sign every archive and publish the signatures. This step is mandatory and was missing from this document until v1.3.0 — its absence is why v1.1.0 and v1.2.0 were tagged but never became installable releases.
  • The wallet's in-app daemon updater pins an ed25519 public key in ObsidianDragon/src/util/daemon_updater.h and sets kDaemonRequireSignature = true. An update is refused outright unless a valid <archive>.sig is published beside the archive. No signature means every existing user silently stays on their old daemon.
  • Sign with ObsidianDragon/scripts/sign-daemon-release.sh:
    • scripts/sign-daemon-release.sh sign <secret.key> <archive>... produces <archive>.sig (base64 of a detached 64-byte ed25519 signature over the exact archive bytes)
    • or scripts/sign-daemon-release.sh release <secret.key> <version> to zip, sign, and print the checksum table in one step
  • Keep the secret key offline, mode 600. The matching base64 public key must already be pinned in kDaemonSignaturePublicKeyBase64.
• Upload each Linux binary archive and its .sig to the Gitea release
• Paste the SHA-256 checksum table into the release body as markdown rows of the form | <archive>.zip | |. The updater parses this table and will not install an archive that is absent from it.
• Confirm the release is actually consumable before announcing it: the updater looks for an asset whose name contains "-" + platformToken + ".zip" (linux-amd64, macos, win64). An archive named for a distro variant instead of the platform token is invisible to it.
• Create an x86 Debian package for the release:
  • Edit contrib/debian/changelog to add information about the new release
  • Use util/build-debian-package.sh to make an x86 Debian package for the release
  • Debian packages should be done after you make manpages, because those are included in Debian packages
  • lintian is an optional dependency, it's not needed to build the .deb
  • Upload .deb to Gitea release
  • Add SHA256 checksum of .deb to release
• ARM Debian package: util/build-debian-package-ARM.sh is referenced here historically but is not present in the tree. Skip, or restore the script first.
• Upload the debian packages to the Gitea release page, with SHA256 sums

Platform-specific notes

• Use ./util/build-mac.sh to compile on Apple/Mac systems
• Use ./util/build-win.sh to build on Windows

Optional things

Updating RandomX

If you need to update the source code of our in tree copy of RandomX, open an issue in the DragonX Git repository to track the details. Currently we use RandomX v1.2.1 from the official repo at https://github.com/tevador/RandomX/releases/tag/v1.2.1