Page History

...

Checkout the Language Pack Module:
1. git clone git@github.com:DSpace/dspace-api-lang.git dspace-api-lang
2. cd dspace-api-lang
3. git checkout main
  NOTE: always release language packs from the main branch -- we do not use a maintenance branch for language packs.
Do a Dry Run: mvn release:prepare -DdryRun=true
Tag and Increment Version: mvn release:prepare -Dresume=false
- Make sure to assign a version number of the format: [major].[minor].[sequence-number] (e.g. 5.0.0, 5.0.1, etc for 5.0 releases of language packs)
- NOTE: The release process should suggest the correct version number by default
Deploy Artifacts to Staging in Sonatype: mvn release:perform
Verify and Release Staged Artifacts in Sonatype (see instructions at link)
(For v6.x or below) Go back and run steps #1-5 above for the other language packs modules (dspace-xmlui-lang)

Once both Language Packs have been released, you can immediately perform the DSpace release. You do not need to wait for them to appear in Maven Central, as our DSpace parent pom.xml will find them in Sonatype's Release Repository immediately.

...

In the main pom.xml, provide the proper version range for each language pack. In the below example, we are saying to use any language pack version which is at least version 37.0.0, but is less than version 48.0.0:

Code Block

<!-- DSpace Localization Packages -->
<dependency>
   <groupId>org.dspace</groupId>
   <artifactId>dspace-api-lang</artifactId>
   <version>[37.0.0,4.0.0)</version>
</dependency>
<dependency>
   <groupId>org.dspace</groupId>
   <artifactId>dspace-xmlui-lang</artifactId>
   <version>[3.0.0,48.0.0)</version>
   <type>war</type>
</dependency>

Ensure Documentation is Updated Appropriately

...

Just including a little warning about this up front. The following optional modules need to be specified with every mvn command below. We will make an effort to keep this list up to date, but you should verify it before you cut a new release. Things change. Forgetting an optional module means you'll have to cut another release.

Code Block

mvn {target} {-D[version-specific-option]}-Drelease

# NOTE: for DSpace 7.x, you MUST use the "-Drelease" flag in all commands.  It will automatically release all modules.
# NOTE: for DSpace 6.x, make sure the "-Dmirage2.on=true" flag is specified to ensure Mirage2 is released
# NOTE: for DSpace 5.x, make sure the "-Dmirage2.on=true" flag is specified to ensure Mirage2 is released 
#       AND the LNI module must be manually specified (-Pdspace-lni)
#       AND "-Dhttps.protocols=TLSv1.2" (needed for Maven + Java 7)

Checkout Main or Branch to Release

Checkout a fresh copy of the to-be-released version either from a branch or main. For example:

Code Block
git clone git@github.com:DSpace/DSpace.git dspace-release cd dspace-release git checkout main

Note: do not just re-use an old working copy of the DSpace Main branch, for obvious reasons, you don't want your own work in progress sneaking into the release. It's also important to use the SSH repository path as noted above (NOT the https URL), otherwise you will be prompted for your GitHub credentials during the release process. More than once. Save yourself some time, be sure to use the SSH path.

Note: if you are doing a maintenance release, you will need to check out the maintenance branch, and not the main branch. In this case, the example above would instead readCheckout a fresh copy of the to-be-released version either from a branch or main. For example:

Code Block
git clone git@github.com:DSpace/DSpace.git dspace-release cd dspace-release git checkout main

Note: do not just re-use an old working copy of the DSpace Main branch, for obvious reasons, you don't want your own work in progress sneaking into the release. It's also important to use the SSH repository path as noted above (NOT the https URL), otherwise you will be prompted for your GitHub credentials during the release process. More than once. Save yourself some time, be sure to use the SSH path.

Note: if you are doing a maintenance release, you will need to check out the maintenance branch, and not the main branch. In this case, the example above would instead read:

Code Block
git clone git@github.com:DSpace/DSpace.git dspace-release cd dspace-release git checkout dspace-7_x (or whatever the current maintenance branch might be named)

Update your Local Maven Cache (optional - not necessary)

Before starting the release, you may wish to ensure your local maven cache (~/.m2/repository) is completely up-to-date by running (from [dspace-src]):

Code Block

mvn install -Dmirage2.on=true
# NOTE: for DSpace 5.x, the LNI module must be manually specified (-Pdspace-lni)
# Additionally, if releasing using Java 7, then you must include "-Dhttps.protocols=TLSv1.2" to avoid protocol_version errors in Maven.

