Versions Compared

Old Version 228

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Excerpt
hiddentrue

Step by step of how to perform a new DSpace Release via Maven


Note

This document is intended to be kept up to date by the DSpace Release Team.  It details the steps necessary to perform snapshot and official releases of DSpace and supporting Modules.

...

  1. Write access to the DSpace GitHub repository hosted at https://github.com/DSpace/DSpace. (All Committers should already have this, obviously)
  2. Write access to the org.dspace groupId in the snapshot and staging repositories hosted at oss.sonatype.org.  If you don't already have this, you will need to:
    1. Sign up for a Sonatype JIRA account. This account will also serve as your login to the Sonatype OSS system. (If you already have a Sonatype account, you can skip this step)
    2. Ask a Committer with release privileges (e.g. a previous release manager) to request that your Sonatype account be given release privileges to the "org.dspace" GroupID. This request should be submitted via the Sonatype JIRA system in the Open Source Project Repository Hosting project.
    3. Once Sonatype gives you the proper authorization, you should be able to login to the Sonatype OSS system using the same login/password you setup in Sonatype JIRA. You should also have access to publish new releases to the "org.dspace" GroupID.
    4. NOTE: The full details of signing up and getting access to Sonatype are also posted online here: Sonatype Maven Repository Usage Guide
  3. You must generate and publish your own personal Code Signing Key (required by Sonatype). Here are two sites that give hints on how to do that:

Update Maven settings.xml with Sonatype User Token

Generate / Access your Sonatype User Token via the instructions at https://central.sonatype.org/publish/generate-token/

DSpace's root pom.xml already has the correct staging and snapshot repositories listed in the OSS parent's '<distributionManagement>' section.  In order to deploy, you will need to add your Sonatype OSS username and password OSSRH user token to your local ~/.m2/settings.xml file. For example:

Code Block
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <!--Login User infoToken for Sonatype SnapShotOSSRH Maven repository -->
    <server>
      <id>ossrh</id>
      <username>YourSonatypeUsername</username>
      <password>YourSonatypePassword</<!-- To generate a User Token (random username & password), follow instructions at
         https://central.sonatype.org/publish/generate-token/ -->
    <server>
      <id>ossrh</id>
      <username>YourUserToken</username>
      <password>YourUserTokenPassword</password>
    </server>
  </servers>
</settings>

...

For DSpace 7.x, you must use Java 11.

For DSpace 8.x, you must use Java 17.


Use Maven 3 or above

For more information see the Prerequisites section of the Sonatype Maven Repository Usage Guide

For DSpace 7.x or 8.x, you must use Maven 3.5.4 or above.  It's necessary to regenerate the LICENSES_THIRD_PARTY file (see notes below)

...

  • If any dependencies are listed with an "UNKNOWN" license, then that means that dependency failed to specify its OS License in their own Maven POM file. We will need to manually lookup the license for that project, and manually add it to our src/main/license/LICENSES_THIRD_PARTY.properties file which corrects all "UNKNOWN" licenses. Finally, rerun the command above to regenerate the new LICENSES_THIRD_PARTY based on this update.
  • If any dependencies are listed under an INCOMPATIBLE License (GPL, AGPL, etc), then we need to take a closer look at that dependency.  It is possible that the dependency is dual-licensed and therefore may be listed multiple times in the generated LICENSES_THIRD_PARTY file. If so, that's fine. If not, we may need to remove that dependency prior to the release.
  • If any Open Source Licenses are listed under multiple names (e.g. "BSD" vs. "BSD License" vs. "BSD licence"), then we may need to update our POM configurations for the codehaus license-maven-plugin to tell it to merge licenses of those names into one. Those configurations are in the Parent POM under the <licenseMerges> tag of this plugin: https://github.com/DSpace/DSpace/blob/mastermain/pom.xml#L406xml#L713

If the file was updated, commit it.

