How to release

To create a new MapStore release, you need to:

• Create an issue of type Mapstore Release on GitHub by clicking here with the title of the release.
• Follow the checklist in the issue created.

Here below some details about changelog generation and naming conventions.

Naming conventions

release and tag

• vYYYY.XX.mm name of the release and tag. (e.g. v2022.01.01)
• YYYY is the year,
• XX is the incremental number of the release for the current year (starting from 01)
• mm is an incremental value (starting from 00) to increment for minor releases

stable branch

• YYYY.XX.xx name of stable branch (e.g. 2022.01.xx )
• YYYY is the year
• XX is the incremental number of the release for the current year (starting from 01)
• xx is the fixed text xx

Release procedure details

Github actions

The github actions are configured to automate the release process.

In particular the process is composed by 4 steps:

• Cut Release Branch creates a new branch from master with the name of the stable branch
• Prepare Release updates the version of the packages and creates the changelog
• Create Release creates the github draft release
• Post Release restores the snapshots

In this process the user has to manually finalize the release by adding the release description and the binaries to the release. Everything is listed in the checklist of the issue created at the beginning.

Here a flow chart that describes the process:

flowchart TD
    Issue[Create MapStore Release Issue] --> X[...]
    X --> Cut
    Cut[[GH Action: Cut Release Branch]] -->|
    create branch
    PR to master with packages versions update
    | Update[[GH Action: Update dependencies versions]] -->|
        fix package versions for geostore, http-proxy, print lib
        excluding snapshots
    | Fixes
    Fixes[Fixes...] --> Tests[Tests...]
    Tests --> start(((start release)))
    start --> PrepareRelease
    PrepareRelease[[GH Action: Prepare Release]] --> |
    Fix versions
    Changelog
    Tag
    PR to master with changelog updates
    | CreateRelease
    CreateRelease[[GH Action: Create Release]] --> |
        Create github Release
        generate binaries to attach to the release
    |release
    release((release
    created)) -->PostRelease[[Post Release]]
    PostRelease[[GH Action: Post Release]]  --> |
        restores snapshots
    | finish(((end)))
    release --> FinalizeRelease[Finalize release manually]
    FinalizeRelease -->|
        refine release description with features
        docker
        jenkins
        communication...
    | Publish
    finish -- next minor release --> Fixes

Git graph structure

The procedure produces the following git graph structure:

gitGraph TB:
    commit
    branch 2023.01.xx
    checkout 2023.01.xx
    commit id: "2023.01 initial commit"
    checkout main
    commit id: "feature-1"
    commit id: "fix-1"
    checkout 2023.01.xx
    cherry-pick id:"fix-1"
    commit id: "fix-versions-1+changelog"
    commit id: "2023.01.00-release" tag: "v2023.02.00"
    commit id: "restore-snaphots-1"
    checkout main
    commit id: "Changelog for version v2023.01.00"
    commit id: "fix-2"
    commit id: "feature-2"
    commit id: "feature-3"
    checkout 2023.01.xx
    cherry-pick id:"fix-2"
    commit id: "fix-versions-2+changelog"
    commit id: "2023.01.01-release" tag: "v2023.02.01"
    commit id: "restore-snaphots-2"
    checkout main
    commit id: "Changelog for version v2023.02.01"
    commit
    commit
    branch 2023.02.xx
    checkout 2023.02.xx
    commit id: "2023.02 initial commit"
    checkout main
    commit id: "fix-3"
    checkout 2023.02.xx
    cherry-pick id:"fix-3"

Changelog generation

The changelog generation is now automated. Anyway it is possible to generate the changelog manually by running the following command:

npm run generate:changelog <oldReleaseNumber>  <newReleaseNumber>

# usage
# e.g. npm run generate:changelog 2022.01.00 2022.02.00

This produces some text that can be used to update the changelog file.

Handling errors

If in a certain point we notice some errors, the separation of the tasks allows to restart the process from the point where the error occurred.

For instance if after tag creation we notice some problem or we have some failures, we can fix the problem, delete and recreate the tag manually and recreate the release by running the Create Release action.

Testing and fixing release procedure

For testing and fixing the release procedure it is possible to run the release procedure on your fork. anyway "Create, Prepare and Post Release" actions are configured to run only on the main repository. This is done to avoid that the release procedure is triggered automatically by forks in some cases. So on your fork you will need to manually edit the workflow files to enable the actions to run on your fork.

In particular you will need to edit some lines like this:

if:  ${{ github.event_name == 'push' && github.repository == 'geosolutions-it/MapStore2' }}

Removing the condition or changing the repository name.