Releasing a new Version

How to release a new version

Pre-Conditions

1. Ensure that all tests are green
   1. Execute test locally to ensure everything (especially the fetchers) is working
   2. Some fetchers may not work due to licensing. See https://devdocs.jabref.org/advanced-reading/fetchers how to get keys. More fetchers are enabled locally than on the CI, because of rate limits.
2. Ensure that Snapcraft is running. For instance, at release 5.10, the underlying Ubuntu image (20.04) was too old.

Prepare project files

Hint: You can work on a branch main-release. This will trigger the GitVersion tool, but not indicate a real release. After JabRef works fine, you can push to main.

1. Update Journal Abbreviation List and CSL styles -> These are managed by Dependabot. Trigger Dependabot manually under https://github.com/JabRef/jabref/network/updates for .gitmodules

2. Update SBOM. Trigger workflow Update SBOM and open PR

3. CHANGELOG.md

   • Change version from [Unreleased] to [5.2] – 2020-10-03.
   • Remove empty sections of the release.
   • At the very end of the file:
     [5.2]: https://github.com/JabRef/jabref/compare/v5.1...v5.2

4. GitVersion.yml:

   • No changes required except if a) there was an alpha or beta release before or b) this release is an alpha or beta release

   • In both cases, the tag and the pre-release-weight have to be changed according to:

     New release	tag	pre-release-weight
     alpha	alpha	15000
     beta	beta	30000
     stable	''	50000

     Reason: we need to have an always increasing build number

     You can check the current build number at GitVersion CI output: WeightedPreReleaseNumber": 15516,

5. snap/snapcraft.yml. Check that grade is stable (should be)

   • grade: stable

6. Create a release commit

   • git add CHANGELOG.md (to stage the changes on CHANGELOG.md). Maybe use git gui.
   • git commit -m "Release v6.0"

Do Release

(For alpha/beta releases, one needs to use the main branch. We ensure below that these macOS images are notarized. - Getting GitVersion to output the right numbers on the tag build is too hard.)

1. git tag v6.0. For alpha.x versions, use "pattern" v6.0-alpha.3. The last dot is important. See https://github.com/JabRef/jabref-issue-melting-pot/issues/742 for details.
2. git push upstream v6.0 - to push the newly created tag
3. git push upstream - to push the main branch -- an updated main branch is important for the build of the release to succeed (GitVersion). This update will use the tag pushed in the step before.
4. In case of an alpha/beta release: Manually trigger build on main with notarization enabled. Link: https://github.com/JabRef/jabref/actions/workflows/binaries.yml.
5. Wait until the build completes. DO NOT UPDATE THE main BRANCH. The important build is the build for the tag. The parallel build on main is important for Snapcraft only (and for alpha/beta releases)

• For GitHub-based builds, we notarize on the tag only
• In case of an alpha/beta release, login to build-upload.jabref.org and copy the build from main (/var/www/builds.jabref.org/www/main) to tags.

Test Release

(For alpha/beta releases, one needs to use the main branch. We ensured above that the macOS images are notarized. - Getting GitVersion to output the right numbers on the tag build is too hard.)

1. Download binaries from the tag (This is important for mac because only the tag release gets correctly signed + notarized). https://builds.jabref.org/tags/. Additionally download https://builds.jabref.org/main/JabRef-$version-portable_linux.tar.gz to test the snapcraft build. One can start VMs using some of https://github.com/JabRef/jabref/tree/main/scripts/vms/.
2. At least, quickly check if contents in Help - About JabRef are properly replaced. Also create a new library and create a new entry.
3. Test https://builds.jabref.org/main/JabRef-$version-portable_linux.tar.gz -- this .tar.gz file is also used for the snapcraft release.
4. On macOS:

• xcrun stapler validate JabRef-$version.dmg
• pkgutil --check-signature JabRef-$version.pkg

Publish Binaries

