From af82f439566d8d8c622c86e96ec52cc180e5d400 Mon Sep 17 00:00:00 2001
From: Christophe Loiseau <christophe.loiseau@sovity.de>
Date: Wed, 18 Sep 2024 19:01:11 +0200
Subject: [PATCH] update

---
 .github/ISSUE_TEMPLATE/release.md |  2 +-
 .github/PULL_REQUEST_TEMPLATE.md  |  2 +-
 docs/dev/changelog_updates.md     | 67 +++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/dev/changelog_updates.md

diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md
index d238df361..247365ad8 100644
--- a/.github/ISSUE_TEMPLATE/release.md
+++ b/.github/ISSUE_TEMPLATE/release.md
@@ -15,7 +15,7 @@ Feel free to edit this release checklist in-progress depending on what tasks nee
 - [ ] Update this issue's title to the new version
 - [ ] `release-prep` PR:
   - [ ] Update the CHANGELOG.md.
-    - [ ] Add links from the changelog entry to their GitHub issue
+    - [ ] Check that all the entries have a link to an issue or a pull request.
     - [ ] Add a clean `Unreleased` version.
     - [ ] Add the version to the old section.
     - [ ] Add the current date to the old version.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index c777e39aa..9dd40fc8e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,7 +4,7 @@ _What issues does this PR close?_
 ```[tasklist]
 ### Checklist
 - [ ] The PR title is short and expressive.
-- [ ] I have updated the CHANGELOG.md. See [changelog_update.md](https://github.com/sovity/authority-portal/tree/main/docs/dev/changelog_updates.md) for more information.
+- [ ] I have updated the CHANGELOG.md and linked the changes to their issues. See [changelog_update.md](https://github.com/sovity/edc-ui/tree/main/docs/dev/changelog_updates.md) for more information.
 - [ ] I have updated the Deployment Migration Notes Section in the CHANGELOG.md for any configuration / external API changes.
 - [ ] I have performed a **self-review**
 ```
diff --git a/docs/dev/changelog_updates.md b/docs/dev/changelog_updates.md
new file mode 100644
index 000000000..8892e534a
--- /dev/null
+++ b/docs/dev/changelog_updates.md
@@ -0,0 +1,67 @@
+Updating the Changelog
+======================
+
+This project uses a [CHANGELOG.md](../../CHANGELOG.md).
+
+## Structure of the Changelog
+
+Each pull request should also update the "Unreleased" section of the changelog.
+It should also update the "Deployment Migration Notes" Section of the unreleased section as preparation for the release.
+
+For each release there will be a separate section especially with an "Overview" section containing a summary
+from a product perspective.
+
+Releases will especially contain a "Compatible Versions" section with the final docker
+images and versions of other software components that are connected by APIs.
+
+## How to categorize a change
+
+The changelog uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Changes are categorized as either Major, Minor or Patch Changes.
+
+For this project, changes are categorized as the following:
+
+### Major Changes
+
+Major changes include:
+
+- UX / Product overhauls.
+- Breaking changes in Connector-To-Connector communication.
+- Breaking changes to the required deployment units (our UI doesn't count).
+- Breaking changes in our API Wrapper Use Case API.
+
+### Minor Changes
+
+Minor changes include:
+
+- Any changes from a product perspective to our UI or API Wrapper UI API.
+- Additions to our API Wrapper Use Case API.
+- New APIs with API contracts with other deployment units (our UI doesn't count).
+- New Product Documentation
+
+### Patch Changes
+
+Patch changes are basically everything else, that does not add, change or remove any product or external API features.
+
+- Product Fixes, Bugfixes, Refactorings
+- Changes to existing Product Documentation
+- New or changes to Developer Documentation
+- Everything else
+
+## Released Versions
+
+On releases the "Unreleased" section is emptied in favor of a new section for the release.
+
+Whether a release will bump the major, minor or patch version is decided by the unreleased changes in the changelog.
+
+The Release sections will be cleaned up on release, improved with additional information and made
+useful for the customer and people deploying the application, containing both product changes and
+deployment migration notes.
+
+More on that can be found in the [Release Issue Template](../../.github/ISSUE_TEMPLATE/release.md).
+
+## Linking
+
+The entries in the changelog should be linked to their corresponding issue.
+
+If for some reason the issue is not accessible for the public, link to the pull request instead.