Use a `changelog.{md,rst}` file

[tony]

This makes it easier for downstream packages to link to a range of changes.

Examples:

• https://github.com/pytest-dev/pytest-django/blob/v4.8.0/docs/changelog.rst
• https://github.com/pytest-dev/pytest/blob/8.1.1/doc/en/changelog.rst

Problem:

As a downstream package, it's nearly impossible to convey to the user changes from 0.6.2 -> 1.1.3 using GitHub releases.

[gaborbernat]

We use GitHub release notes and don't plan to change.

[tony]

@gaborbernat Can you explain why?

The reason I ask is - from a downstream user's perspective - GitHub Releases makes it very arduous, almost impractical, to comprehend changes across a range a releases.

Example (as a downstream package user):

• With only GitHub Releases: If I wanted to document to other's the changes between 0.6.2 and 1.1.3 - there's no way I could select a range of releases to convey to other's what changed other than link to individual releases, e.g. https://github.com/pytest-dev/pytest-env/releases/tag/1.1.3, https://github.com/pytest-dev/pytest-env/releases/tag/1.1.2, https://github.com/pytest-dev/pytest-env/releases/tag/1.1.1, https://github.com/pytest-dev/pytest-env/releases/tag/1.1.0.

• With a changelog: If I wanted to show changes between pytest-django 4.0.0 and 4.8.0, I could simply link to https://github.com/pytest-dev/pytest-django/blob/v4.8.0/docs/changelog.rst and they could scroll down.

[gaborbernat]

Adding a release changelog is extra work that I'm not willing to do. Plus we have to make sure that it aligns up correctly with GitHub releases that some people prefer over changelogs. This is something I'm not willing to do for such a small project. Furthermore having a changelog that needs to be updated before a new release would make the release a much more difficult process. Again this is something not I'm willing to do for such a small project.

[The-Compiler]

I don't follow. What's the difference between someone scrolling down on a changelog and someone scrolling down on https://github.com/pytest-dev/pytest-env/releases instead?

[tony]

Adding a release changelog is extra work that I'm not willing to do. Plus we have to make sure that it aligns up correctly with GitHub releases that some people prefer over changelogs. This is something I'm not willing to do for such a small project. Furthermore having a changelog that needs to be updated before a new release would make the release a much more difficult process. Again this is something not I'm willing to do for such a small project.

I've found it worth it for me (I also maintain a few open source packages): I frame it in terms of usefulness to downstream users and project sustainability, where the payoff is decent.

It takes me under 3 minutes - usually - to tighten up a changelog before cutting a release. The only exception is when APIs are deprecated. Proactively, I update the file before merging a PR (or immediately after) while a changeset is fresh on the mind.

I don't follow. What's the difference between someone scrolling down on a changelog and someone scrolling down on https://github.com/pytest-dev/pytest-env/releases instead?

I have a video comparison between changelog and github releases here: strawberry-graphql/strawberry-django#396.

GitHub Releases:

• Cannot Ctrl-f/Command-f across all releases

• Cannot use anchor links

• Aren't portable outside the project (a changelog lives in the git repo itself)

• Requires viewers to paginate

• Encourages automated generation changes that aren't helpful to downstream users.

  I think the maintainer / releaser is in the best position to highlight what they feel is most important when a new version is cut.

[gaborbernat]

I've found it worth it for me (I also maintain a few open source packages): I frame it in terms of usefulness to downstream users and project sustainability, where the payoff is decent.

Great for you, but we don't plan to do it for now. All the best!