How to release a new ontology version

We use the Driessen workflow.

Prior to the release

• About two weeks before release day, review open issues in the corresponding release milestone and check their status, if necessary, by commenting on the issue. From experience, this notice length is reasonable to check on the issue status, allow for implementation, or assess whether to postpone the issue to the next release milestone (the latter should be avoided if possible).

• About a week before release day, start a new discussion to ensure three members from the oeo-release-team have the capacity to complete the release on release day. This includes two team members performing the release and reviewing the merge from release branch to dev branch and another member reviewing the merge from release branch to master branch.

• About 2-3 days before release day, repeat the issue review to avoid unresolved issues on release day and reconcile in oeo-release-team discussion if the release should proceed as planned or postponed.

• On release day, start the release early to ensure sufficient time for reviews and follow the checklist for a 'Normal (scheduled) release' below.

• The scheduled releases are always in the first week of months March, May, July, October, December.

Normal (scheduled) release

1. Make sure that all issues and pull requests that should go into the issue are closed and merged. These issues are usually collected in a release milestone. Also have a look at stale and merged branches, to ensure a tidy repository. (Note that we want to keep the two specific branches feature/geo and feature/sector-and-sector-concepts because they contain conceptual work we don't want to lose. Reasoning)

2. Create a release branch from dev branch

   • run git pull on dev branch before branching off on your local computer, so that the latest changes are included in the release branch
   • run git checkout -b releases-v1.2.3 to create and switch to the release branch
   • run git push --set-upstream origin releases-v1.2.3 to push branch to GitHub

3. Update version information in

   • VERSION file (version number)
   • CITATION.cff (version number and release date)

4. Change heading of the unreleased section in CHANGELOG.md with version number and release date.

   • If any of the added/changed/removed sections is empty, remove that section.

5. As part of the review process:

   • check changelog, e.g. for typos, unnecessary spaces, if PR numbers are in order
   • in protege check manually, if you notice any odd occurences in class tree or object properties (asserted and inferred)
   • reason the ontology in Protégé
   • carefully check all oeo-modules check if there are "runaway" classes or object properties (see also step 4 of the review workflow)
   • validate that all the new labels an definitions have their respective language labels. i.e. @en for english. Regular expressions can be used to find all cases where this should be checked. Example: replace rdfs:label\s*"(.*)" with rdfs:label "($1)@en.

6. Create two pull requests:

   • from release branch to dev branch, named: "Release v1.2.3 to dev branch"
   • from release branch to master branch, named: "Release v1.2.3 to master branch"

7. Make sure that all automated tests are successful

8. Merge both pull requests at the same time. Do not delete release branch for documentation purposes.

9. Close the release milestone.

10. Open new release milestone.

11. Draft a new release: https://github.com/OpenEnergyPlatform/ontology/releases/new
    ④ Summarize key changes
    ⑤ Link to heading of current release in CHANGELOG.md
    

12. Check the box Set as the latest release

13. Press the green Publish release button

14. After the release - on the dev branch -, create new unreleased section in the CHANGELOG.md. This should be done with first contextual PR on dev and not a designated PR to just add unreleased section.

## [2.X.X] - 20XX-XX-XX

### Added
### Changed
### Removed

14. Add the build files to the release. Go to Actions and click on the OEO CI pipeline of this release tag (you need to wait for the pipelines to finish):

And download the "build files":

Now go to the Actions but instead to the "Post Release Scipts" and download the file "existing-terms-and-definitions" :

Now edit the release you just made and attach both files "existing-terms-and-definitions.zip" and "build-files.zip" to the release artifacts

15. Inform @adelmemariani and @jh-rli that a new OEO version is released and that the OEO viewer needs to be compiled

End of release process

Checklist template

This is a checklist for the release that can be used e.g. in the thread of the release oeo-release-team.

1. [ ] All issues closed and all pull requests merged that are part of the release milestone.
2. [ ] Branch `releases-v1.2.3` from `dev`.
3. [ ] Update version information and release date in VERSION file and CITATION.cff.
4. [ ] Change *unreleased* heading in CHANGELOG.md.
5. [ ] Create two pull requests.
6. [ ] Automated tests are successful.
7. [ ] PR reviews.
8. [ ] Merge both PRs.
9. [ ] Close release milestone.
10. [ ] Draft release.
11. [ ] *Set as the latest release*.
12. [ ] Press *Publish release* button.
13. [ ] Create new *unreleased* section in CHANGELOG.md.
14. [ ] Add build files to the release page.
15. [ ] Inform @adelmemariani and @jh-rli.

[Detailled release workflow](https://github.com/OpenEnergyPlatform/ontology/wiki/How-to-release-a-new-ontology-version)

Hotfix release

Same workflow as above, but branch from master branch instead of dev branch.