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

   • Start "Refresh Journal Lists" action (https://github.com/JabRef/jabref/actions/workflows/refresh-journal-lists.yml).
   • This action will create a pull request. This pull request should be merged automatically by a bot.

2. Refresh Citation Style Lists

   • Start the action (https://github.com/JabRef/jabref/actions/workflows/refresh-csl-subtrees.yml).
   • This action will create a pull request. Merge that pull request.

3. Update external-libraries.md. Howto inside.

4. 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

5. GitVersion.yml:

   • No changes required except if there have been alpha / beta releases, or this release is a pre-release.

   • In this case, 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

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

   • grade: stable

7. Create a release commit

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

Do Release

1. git tag v5.1
2. git push upstream v5.1 - 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. 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.

• For GitHub-based builds, we notarize on the tag only

Test Release

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.

   • 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/releases. Trigger a new build to ensure that the latest one of main is used. Then, 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

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.

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/).
   See https://blog.jabref.org/#december-18-2022-%E2%80%93-%F0%9F%8E%84-jabref-5-8-release-%F0%9F%8E%84 for an example for the list of contributors. To get the list of contributors, use github-contributors-list

   1. jbang gcl@koppor/github-contributors-list --repository JabRef/jabref c:\git-repositories\jabref --startrevision=v5.13 --endrevision=v5.15 --filter=koppor,calixtus,Siedlerchr,tobiasdiez,but,k3KAW8Pnf7mkmdSMPHz27,HoussemNasri,apps/dependabot,apps/githubactions,ThiloteE,dependabot[bot],dependabot
   2. Copy and paste the Markdown
   3. Preview
   4. Double check with https://github.com/JabRef/jabref/graphs/contributors?from=2023-09-02&to=2023-10-22&type=c
   5. Double check with merged PRs: https://github.com/JabRef/jabref/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged. On 2023-10-22 (when the JavaScript-variant was used), contributors with PRs being merged on the release date did not show up. Example: https://github.com/JabRef/jabref/pull/10497

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/