Skip to content

Releasing

The following process should be followed EXACTLY to release MauroDataMapper in its entirety. Please pay attention to versions and whats changed between each git commit.

Warning

The main release cycle should be performed using Jenkins, not done manually. However plugins & documentation do still need to be done manually

Warning

You will need git flow installed in the command line to be able to perform the release. Installation instructions are here. You will also need to make sure all your repositories are initialised as git-flow repositories. This can be done using git flow init, however you MUST make sure you have checked out the develop and main branches before you initialise.

Information

Unless patching a release which has failed ALL releases should be the next MINOR release. If there is significant and appropriate change then a MAJOR release should be used. A PATCH release should only be done if the MINOR release failed and this is a release being done to fix that release failure.

Information

A unified view of the current build status of develop and main branches can be see here

You should identify the following from the repositories before starting

  • RELEASE_VERSION : The quarterly release version. e.g. 2022.2
  • CORE_VERSION : The appropriate non-snapshot version from mdm-core/gradle.properties on the develop branch
  • UI_VERSION : The appropriate non-snapshot version from mdm-ui/package.json on the develop branch

Jenkins Release

Use the mdm-release/release job, filling in the requested parameters. Sit back and relax.

MDM plugins

Warning

You will need to wait for the main branch of mdm-core to finish before proceeding on the latest plugins

Information

This repository provides useful scripts and a unified live view of the state of each branch build.

Release Order

You will need to push some of the repositories in the correct order as they have dependencies on other plugins. The following plugins have a release order, if not listed then there is not required order.

  1. mdm-plugin-database
  2. mdm-plugin-testing-utils
    1. mdm-plugin-database-oracle
  3. mdm-plugin-database-mysql
  4. mdm-plugin-database-postgresql
  5. mdm-plugin-database-sqlserver
  6. mdm-plugin-profile-schema-org
  7. mdm-plugin-profile-hdruk

No changes waiting to be released

  • You don't need to release these every time we release mdm-core
  • However you should make sure all develop branches are updated to mdmCoreVersion=${CORE_VERSION} and then push the update.
  • Any jobs which fail will need to have the code updated.
  • If any of the code changes are in side the code base (not test changes) then you will need to release
  • If only test code changes are needed or no changes are needed then don't do a release as we have proved it's still compatible

Changes waiting to be released

  • You should make sure the develop branch is updated to mdmCoreVersion=${CORE_VERSION} and then push the update
  • Any tests which fail will need to have the code updated
  • If any of the code changes are in side the code base (not test changes) then you will need to release with an updated mdmCoreVersion
  • If only test code changes are needed or no changes are needed then release using the last mdmCoreVersion used as its still compatible
1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start ${PLUGIN_VERSION}
  • Update gradle.properties
  • Update README.md "How to apply"
1
2
git commit -am "Release ${PLUGIN_VERSION}"
git flow release finish -m "${PLUGIN_VERSION}" ${PLUGIN_VERSION}
  • Update gradle.properties to next minor snapshot
  • DO NOT change the README.md file
1
2
git commit -am 'Next snapshot'
git checkout main && git push && git checkout develop && git push && git push --tags

Document & Announce

Information

To be able to autogenerate the release documentation for plugins you will need to clone https://github.com/MauroDataMapper-Plugins/mdm-plugins. Then place all the plugins into this directory.

Warning

Remember to remove the following from the autogenerated plugins release output

  • Private Repositories
  • Unreleased plugins

Github

Each of the repositories requires the tag to be released and links to the issues fixed supplied.

  • Navigate to the supplied tags page
  • Select the latest tag and choose "Create release"
  • Copy in the appropriate text from the below list, making sure to update
    • the stated YouTrack version to the tag being released
    • the stated Github milestone
  • Click the "Auto-generate release notes" button