1. FossHub (via developer account)

   • It is very important to do that BEFORE GitHub, because of the auto update feature.
   • Use tools/wget
     • point to the binaries at the build artifacts of GitHub (the ones at https://builds.jabref.org/tag/v5.x also work)
     • After the upload: adjust them under "files".
   • (currently not working) Semi-automatic upload (see Tools - JSON on FossHub)
     • adapt upload-to-fosshub.json
     • POST it to https://www.fosshub.com/JSTools/uploadJson
   • Manual upload:
     • For each file:
       • "Add File"
       • Type: Select fitting type. E.g., "Windows Installer (32 bit)"
       • Version: v5.1
       • Drag file

2. GitHub

   • Ensure that https://builds.jabref.org/tags/ contains a single tag directory only.

   • If an alpha/beta release was made, copy the binaries from main to the tags folder

   • Do a release creation using the GitHub workflow Release binaries on GitHub running on the release tag. This automatically executes following steps:

     • Create new release based on tag.
     • Upload binaries to GitHub release page.

   • Turn the draft into a public release

     • Add CHANGELOG.md text to the GitHub release

3. Snapcraft: Release to Ubuntu Store

   1. Ensure that the branch main was successfully build. snapcraft.yml points to https://builds.jabref.org/main/, which needs to contain the released version.
   2. Go to https://snapcraft.io/jabref/builds. Trigger a new build to ensure that the latest one of main is used. This takes about 8 minutes. Then, go to https://snapcraft.io/jabref/builds. release the build version to stable and also to beta and candidate. Click on "Save"!
   • The release version number should be ending in .60000. If not, there was a push to main meanwhile.
   • Other information is available at https://dashboard.snapcraft.io/dev/snaps/7999/
   • One can use https://github.com/JabRef/jabref/tree/main/scripts/vms/ubuntu to fire up a VM.
   2. On Ubuntu snap install --beta jabref
   3. Test whether JabRef shows the right version

4. WinGet

   • Not necessary anymore, because of https://github.com/vedantmgoyal9/vedantmgoyal9/blob/main/WinGetAutomation/Formula/j/jabref.jabref.json.

5. FlatPak.

   • Check if https://github.com/flathub/org.jabref.jabref/ builds.

Prepare for next version

After snapcraft succeded, one can continue. One really needs to wait for snapcraft, because it relies on the build artifacts of main.

Ensure that snapcraft build was released. If you did not, you will get in big trouble. Main reason: Inside snapcraft.yaml file, https://builds.jabref.org/main/ is used as source for the build.

1. CHANGELOG.md

   • At the beginning of the file:

     ## [Unreleased]
     
     ### Added
     
     ### Changed
     
     ### Fixed
     
     ### Removed
     

   • At the very end of the file:
     [Unreleased]: https://github.com/JabRef/jabref/compare/v5.1...HEAD

2. Edit snapcraft.yml under /snap/ and change the download link to point to the new version cycle. See https://github.com/JabRef/jabref/pull/11467 for an example. - we always use main.

3. Edit https://github.com/JabRef/jabref/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml and change to the new version

4. Update https://github.com/JabRef/jabref/blob/main/.github/workflows/gource.yml to use correct dates and filenames

• gource_title (2x), gource_start_date (2x), mv (at "Store video") (2x), gource_stop_date (1x)

5. After a stable release, set pre-release-weight in GitVersion.yml back to 0.

6. Commit the changes for the new dev cycle

   • git commit with message:

     Start new development cycle
     
     +semver: minor
     

     • Without semver: minor, the version number will not be correct in the about dialog etc.
     • +semver: minor to increase the version number
     • The commit must not be empty (otherwise no build is triggered)
   • git push origin main

7. Remove old builds at /var/www/builds.jabref.org/www/main and /var/www/builds.jabref.org/www/jdk-ea.

8. Check the Milestone list at https://github.com/JabRef/jabref/milestones

   • Go to the milestone of the currently released version.
   • Move all open issues to the next milestone
   • Close the milestone

Spread the word

1. Write a blog entry (at https://github.com/JabRef/blog.jabref.org/).
2. Write a news entry at https://discourse.jabref.org/c/news/5
3. Follow https://github.com/JabRef/jabref/wiki/Information-update-after-a-release/