Updating your local maven cache will help to ensure that the release process goes more smoothly, and should help you to avoid any errors having to do with Maven being unable to locate any particular dependencies. That being said, this step actually may not be necessary, if our release process is working correctly.

Do a sanity check of the tests

You know, just to save yourself a bunch of embarrassment later, run the tests?

Code Block
mvn test -Dmaven.test.skip=false -DskipITs=false

You can also choose to simply verify the tests succeed in our automated CI processes after the latest commit.

Do a Dry Run

This step is not required, but performs a useful sanity check without committing any changes. From your clean, up-to-date copy of master/branch, run the following command (from [dspace-src]):

Code Block

# For DSpace 6.x or below
mvn release:prepare -DdryRun=true -Dmirage2.on=true
# NOTE: for DSpace 5.x, the LNI module must be manually specified (-Pdspace-lni) to ensure it is also released.
# Additionally, if releasing using Java 7, then you must include "-Dhttps.protocols=TLSv1.2" to avoid protocol_version errors in Maven.

# For DSpace 7.x or above (the "-Drelease" flag is required and it selects all modules to release)
mvn release:prepare -DdryRun=true -Drelease

dspace-7_x
 
(or whatever the current maintenance branch might be named)

Do a Dry Run

This step is not required, but performs a useful sanity check without committing any changes. From your clean, up-to-date copy of master/branch, run the following command (from [dspace-src]):

Code Block
# For DSpace 7.x or above (the "-Drelease" flag is required and it selects all modules to release) mvn release:prepare -DdryRun=true -Drelease

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

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

Tag and Increment Version

This step will set the version declared in the project's pom.xml files, commit the changes to master/branch, tag the release, and finally, check in the master/branch change that increments the next development version (e.g. x.y-SNAPSHOT) in the pom.xml files. Run the following (from [dspace-src]):

Code Block
# For DSpace 7.x or above (the "-Drelease" flag is required and it selects all modules to release) mvn release:prepare -Dresume=false -Drelease

