This document uses "0.x.0" throughout as an example version number. Whenever you see this, you should substitute the version number of the new release being prepared.

Paths are specified in git syntax, i.e. :/ is the repository root.

This document assumes you are using a Linux-based OS. While it should be possible to cut a release on Windows, using e.g. the Git for Windows SDK or a MinGW environment, the names and/or arguments to some commands may be different.

In addition to the build and test requirements for Uncrustify itself (CMake, a C++ compiler, Python, git), you will also need:

• tar
• python3-git
• Binutils-mingw-w64
• Gcc-mingw-w64
• G++-mingw-w64
• zip
• wget (optional)
• scp (to update documentation on the SourceForge page)

Using packages provided by your OS distribution is strongly recommended. (Exact package names may vary depending on your distribution.) Examples use wget to download files via command line, but any mechanism of obtaining files over HTTPS may be employed.

Prior to making a release, verify that the repository is in a stable state and that all CI (continuous integration) tests have passed. This should ensure all tests pass and building is working, including cross-compiling for Windows.

Before starting the release process, first check that:

• your local clone of uncrustify/uncrustify is up to date (don't use your uncrustify fork clone for preparing a release)
• you are on the master branch
• CMAKE_BUILD_TYPE is set to Release (or RelWithDebInfo)
• you have a valid PAT for your admin account. See below on how to get a new PAT if needed.
• .git/config contains your PAT information. Again see below.

Info about PAT can be found here: https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

To get a new PAT for your admin account follow these steps:

• login with an admin account at https://github.com/uncrustify/uncrustify

• on the right, click on the photo

• scroll down to "Settings"

• on the left, scroll down to "Developer settings", and click

• on the left, click on "Personal access tokens"

• choose "Tokens (classic), click

• if necessary "Delete" expired token(s)

• click on "Generate new token"

• choose "Generate new token (classic)", click

• choose a "what's this token for"

• click on "repo"

• scroll down to bottom and click on "Generate token"

• make sure to copy your personal access token now. You won’t be able to see it again!

• copy the token "ghp_******"

• update the file .git/config using the new token

  [remote "origin"]

  url = https://<admin account>:<PAT>@github.com/uncrustify/uncrustify.git

• check that the PAT is correct with: .. code:

  $ git config --local --get remote.origin.url
  

First update the list of authors with:

$ ./scripts/prepare_list_of_authors.sh

Build uncrustify (including builds for Windows) and verify that they are successful and all tests are passed. See section "Create Binaries" below for the required steps.

Run the following commands to start the release preparation:

$ ./scripts/release_tool.py init
$ ./scripts/release_tool.py update path/to/uncrustify

(Replace path/to/uncrustify with the path to the Uncrustify executable you just built, e.g. build/uncrustify.)

This will create a branch for the release candidate and perform some automated updates to various files. With no arguments, init will prompt you for the new version number, defaulting to x.(y+1).0, where x.y.z is the previous release. The --version argument may also be used to specify the version (e.g. if the script will not be able to prompt for input).

After, you should check that the following files show the correct version number and option count:

• :/CMakeLists.txt (version number only; look for UNCRUSTIFY_VERSION)
• :/package.json (version number only; you'll see it, the file is tiny)
• :/README.md (look for "options as of version")
• :/documentation/htdocs/index.html (look for "options as of version")

(Note that uncrustify itself will not show the new version number until the final release has been tagged.)

Update :/ChangeLog. There is a helper script, :/scripts/gen_changelog.py, that can help extract new options since the previous release:

$ ./scripts/gen_changelog.py uncrustify-0.0.0

Replace 0.0.0 with the version of the previous release. This will generate a bunch of output like:

0123456789abcdef0123456789abcdef01234567
  Added   : better_name                          Jan 13 1970
  Removed : poor_name                            Jan 13 1970
fedcba9876543210fedcba9876543210fedcba98
  Added   : new_option_1                         Jan 18 1970
  Added   : new_option_2                         Jan 18 1970

Copy the output from the script at the top of :/ChangeLog and add a new release header (don't forget to add the date!)

Inspect your working tree. Use git add -p to stage the changes made to the documentation and other artifacts that contain version-dependent information. Verify that only desired changes are staged and that your working tree is otherwise clean.

When you are ready, commit the changes using:

$ ./scripts/release_tool.py commit

(If you prefer, you can also commit the changes manually; the script just fills in the commit message for you.)

Push the release candidate branch to GitHub and create a pull request. Make sure to use your NON-admin account for creating the pull request, so that later you can use your admin account to approve it.

$ git push -u origin HEAD

This will push the branch and commit to the remote upstream and will print out a link that you can use to create a pull request in a web browser.

Once the pull request has completed the various CI checks, merge it.

Switch to master branch and check out the latest commit that includes the previously merged pull request and then tag the release using:

$ ./scripts/release_tool.py tag

Note that this will only work if the merge of the release candidate is the most recent commit upstream. Otherwise, the merge commit must be specified by using the -c option. The command will automatically push the tag upstream as well.

You can check the new tag with the following commands, which will list all existing tags locally and remotely, respectively

git tag
git ls-remote --tags origin

(Tagging the release does not need to be done on any particular branch. The command will not affect or look at your work tree at all.)

Finally, delete the release branch upstream and locally

$ git push -d origin <release branch name>
$ git branch -D <release branch name>

Create a tarball and zip archive of the sources:

$ cd /path/to/uncrustify
$ git archive -o ../uncrustify-0.x.0.tar.gz --prefix=uncrustify-uncrustify-0.x.0/ uncrustify-0.x.0
$ cd /path/to/uncrustify/..
$ tar xzf ./uncrustify-0.x.0.tar.gz
$ zip -r uncrustify-0.x.0.zip uncrustify-uncrustify-0.x.0

Build the Linux binaries:

$ cd /path/to/uncrustify-uncrustify-0.x.0
$ mkdir build
$ cd build
$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
$ ninja
$ ctest
$ ./uncrustify --version

Next, build the 32 and 64 bit Windows binaries:

$ cd /path/to/uncrustify-uncrustify-0.x.0
$ mkdir buildwin-32
$ cd buildwin-32
$ cmake -G Ninja \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw32.cmake \
        -DCMAKE_EXE_LINKER_FLAGS="-static -s" \
        ..
$ ninja
$ cpack

$ cd /path/to/uncrustify-uncrustify-0.x.0
$ mkdir buildwin-64
$ cd buildwin-64
$ cmake -G Ninja \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw64.cmake \
        -DCMAKE_EXE_LINKER_FLAGS="-static -s" \
        ..
$ ninja
$ cpack

• Login with an admin account at https://github.com/uncrustify/uncrustify

• Navigate to https://github.com/uncrustify/uncrustify/releases and click on the "Draft a new release" button at the top of the page

• Select the corresponding release tag under the "Choose a tag" combobox

• Add the release version under "Release title" as "Uncrustify 0.xx.y"

• Upload the Windows binaries and the source code zip/tarball files in the section "Attach binaries by dropping them here or selecting them": these will show up as "Assets" under the release text. The following files need to be added:

  • buildwin-32/uncrustify-0.x.0_f-win32.zip
  • buildwin-64/uncrustify-0.x.0_f-win64.zip
  • uncrustify-0.x.0.tar.gz
  • uncrustify-0.x.0.zip

• Add release text in describing section. It is recommended to copy the text from previous releases and update the related files. Make sure to use bold text to highlight the various sections (use '### ' at the beginning of the line). You need to drag the files into the text section to get a link to the actual files there. The same files mentioned above need to be added.

• Publish the release by clicking on the "Publish release" button.

• Login as admin under https://sourceforge.net/projects/uncrustify/

• Change to https://sourceforge.net/projects/uncrustify/files/

• "Add Folder"; the name should be e.g. "uncrustify-0.x.0"

• Navigate to the new folder (e.g. https://sourceforge.net/projects/uncrustify/files/uncrustify-0.x.0/)

• Click "Add File" and upload the following files (adjusting for the actual version number): Click "Done" when all files have been uploaded.

  • README.md
  • uncrustify-0.x.0.tar.gz
  • uncrustify-0.x.0.zip
  • buildwin-32/uncrustify-0.x.0_f-win32.zip
  • buildwin-64/uncrustify-0.x.0_f-win64.zip

• Upload the documentation using the following commands:

  $ cd /path/to/uncrustify
  $ scp -r documentation/htdocs/* ChangeLog \
    USERNAME,uncrustify@web.sourceforge.net:htdocs/
  

The new release is live! Spread the word! Consider these ideas:

• Create a news item.
• Update freshmeat.net project.

The following list serves as a quick reference for making a release. These items are explained in greater detail above.

1. Verify that CI passes
2. Use release_tool.py to initialize the release and perform automated updates. Check:
   1. :/CMakeLists.txt
   2. :/package.json
   3. :/README.md
   4. :/documentation/htdocs/index.html
3. Update documentation as needed:
   1. :/ChangeLog
   2. :/man/uncrustify.1.in
4. Stage changes.
5. Test everything again.
6. Finalize the code changes.
7. Push to GitHub and create a merge request.
8. Tag the merged release branch.
9. Create Windows (32- and 64-bit) binaries.
10. Run a test build on Linux.
11. Create release on Github.
12. Upload the release and documentation to SourceForge.
13. Announce the release!