...

  • Release Notes- Should contain a very basic overview of the Release. Make sure the Release number is updated here!
    • NOTE: For minor releases (bug-fix-only releases), you may want to leave all information about the previous major release, and just enhance the content to state that this was a bug-fix release, and list any new contributors, etc.
  • Installation - Obviously make sure the Installation Documentation is updated for this Release
  • Upgrading a DSpace Installation - Same for the Upgrade Documentation, make sure it's up to date

  • History- Make sure the online History for this latest Release is included. This section just links to all the tickets/PRs closed under the release "milestone" in GitHub.

    Note

    Obviously, this is just a brief reminder of important areas of Documentation which always require updates. There's surely other areas, like Configuration section, which will require some updates for your release.


Ensure you

...

specify the "latest" release in GitHub

If you are performing multiple releases at once (e.g. backporting security or bug fixes), it is IMPORTANT to tag your releases chronologically.  For example, the backported fixes to 3.x should be tagged BEFORE 4.x which should be tagged BEFORE 5.x. The reason for this is that the timestamp of the tag determines the ORDERING of the releases in GitHub.  So, in order for the 5.x release to appear after the backported releases, it needs to be released LAST.  then you need to tell GitHub which one to label as the "latest" release.

This can be done within the GitHub Release Notes by either checking or unchecking the "Set as the latest release" option.  For more details see the GitHub docs on managing releasesThe last tagged release will become the "Latest Release" in GitHub.

Warning: optional profiles need to be specified at compile time

...

Code Block
mvn {target} -Drelease

# NOTE: for DSpace 7.x, and later, you MUST use the "-Drelease" flag in all commands.  It will automatically release all modules.

...

You will have to enter in your GPG passphrase (which you established when you created your Code Signing Key).

Note

If GPG is not working, you can "prime" the GPG agent by signing something like this:


echo "test" | gpg --clearsign


Info
If you need to re-run the Dry Run
If you need to re-run the Dry Run

If you notice an issue or an error occurs, you can re-run the Dry Run using the following command:

  • mvn release:prepare -DdryRun=true -Dresume=false -Drelease

You can also clean up any of the release files that the Dry Run created, and just re-run it.

  • mvn release:clean -Drelease
  • mvn release:prepare -DdryRun=true -Drelease

...

  1. Before running the "yarn version" command, you will need to tell your local "yarn" to NOT create a git tag.  We'll tag this release ourselves:

    Code Block
    # This only needs to be done once. You can check your settings via "yarn config list"
