Skip to content

Releasing a new Version

Oliver Kopp edited this page Jul 15, 2024 · 131 revisions

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

  2. Refresh Citation Style Lists

  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
    • (currently not working) Semi-automatic upload (see Tools - JSON on FossHub)
    • 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:

    • 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"!
    1. On Ubuntu snap install --beta jabref
    2. Test whether JabRef shows the right version
  4. WinGet

  5. FlatPak.

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

  2. 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
  3. Remove old builds at /var/www/builds.jabref.org/www/main and /var/www/builds.jabref.org/www/jdk-ea.

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

Clone this wiki locally