GIScience / ohsome-quality-api

Data quality estimations for OpenStreetMap
https://api.quality.ohsome.org
GNU Affero General Public License v3.0
35 stars 7 forks source link

Use GitHub generate release notes feature instead of CHANGELOG.md #484

Closed matthiasschaub closed 1 year ago

matthiasschaub commented 1 year ago

On creating a release GitHub can generate release notes for you which are based on merged PR titles. One has then the opportunity to revise and change the suggestion. This could make the process of providing information about changes easier.

Currently one has to manually describe changes made in a PR in the CHANGELOG, where ideally the PR title should suffice. Also one has to copy paste in the PR number and URL which is a tedious process. One more problem is arising merge conflicts in the CHANGELOG when PRs are worked on in parallel.

One disadvantage with automatic generation of release notes is that one needs to make sure that every thing is mentioned and enough detail is provided. It could be that one needs to spend more time during the release process making sure that release notes are proper and helpful.

matthiasschaub commented 1 year ago

Sketch Map Tool has used it in the last Release: https://github.com/GIScience/sketch-map-tool/releases/tag/1.1.1

The GitHub docs for this feature: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

For the last OQT Release the notes would look like:


What's Changed

New Contributors

Full Changelog: https://github.com/GIScience/ohsome-quality-analyst/compare/0.13.0...0.14.0


With this approach we would likely be more careful when writing PR titles. Also we would moderate above list (Remove unnecessary ones and highlight important ones such as breaking changes. One can also add more context such as how to deal with a breaking change.

matthiasschaub commented 1 year ago

One can even configure automated release notes: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes