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 origin v5.1 - to push the newly created tag

3. git push origin - 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 not important.

5. Ensure that @siedlerchr's Arm64 runner is available, execute Deployment Arm64 workflow for the tag with notarization activated (main works, too).
   Notice for @siedlerchr If the runner was idle for more than 14 days remove old config

   rm .runner
   

   Configure a new self hosted runner

   Start runnner:

   cd actions-runner/
   ./run.sh

6. Wait until completed

7. Download binaries from the tag (This is important for mac because only the tag release gets correctly signed + notarized)

Test Release

1. At least, quickly check if contents in Help - About JabRef are properly replaced.
2. On macOS:

• xcrun stapler validate JabRef-5.3.dmg
• pkgutil --check-signature JabRef-5.3.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.

3. Release to Ubuntu Store

   1. Go to https://snapcraft.io/jabref/releases and release the build version to stable and also to beta and candidate.
   • 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/
   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/vedantmgoyal2009/vedantmgoyal2009/blob/main/winget-pkgs-automation/packages/j/jabref.jabref.json.

Prepare for next version

Ensure that snapcraft build was released. If you did not, you will get in big trouble

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. After a stable release, set pre-release-weight in GitVersion.yml back to 0.

3. Commit the changes for the new dev cycle

   • git commit with message:\

     Show development information
     
     +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 master

4. Remove old binaries at /var/www/builds.jabref.org/www/main and /var/www/builds.jabref.org/www/nightly

5. Edit snapcraft.yml under /snap/ and change the download link to point to the new version cycle

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

7. 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. Add news text to the GitHub release
2. 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 (by using github-contributors-list)
   1. Generate a personal access token
   2. Clone https://github.com/mgechev/github-contributors-list.git
   3. cd github-contributors-list
   4. npm install
   5. cd bin
   6. node githubcontrib --repo jabref --owner jabref --cols 6 --format md --fromDate 2023-09-02 --showlogin true --filter "koppor,calixtus,Siedlerchr,tobiasdiez,but,k3KAW8Pnf7mkmdSMPHz27,HoussemNasri,dependabot[bot],dependabot,apps/dependabot,apps/githubactions,ThiloteE" --authToken "github_pat_XXX". githubg_pat_XXX is your personal access token from step 1. On Windows, use cmd.exe (git bash does not work). --sha {commit-id-of-last-release} also does not work
   7. Paste HTML
   8. Preview
   9. Remove dependabot and githubactions manually.
   10. Double check with https://github.com/JabRef/jabref/graphs/contributors?from=2023-09-02&to=2023-10-22&type=c
   11. Double check with merged PRs: https://github.com/JabRef/jabref/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged. On 2023-10-22, contributors with PRs being merged on the release date did not show up. Example: https://github.com/JabRef/jabref/pull/10497
3. Write a news entry at https://discourse.jabref.org/c/news/5
4. Follow https://github.com/JabRef/jabref/wiki/Information-update-after-a-release/