yarn config set version-git-tag false


  2. First, increment the release in our package.json.  Node.js / NPM / Yarn requires that release tags all be valid semantic versioning (https://semver.org/).

    1. So, our "dspace-angular" release numbering looks slightly different than the backend release numbering. It's MAJOR.MINOR.PATCH

      1. Major releases: 8.0.0 (would be compatible with v8.0 of the backend)
      2. Minor releases: 7.4.0 (would be compatible with v7.4 of the backend)
      3. Patch releases: 7.4.1 (would be compatible with v7.4 of the backend, but with very minor patches/fixes to the frontend codebase)

    2. Increment the version by running (NOTE: This will immediately apply a git commit to update the "version" in package.json).  In the below example, the current version is "7.4.0-next", and we've updated it to be "7.4.0" in preparation for the "dspace-7.4" tagged release.

      Code Block
      git checkout dspace-7_x (or main)
yarn version
...
info Current version: 7.4.6.1-next
question New version: 7.6.1
...
(EXAMPLE for 8.0)
info Current version: 8.0.0-next
question New version: 78.40.0


    3. Commit the change to package.json 

      Code Block
      git commit -a -m "Update version tag for release"
git push upstream maindspace-7_x (or main)


  3. Create a Create a new Release & Tag in GitHub.  See https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository for full instructions
    • Note: Alternatively, you can choose to tag the release from command-line (via git tag), but GitHub allows you to create a new tag when creating a new release.
    • Just create a new tag (e.g. "dspace-7.4") off the current "main" branch.
  4. Make sure the GitHub Release description links to the Release Notes  It should also link to the Backend's GitHub Release (and visa versa).  Look at past 7.x releases for examples.
  5. After the release, update our package.json with the next planned version to represent that the "main" branch is now for developing the next release.  NOTE: for Node.js / Angular, the "-next" suffix is the same as the "-SNAPSHOT" suffix used for Maven on the backend.
    1. If the next release is planned to be a major release, set the version to "[major].0.0-next"  (e.g. "8.0.0-next")
    2. If the next release is planned to be a minor release, set the version to "7.[minor].0-next" (e.g. "7.5.0-next")

    3. You'll need to run the "version" command a second time to update package.json for our next release.  In the below example, the current version is "7.4.0" and we've updated the version to be "7.5.0-next" for the next release.

      Code Block
      yarn version
...
info Current version: 7.4.6.1 
question New version: 7.6.2-next
...
(EXAMPLE for 8.0)
info Current version: 8.0.0
question New version: 78.51.0-next


    4. Commit the change to package.json 

      Code Block
      git commit -a -m "Update version tag for development of next release"
git push upstream dspace-7_x (or main)


Create the PDF version of Wiki Documentation

...

  • Make sure all contributors to the release have been added to the Release Notes!
    • Find the contributors: 

      • For bugfix releases

        Code Block
        # This example is to find the list of contributors to 6.3 
# It lists contributors to 6.x branch since the 6.2 tag
git shortlog -ns dspace-6_x ^dspace-6.2


      • For major releases (or from main branch), you can use GitHub contributors pages with a date range.  
  • Coordinate Announcements with LYRASIS Staff:
    • You might post draft announcements to a service such as https://gist.github.com/ and send out a call to committers for review.  When finalized, DSpace releases should be announced on the dspace-community, dspace-devel and dspace-tech lists/groups.
    • Announcement on dspace.org website, twitter
    • (As necessary) Ensure that the Download page on dspace.org is updated.
      • Plus, ask dspace.org admins to upload latest documentation in PDF/HTML format
    • Announce on all DSpace mailing lists
    • Link announcement on Home of DSpace Wiki, change any version numbers listed on that page.
  • Update Wiki pages, particularly these pages which refer to the Current and Next Releases:
  • Also, update the Documentation Wiki area! Specifically:
    • All Documentation page -> Has current release info
    • Add a warning to the documentation of the newest unsupported release (e.g. the warning for DSpace 1.7) and link to our Support Policy.
      Spaces - Space directory - (i) next to the space - Space Admin - Themes - Configure Theme - Header 
    • Homepage for the current Documentation (e.g. DSDOC7x) -> Has links to download latest version of DSpace
    • (If possible) Update the database schema diagram
  • Updates to GitHub: 
    • Move any uncompleted PRs to the next DSpace version tag / project board
    • Close any release-specific project board (after moving any uncompleted PRs or issues elsewhere)
    • Close the release milestone (adding date of the release)
  • Additional steps for Minor releases
    • See "Merge Minor Releases back to main branch" section below
  • Additional steps for Major releases
    • See also "Create Maintenance Branches" section below

Merge Minor Releases back to main branch

After any minor release (e.g. 8.1 or 8.2), we need to merge the release tag back into the "main" branch for easier upgrades.  This allows ensures the "main" branch is aware of any activity (commits) specific to that minor release.  It also allows sites to more easily upgrade to the next major release via "git merge [next-major-release-tag]"  (e.g. if currently running code from dspace-8.1  tag, you should be able to run get merge dspace-9.0  to upgrade to the next major release)

Code Block
# Start from current main
git checkout main

# Merge in the new minor release tag
# e.g. git merge -s ours dspace-7.6.2
git merge -s ours [minor-tag]

# Push updates to main
# If in doubt, create a PR first! 
# The result should be a PR with all the commits of the minor branch but zero code changes
git push upstream main

The resulting changes should be that zero code changes are made, but all the commit hashes from the minor release will be copied to main .

For more information on the "-s ours" merge command, see:

Create Maintenance Branches (after major release)

...