Page History
...
- Checkout the Language Pack Module:
git clone git
@github.
com:DSpace/dspace-api-lang.git dspace-api-lang
cd dspace-api-lang
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
- Make sure to assign a version number of the format:
- 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 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 notice an issue or an error occurs, you can re-run the Dry Run using the following command:
You can also clean up any of the release files that the Dry Run created, and just re-run it.
|
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 |
---|
|
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:
You can also clean up any of the release files that the Dry Run created, and just re-run it.
|
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 |
---|
|
You will also have to enter in your GPG passphrase (which you established when you created your Code Signing Key).
Info | ||
---|---|---|
| ||
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:
| ||
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
- 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.
- 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
- 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
- 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.
- 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
- 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 | ||
---|---|---|
| ||
The
|
Note | ||
---|---|---|
| ||
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:
|
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 | ||
---|---|---|
| ||
The
|
Note | ||
---|---|---|
| ||
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:
|
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 |
---|
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 | ||
---|---|---|
| ||
If any errors or problems occur during the deploy, you can re-run the same | ||
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
|
...
- 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.
- 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/
...