dd-trace-py icon indicating copy to clipboard operation
dd-trace-py copied to clipboard

Published 20 hours ago • verified publisher icon DataDog

Docs / Bikeshed: Reconsider maintaining a single `CHANGELOG.md` file

Open tony opened this issue 2 years ago • 4 comments

Hi! Thank you for the project.

Summary of problem

dd-trace-py release notes aren't being conveyed succinctly to downstream users due to replacing a changelog file for GitHub releases.

Release notes are not a viable replacement for a changelog:

  1. Changelogs are a single file, can be scrolled across in a stream, git tagd, and portable

    Example spec: keepachangelog

  2. Releases are kept in https://github.com/DataDog/dd-trace-py/releases

    GitHub releases are fragmented across releases with blog-like typesetting and whitespacing, file assets, include unnecessary repetition in the form of pre-releases, and further break concentration by paginating.

    It hampers understanding what's changed across versions, esp. after a few months pass.

How can we reproduce your problem?

Try to link to a tag or span of a version release, e.g. v2.0.2 to find updates since v1.13.0

What is the result that you get?

  1. Load changelog page via docs or GitHub

    image

  2. And then, after a few clicks, going to https://github.com/DataDog/dd-trace-py/releases

  3. Paginating through pages of beta releases / repetition, whitespacing, and having a very difficult time compared to just having a markdown file.

    https://github.com/DataDog/dd-trace-py/assets/26336/f6cf2ecb-d2cd-4e3b-8536-5baf0433b91a

What is the result that you expected?

Being able to load CHANGELOG.md at v2.0.2 and simply scroll down and see final version releases since v1.13.0 without GitHub releases.

Example, Flask (CHANGES.rst: repo, docs)

https://github.com/DataDog/dd-trace-py/assets/26336/06b936c0-5fb0-4d51-a806-5ebdb79330ea

tony avatar Oct 11 '23 14:10 tony

Thank you @tony for raising this!

Your proposal to maintain a changelog is one we have discussed on the team.

The question I have had is what we should do with the "release notes" we included in our sphinx docs. Do we continue to use reno and publish them with the GitHub releases?

What do others think of maintaining a separate release notes file more information relevant to a release can be communicated?

majorgreys avatar Oct 11 '23 20:10 majorgreys

The question I have had is what we should do with the "release notes" we included in our sphinx docs. Do we continue to use reno and publish them with the GitHub releases?

If Reno can publish versions to a single page like this, that'd be a good compromise in lieu of just maintaining of CHANGELOG.md.

tony avatar Oct 12 '23 12:10 tony

Separate topic / opinion: Many users don't need to see prerelease and betas, though it's encouraging to see active development and dedication to a package.

When 2.1.0 final is released, the only thing that matters (to me) is what changed between the last 2.0.x release, e.g. 2.0.2. The alpha, beta, release candidates, etc. are repetitious after a final version goes live.

tony avatar Oct 12 '23 12:10 tony

@tony you also highlighted how having release notes included in pre-releases creates problems:

Paginating through pages of beta releases / repetition, whitespacing, and having a very difficult time compared to just having a markdown file.

Including release notes with the pre-releases gives a preview of the documented changes to come. Unfortunately GitHub does not allow for that.

The only solution to the problem you are raising that I see is for us to edit or delete pre-releases once another RC or final version is created. What do others think?

majorgreys avatar Oct 12 '23 18:10 majorgreys

The CHANGELOG.md file is now automatically updated when stable versions are released. It doesn't currently contain the entire history of patch releases, but it should.

As far as I can tell, this issue is now resolved. Please comment if I missed something.

emmettbutler avatar Mar 29 '24 13:03 emmettbutler

@emmettbutler This is very high quality! https://github.com/DataDog/dd-trace-py/blob/c3532ff/CHANGELOG.md

Nice!

git tag release to changelog

Moving forward, in future releases, hopefully the version in CHANGELOG.md is linked to the git tag, e.g.

  • v2.7.5 would be at the top of https://github.com/DataDog/dd-trace-py/blob/v2.7.5/CHANGELOG.md
  • v2.7.6 would be at the top of https://github.com/DataDog/dd-trace-py/blob/v2.7.6/CHANGELOG.md
  • v2.8.0 would be at the top of https://github.com/DataDog/dd-trace-py/blob/v2.8.0/CHANGELOG.md

Let me know if that makes sense or if I should rephrase.

tony avatar Mar 29 '24 13:03 tony