mdm-core
Tags Page 
1
See [Issues fixed](https://metadatacatalogue.myjetbrains.com/youtrack/issues/MC?q=%23Released%20%23B4.8.0) and [Milestones](https://github.com/MauroDataMapper/mdm-core/issues?q=is%3Aissue+milestone%3A4.8.0)
mdm-ui
Tags Page 
1
See [Issues fixed](https://metadatacatalogue.myjetbrains.com/youtrack/issues/MC?q=%23Released%20%23F6.4.0) and [MileStones](https://github.com/MauroDataMapper/mdm-ui/issues?q=is%3Aissue+milestone%3A6.4.0)
mdm-application
Tags Page 
1
See [Issues fixed](https://metadatacatalogue.myjetbrains.com/youtrack/issues/MC?q=%23Released%20%23B4.8.0), [Core Milestones](https://github.com/MauroDataMapper/mdm-core/issues?q=is%3Aissue+milestone%3A4.8.0) and [Application Milestones](https://github.com/MauroDataMapper/mdm-application-build/issues?q=is%3Aissue+milestone%3A4.8.0)
mdm-docker
Tags Page 
1
2
3
4
See [Issues fixed](https://metadatacatalogue.myjetbrains.com/youtrack/issues/MC?q=%23Released%20%23B4.8.0%20%23F6.4.0)
and [Core Milestones](https://github.com/MauroDataMapper/mdm-core/issues?q=is%3Aissue+milestone%3A4.8.0)
and [Application Milestones](https://github.com/MauroDataMapper/mdm-application-build/issues?q=is%3Aissue+milestone%3A4.8.0)
and [UI Milestones](https://github.com/MauroDataMapper/mdm-ui/issues?q=is%3Aissue+milestone%3A6.4.0)

Documentation

Caution

Make sure you've done all the github releases first otherwise the release notes won't contain anything useful

This should be performed inside the docs repository.

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start "${RELEASE_VERSION}"

1
2
3
git commit -am "Release ${RELEASE_VERSION}"
git flow release finish -m "${RELEASE_VERSION}" "${RELEASE_VERSION}"
git checkout main && git push && git checkout develop && git push && git push --tags

Main Release

Update docs/about/release-notes.md file.

The td sections, in order, are: Add 1. Release version & link to the release in Github 2. Release date 3. Major Changes: This is an ul so each change should be wrapped in an li element

  • Update the "Current Full Release" line:
1
The current full release is **${RELEASE_VERSION}** (a.k.a B${CORE_VERSION}_F${UI_VERSION}).
  • Add the following block with updated versions to the top of the ## Core API section:
1
2
3
4
5
6
7
8
9
<tr>
    <td><b>4.10.0</b><br/><a href="https://github.com/MauroDataMapper/mdm-core/releases/tag/4.10.0">(GitHub Link)</a></td>
    <td>2nd September 2021</td>
    <td>
        <ul>
            <li></li>
        </ul>
    </td>
</tr>
  • Add the following block with updated versions to the top of the ## UI section:
1
2
3
4
5
6
7
8
9
<tr>
    <td><b>6.6.0</b><br/><a href="https://github.com/MauroDataMapper/mdm-ui/releases/tag/6.6.0">(GitHub Link)</a></td>
    <td>2nd September 2021</td>
    <td>
        <ul>
            <li></li>
        </ul>
    </td>
</tr>

Plugins Release

  • Run ./releases.sh in mdm-plugins.
  • Remove the private repositories from the HTML format and copy into the docs/installing/plugins.md file

Zulip Announce

Caution

Make sure you've done all the github releases first otherwise the release notes won't contain anything useful

  • Run ./releases.sh in mdm-plugins.
  • Copy the below markdown block into the announce stream of Zulip
  • Update the versions for the applications
  • Update the tag version for the release notes
  • Copy in the plain text format of the "releases" output underneath it
1
2
3
4
5
6
7
# New Release

| Application | Version | Release Notes |
|----|-----|-----|
| Docker | `2022.2` | https://github.com/MauroDataMapper/mdm-docker/releases/tag/2022.2 |
| RESTful API | `4.9.0` | https://github.com/MauroDataMapper/mdm-application-build/releases/tag/4.9.0 |
| UI | `6.5.0` | https://github.com/MauroDataMapper/mdm-ui/releases/tag/6.5.0 |

Manual Release Process

In the event Jenkins is unavailable follow the process below to release the systems Jenkins would release

mdm-core

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start ${CORE_VERSION}

Update gradle.properties

1
2
git commit -am "Release ${CORE_VERSION}"
git flow release finish -m "${CORE_VERSION}" ${CORE_VERSION}

Update gradle.properties to next minor snapshot

1
2
git commit -am 'Next snapshot'
git checkout main && git push && git checkout develop && git push && git push --tags

mdm-resources

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start ${CORE_VERSION}

Update package.json version to CORE_VERSION

1
2
3
npm install && npm run build
git commit -am "Release ${CORE_VERSION}"
git flow release finish -m "${CORE_VERSION}" ${CORE_VERSION}

Update package.json version to next snapshot CORE_VERSION

1
2
3
npm install && npm run build
git commit -am 'Next snapshot'
git checkout main && git push && git checkout develop && git push && git push --tags

mdm-ui

Warning

You must release mdm-resources first, or be able to use an existing release of mdm-resources

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start ${UI_VERSION}

Update package.json

  • version to UI_VERSION
  • "@maurodatamapper/mdm-resources" to CORE_VERSION
1
npm install

Caution

MAKE SURE in package.lock that all the lines for mdm-resources that have a commit hash MATCH the hash for the release, if NOT then delete all entries in the lock file for mdm-resources with a commit hash and run npm install again

1
2
git commit -am "Release ${UI_VERSION}"
git flow release finish -m "${UI_VERSION}" ${UI_VERSION}

Update package.json

  • version to next minor snapshot UI_VERSION
1
2
3
npm install
git commit -am 'Next snapshot'
git checkout main && git push && git checkout develop && git push && git push --tags

mdm-application-build

Warning

You will need to wait for the main branch of mdm-core to finish before proceeding on the latest mdm-application-build

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start ${CORE_VERSION}

Update gradle.properties

1
2
git commit -am "Release ${CORE_VERSION}"
git flow release finish -m "${CORE_VERSION}" ${CORE_VERSION}

Update gradle.properties to next minor snapshot

1
2
git commit -am 'Next snapshot'
git checkout main && git push && git checkout develop && git push && git push --tags

mdm-docker

Warning

You will need to wait for the main branch of mdm-application-build and mdm-ui to finish before proceeding

1
2
git checkout main && git pull && git checkout develop && git pull
git flow release start "${RELEASE_VERSION}"

Update docker-compose.yml

  • The 2 commit ARGS
  • The image tag to B${CORE_VERSION}_F${UI_VERSION}

Dry run and check it comes up as expected

1
2
docker-compose build
docker-compose up

If it all comes up.

1
2
3
4
5
git commit -am "Release ${RELEASE_VERSION}"
git flow release finish -m "${RELEASE_VERSION}" "${RELEASE_VERSION}"
git checkout main 
git tag "B${CORE_VERSION}_F${UI_VERSION}"
git push && git checkout develop && git push && git push --tags