From 9bf0bcd8394d9c252df2812d1153312d8b5f6a69 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Thu, 6 Jul 2023 15:07:13 +0200 Subject: [PATCH 1/2] docs: add decision record about removing the CHANGELOG.md --- .../README.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md diff --git a/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md b/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md new file mode 100644 index 000000000..eab7eab26 --- /dev/null +++ b/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md @@ -0,0 +1,30 @@ +# Removal of manually curated CHANGELOG.md + +## Decision + +We will not maintain a manually curated `CHANGELOG.md` file anymore. Instead, we will rely on an automatically generated +one. GitHub Releases offers that feature. + +## Rationale + +Manually curating a CHANGELOG.md is an arduous process, that does not offer any real value, rather, it introduces mostly +problems. Chief amongst those are the fact that typically the curation happens shortly before the release, which +increases pressure, and introduces the possibility that something is forgotten. Also, digging up the correct issue/PR +numbers is a tedious process. + +Relying solely on GitHub Releases fixes all that, because it will generate a succinct changelog, complete with issue/PR +number and contributor. + +We would lose the possibility to formulate "humanly readable" change log entries, but that is easily offset by the fact +that we [use conventional commits](../2023-04-20_conventional_commits). + +Thus, the commit log should be easily digestible and understandable, assuming a frequent release cycle. + +## Approach + +First, we need to fix the release process. It seems that at the time of this writing, the release PR contains _all_ +commits, instead of just the delta between `main` and the last release. + +This is also reflected in the automatically generated changelog, for +example [0.5.0-rc5](https://github.com/eclipse-tractusx/tractusx-edc/releases/tag/0.5.0-rc5). Once that is fixed, we can +delete the CHANGELOG.md file and [this GH action to update it (line 44)](../../../../.github/workflows/draft-new-release.yaml). From 0dce08ffceb44515688f4fff9715cba92e6031b3 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Thu, 6 Jul 2023 15:47:19 +0200 Subject: [PATCH 2/2] amended merge commit --- .../2023-07-06_removing_manual_changelog/README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md b/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md index eab7eab26..944e775e5 100644 --- a/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md +++ b/docs/development/decision-records/2023-07-06_removing_manual_changelog/README.md @@ -25,6 +25,12 @@ Thus, the commit log should be easily digestible and understandable, assuming a First, we need to fix the release process. It seems that at the time of this writing, the release PR contains _all_ commits, instead of just the delta between `main` and the last release. +This is because upon merging normal PRs, we typically do a "Squash-And-Merge". The same thing was done on release PRs, +which caused the git histories of `main` and `releases` to diverge. + +> **For this to work, it is imperative to create a "Merge commit" for release PRs as that will preserve commits!** + This is also reflected in the automatically generated changelog, for example [0.5.0-rc5](https://github.com/eclipse-tractusx/tractusx-edc/releases/tag/0.5.0-rc5). Once that is fixed, we can -delete the CHANGELOG.md file and [this GH action to update it (line 44)](../../../../.github/workflows/draft-new-release.yaml). +delete the CHANGELOG.md file +and [this GH action to update it (line 44)](../../../../.github/workflows/draft-new-release.yaml).