(Optionally, you may also include the parameters -Dusername=YourGitHubUsername -Dpassword=YourGitHubPassword at the end of the above command, though I've not found these to be necessary)

The above command will ask you three basic questions. Here are sample answers for DSpace 3.0:

Panel

"What is the release version for: XXX" : 3.0

NOTE: This is the release # to put in the final tagged Maven POMs.
Examples:
- For a "3.0" final release, it should look like: 3.0
- For a "3.0 Release Candidate #1" release, it should look like: 3.0-rc1

"What is SCM release tag or label for: XXXX" : dspace-3.0

NOTE: This is the tag name in GitHub .
Examples:
- For a "3.0" final release, it should look like: dspace-3.0
- For a "3.0 Release Candidate #1" release, it should look like: dspace-3.0-rc1

"What is the new development version for: XXXX" : 3.1-SNAPSHOT

NOTE: This is the next release number which all POMs should be incremented to on "master" branch.
Examples:
- For a "3.0" final release (3.0), the next version should be: 3.1-SNAPSHOT
- For a "3.0 Release Candidate #1" release (3.0-rc1), the next version should be: 3.0-rc2-SNAPSHOT

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

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 (add required extra flags)

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 (add required extra flags)

Tag and Increment Version

This step will set the version declared in the project's pom.xml files, commit the changes to master/branch, tag the release, and finally, check in the master/branch change that increments the next development version (e.g. x.y-SNAPSHOT) in the pom.xml files. Run the following (from [dspace-src]):

Code Block

# For DSpace 6.x or below
mvn release:prepare -Dresume=false -Dmirage2.on=true
# NOTE: for DSpace 5.x, the LNI module must be manually specified (-Pdspace-lni) to ensure it is also released
# Additionally, if releasing using Java 7, then you must include "-Dhttps.protocols=TLSv1.2" to avoid protocol_version errors in Maven.

# For DSpace 7.x or above (the "-Drelease" flag is required and it selects all modules to release)
mvn release:prepare -Dresume=false -Drelease

(Optionally, you may also include the parameters -Dusername=YourGitHubUsername -Dpassword=YourGitHubPassword at the end of the above command, though I've not found these to be necessary)

The above command will ask you three basic questions. Here are sample answers for DSpace 3.0:

Panel

"What is the release version for: XXX" : 3.0

NOTE: This is the release # to put in the final tagged Maven POMs.
Examples:
- For a "3.0" final release, it should look like: 3.0
- For a "3.0 Release Candidate #1" release, it should look like: 3.0-rc1

"What is SCM release tag or label for: XXXX" : dspace-3.0

NOTE: This is the tag name in GitHub .
Examples:
- For a "3.0" final release, it should look like: dspace-3.0
- For a "3.0 Release Candidate #1" release, it should look like: dspace-3.0-rc1

"What is the new development version for: XXXX" : 3.1-SNAPSHOT

NOTE: This is the next release number which all POMs should be incremented to on "master" branch.
Examples:
- For a "3.0" final release (3.0), the next version should be: 3.1-SNAPSHOT
- For a "3.0 Release Candidate #1" release (3.0-rc1), the next version should be: 3.0-rc2-SNAPSHOT

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

Info

title	Many JavaDoc WARNING messages will scroll by

As the release process scrolls by, you likely will see a LOT of "WARNING" messages. Don't worry, these should be just Javadocs warnings, and can be safely ignored. Just be patient, and see if it all succeeds in the end. We know it's nerve-wracking, but it will all be OK.

What do successful tagging results look like?

Assuming everything worked right, you should see ALL the following changes in GitHub:

title	Many JavaDoc WARNING messages will scroll by

As the release process scrolls by, you likely will see a LOT of "WARNING" messages. Don't worry, these should be just Javadocs warnings, and can be safely ignored. Just be patient, and see if it all succeeds in the end. We know it's nerve-wracking, but it will all be OK.

What do successful tagging results look like?

Assuming everything worked right, you should see ALL the following changes in GitHub:

A newly tagged version of DSpace under: https://github.com/DSpace/DSpace/tags
1. For example, if you are releasing "3.2" you should see a newly listed tag "dspace-3.2" in the list of tags above.
The primary "pom.xml" file in that newly tagged version should have a <version> tag that correspond to the newly released version.
1. For example, if you are releasing "3.2", then the "dspace-3.2" tag's main "pom.xml" should have a <version>3.2</version> tag
The primary "pom.xml" file in the original branch ("master" or a ".x" branch) should now be updated to the next SNAPSHOT version
1. For example, if you are releasing "3.2", then the original "dspace-3.x" branch's pom.xml file should now have a <version>3.3-SNAPSHOT</version> tag

The results from Maven look similar to this. (Don't worry about the "SKIPPED" messages, those are normal, as the actual release process just runs from the "DSpace Parent Project")

Code Block

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] DSpace Parent Project ............................. SUCCESS [2.320s]
[INFO] DSpace Services Framework :: API and Implementation  SKIPPED
[INFO] DSpace Kernel :: API and Implementation ........... SKIPPED
[INFO] DSpace Addon Modules .............................. SKIPPED
[INFO] DSpace Kernel :: Additions and Local Customizations  SKIPPED
[INFO] DSpace XML-UI (Manakin) ........................... SKIPPED
[INFO] DSpace XML-UI (Manakin) :: Local Customizations ... SKIPPED
[INFO] DSpace LNI ..

A newly tagged version of DSpace under: https://github.com/DSpace/DSpace/tags
1. For example, if you are releasing "3.2" you should see a newly listed tag "dspace-3.2" in the list of tags above.
The primary "pom.xml" file in that newly tagged version should have a <version> tag that correspond to the newly released version.
1. For example, if you are releasing "3.2", then the "dspace-3.2" tag's main "pom.xml" should have a <version>3.2</version> tag
The primary "pom.xml" file in the original branch ("master" or a ".x" branch) should now be updated to the next SNAPSHOT version
1. For example, if you are releasing "3.2", then the original "dspace-3.x" branch's pom.xml file should now have a <version>3.3-SNAPSHOT</version> tag

The results from Maven look similar to this. (Don't worry about the "SKIPPED" messages, those are normal, as the actual release process just runs from the "DSpace Parent Project")

Code Block

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] DSpace Parent Project ............................. SUCCESS [2.320s]
[INFO] DSpace Services Framework :: API and Implementation ......... SKIPPED
[INFO] DSpace KernelLNI :: APILocal and Implementation Customizations ................ SKIPPED
[INFO] DSpace Addon Modules JSP-UI ..................................... SKIPPED
[INFO] DSpace KernelJSP-UI :: Additions and Local Customizations ............. SKIPPED
[INFO] DSpace XML-UI (Manakin) SWORD ...................................... SKIPPED
[INFO] DSpace XML-UI (Manakin) SWORD :: Local Customizations ........ SKIPPED
[...... SKIPPED
[INFO] DSpace LNI ...SWORD v2 ..................................... SKIPPED
[INFO] DSpace SWORD LNIv2 :: Local Customizations ................ SKIPPED
[INFO] DSpace JSP-UI ..................................... SKIPPED
[INFO] DSpace JSP-UI SOLR :: Local Customizations ............... SKIPPED
[INFO] DSpace SWORDOAI 2.0 ..................................... SKIPPED
[INFO] DSpace OAI SWORD2.0 :: Local Customizations .............. SKIPPED
[INFO] DSpace Assembly SWORDand v2Configuration ................................... SKIPPED SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] DSpace SWORD v2 :: Local Customizations ........... SKIPPED
[INFO] DSpace SOLR :: Local Customizations ............... SKIPPED
[INFO] DSpace OAI 2.0 .................................... SKIPPED
[INFO] DSpace OAI 2.0 :: Local Customizations ............ SKIPPED
[INFO] DSpace Assembly and Configuration ................. SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] -----------------------------------------BUILD SUCCESS
[INFO] ---------------------------------------

What to do if you get tagging Errors?

Note

title	If you receive a project dependency error

The mvn release:prepare command may fail to compile part way through the process, complaining that an internal project dependency is not met. If this occurs, don't worry. You just may need to ensure those dependencies get installed to your local cache. To fix this, you should be able to run the following:

mvn release:clean (clean out any files created by the previous "mvn release:prepare")
mvn install -Dmirage2.on=true
mvn release:prepare -Dmirage2.on=true

Note

title	Backing out of changes

If backing out of this step is needed for any reason, the following will restore the github repository and your working copy to the state it was previously in:

mvn release:rollback
- Warning: running a "mvn release:rollback" will perform an immediate, automatic push to GitHub master, rolling back any previously committed POM version changes.
- If you want to avoid the immediate, automatic push to GitHub master, you may be able to use "mvn release:clean" to just clean up the locally made release preparations.
- If the rollback fails for any reason, you can also run the following to simply revert all POMs back to a specific version:
  - mvn versions:set -DnewVersion=[version-to-revert-to] -DgenerateBackupPoms=false -Dmirage2.on=true
  - This will revert POMs to the specified version in your local copy. You'll then need to commit the changes and push them up to GitHub
Now delete the tag in GitHub (local & remote)
- git tag -d dspace-x.y
- git push origin :refs/tags/dspace-x.y

Deploy Artifacts to Staging in Sonatype

This step will sign, checksum, and push all release artifacts (including javadocs and sources) to the Sonatype staging repository (http://oss.sonatype.org/). Run the following (from [dspace-src]):

---------------------------------

What to do if you get tagging Errors?

Note

title	If you receive a project dependency error

The mvn release:prepare command may fail to compile part way through the process, complaining that an internal project dependency is not met. If this occurs, don't worry. You just may need to ensure those dependencies get installed to your local cache. To fix this, you should be able to run the following:

mvn release:clean (clean out any files created by the previous "mvn release:prepare")
mvn release:prepare -Drelease

Note

title	Backing out of changes

If backing out of this step is needed for any reason, the following will restore the github repository and your working copy to the state it was previously in:

mvn release:rollback
- Warning: running a "mvn release:rollback" will perform an immediate, automatic push to GitHub master, rolling back any previously committed POM version changes.
- If you want to avoid the immediate, automatic push to GitHub master, you may be able to use "mvn release:clean" to just clean up the locally made release preparations.
- If the rollback fails for any reason, you can also run the following to simply revert all POMs back to a specific version:
  - mvn versions:set -DnewVersion=[version-to-revert-to] -DgenerateBackupPoms=false -Drelease
  - This will revert POMs to the specified version in your local copy. You'll then need to commit the changes and push them up to GitHub
Now delete the tag in GitHub (local & remote)
- git tag -d dspace-x.y
- git push origin :refs/tags/dspace-x.y

Deploy Artifacts to Staging in Sonatype

This step will sign, checksum, and push all release artifacts (including javadocs and sources) to the Sonatype staging repository (http://oss.sonatype.org/). Run the following (from [dspace-src]):

Code Block

# For DSpace 6.x or below
mvn release:perform -Dmirage2.on=true
# NOTE: for DSpace 5.x, the LNI module must be manually specified (-Pdspace-lni) to ensure it is also released
# Additionally, if releasing using Java 7, then you must include "-Dhttps.protocols=TLSv1.2" to avoid protocol_version errors in Maven.

# For DSpace 7.x or above (the "-Drelease" flag is required and it selects all modules to release)
mvn release:perform -Drelease

...

Info

title	If you need to re-deploy

If any errors or problems occur during the deploy, you can re-run the same mvn release:perform safely after fixing those issues (re-running it will just overwrite existing staged contents).

Warning

As of 2022, Sonatype REQUIRES usage of Java 8 (or above) to deploy artifacts into staging. Attempting to use Java 7 will result in "connection reset" errors. So, when releasing DSpace 5.x (or lower), you must switch to using Java 8 for this step.

Note

If you run into issues, or need to perform the mvn release:perform from a different machine, it is possible to run it simply against the created tag in GitHub.

Create a "dummy" [src]/release.properties file in your local DSpace source directory. It should simply state the basic SCM info for the tag you wish to release, e.g.

Code Block

# Location of DSpace's SCM. Keep this as-is.
scm.url=scm\:git\:git@github.com\:DSpace/DSpace.git
# Change this value to point at the tag in GitHub
# For example, this example tells "release:perform" to perform a release to Sonatype based on the 'dspace-6.0-rc1' tag.
scm.tag=dspace-6.0-rc1

Run the specified mvn release:perform command (see above). Maven will then proceed to checkout the specified tag into your [src]/target/checkout folder, package up the release and send it off to Sonatype.

...

Login to http://oss.sonatype.org/
Click "Staging Repositories" in the left column, then select the checkbox next to the staged repository on the right. The contents of it will open up at the bottom of the page.
1. The staged repository should begin in the "Closed" state, which means some automated verifications on the POM structure etc. have already been run. If it is not yet closed, select it and click the "Close" button.

Ensure that the artifacts in staging are exactly as they should be once deployed to Maven Central. Here's a few things to watch out for...

Download one (or more) of the POMs, and make sure the <version> tag is correct (e.g. 6.0 and not a SNAPSHOT version or similar)
Compare it against a past release in Maven Central (https://search.maven.org/search?q=org.dspace), making sure it has the same JARs or WARs, etc
Check if the file sizes looks reasonable (0 Bytes is probably not reasonable ;-)). You can also compare those to previous releases.

You can also verify the checksums of one or more of the JARs/WARs in Sonatype versus those that were installed into your .m2 directory. They should be the same.

Info

title	If You Need to Revert Back before Releasing

If anything is incorrect, select the staged repository and select "Drop". After the problem is resolved, you can re-deploy the artifacts to staging and verify them again. To re-deploy an already-tagged release:
mvn release:perform -Dmirage2.on=true Drelease -Dtag=dspace-x.y -DconnectionUrl=scm:git:git@github.com:DSpace/DSpace.git -Darguments="-Dgpg.keyname=YourKeyId -Dgpg.passphrase=YourKeyPassword"

If everything looks good, select the repository and select "Release". The artifacts should be synced to Maven central (https://search.maven.org/search?q=org.dspace) within 2 hours.

Warning

title	Once Released, There is No "Undo" Option

Once you select "Release", there is no way to "undo" the release. If any major issues are found, you'll have to increment the version number and perform a new bug-fix release.

Keep in mind however, that the release should become almost immediately available in the public Sonatype repository: https://oss.sonatype.org/content/repositories/releases/org/dspace/

...

Page tree

Versions Compared

Old Version 226

New Version 227

Key

Ensure Documentation is Updated Appropriately

Checkout Main or Branch to Release

Checkout Main or Branch to Release

Update your Local Maven Cache (optional - not necessary)

Do a sanity check of the tests

Do a Dry Run

Do a Dry Run

Tag and Increment Version

Tag and Increment Version

What do successful tagging results look like?

What do successful tagging results look like?

What to do if you get tagging Errors?

Deploy Artifacts to Staging in Sonatype

What to do if you get tagging Errors?

Deploy Artifacts to Staging in Sonatype