Releasing a new CKAN client

When merging pull requests

Easy

1. git checkout master
   bin/ckan-merge-pr.py pr_num

2. The script will pull and merge the PR's changes, add a line to the top of the change log, and open the change log in your editor
3. Move the change log entry to the right section and replace the "UNKNOWN" tag with the appropriate tag for the change, then save and close your editor
4. The script will commit the changes with an appropriate commit message
5. Inspect the merge in your working copy; if everything looks OK:

   git push

Advanced

Merging pull requests is a great time to update CHANGELOG.md. You can do this as a separate commit on master, but with a bit of git-fu you can update it as part of the merge commit itself!

$ git checkout master
$ git merge someuser/somebranch --no-commit --no-ff # This merges your PR, but doesn't commit it.
$ vim CHANGELOG.md                                  # Or whatever your favourite editor is, if not vim.
$ git add CHANGELOG.md
$ git commit -m 'Merge #<PR-Num> <Description>'     # This commits the merge, *and* your changes to CHANGELOG.md
$ git push

This has the advantage that if the merge is undone, so is the changelog entry.

Making sure the changelog is up-to-date is important for our next step, which is...

Before the release

1. Build the final code base and test that CKAN will launch on both Windows and Linux, will install, remove and update mods.
2. Ideally, create a Pre-release first and ask the @MacOS-Testers and @Wranglers teams to try the new client and report any issues.

Making a release!

CKAN releases are mostly automated, but the full process is:

1. Update the release number in the changelog. Releases should have an even release (patch) number. The Minor version number must be updated if the release includes any changes to the Spec. Don't add the release name to the changelog yet.
2. Add an entry to the Download-Counts.md file
3. Go to draft a new release, fill in the version (don't forget the leading v; eg v1.2.3), and title (which is a cool release name of your choosing).
4. We traditionally have a release picture that relates to the title. The textbox at the bottom lets you upload a picture. While it looks funny, you can use the standard [title](url) markdown syntax to make a link, except instead of a title you have a the image reference (![](url...)). If you're unsure, look at the text of a previous release to see what it looks like.
5. Have a line of three dashes (---) by themselves, with a blank line on either side, after the release image. The updater program expects to see this, so it doesn't include the image in the text-only release notes.
6. Copy'n'paste in the release notes for this version, usually from the changelog. Add extra notes if necessary.
7. Add another line of three dashes, and provide attribution for the release image. Again, the updater program expects to see this.
8. Hit the release button and celebrate!

You do not need to build the binary. Our GitHub release work flow will see the new tag, build a binary, run it through tests, and upload the assets when complete. Once they're uploaded, the client updater will show a new release is available to users and ask if they wish to upgrade.

After the release

1. Post the change log to the Discord #announcements channel.
2. Update the forum thread topic with the version and date of the new release.
3. Post in the forum with release notes and a link to the releases page.
4. Start a new "unreleased" stub in the changelog file and push the release number to the next odd integer.
5. Congratulate yourself on a job well done!

Improvements that can be made to the release process

Right now the release project requires a human to copy'n'paste in a changelog, which is silly, because that could be done by a bot. In the future the ideal release process would simply be choosing a release name and image, and having bots do the rest.