Maintain `CHANGELOG.md` again?

[tony]

Hi, thank you for the project!

A single, curated change file is ideal for conveying the value of changes across releases.

Note: This is a bikeshed / matter of taste from a downstream user perspective, apologies if this draws away from technical discussion.

Background

In 0.3+ release notes in the Changelog file was replaced by linking to GitHub Releases.

Elsewhere, the core strawberry project maintains a changelog as of 0.209.7.

Proposal

• Maintain CHANGELOG.md

• Hand-curate changelog instead of machine-generate it

• Keep GitHub Releases also

  It drive engagement and has benefits, but not be a replacement for what a changelog does.

Comparison

Changelog file (CHANGELOG.md)

https://github.com/strawberry-graphql/strawberry-graphql-django/assets/26336/75536c11-6441-4af7-b7cc-3ea097989b53

Pros:

• Portable
• Scrollable: changes across versions, 0.3.0 -> 0.2.1
• Linkable:
  • Anchor link to versions
  • Link to git tag releases via URL

Cons:

• For super active projects (e.g. Linux Kernel?), it'd need to be broken up into multiple files
• Takes more effort to maintain

Releases (GitHub Releases)

https://github.com/strawberry-graphql/strawberry-graphql-django/assets/26336/768384d5-da5a-4878-b767-4491dfed7af3

Pros:

• Automated adding of changes via PRs between git tags
• Mentions / shoutouts to contributors (for this I think it's worth keeping)
• Can show up in news feeds (for those who like that)
• Comparison tools:
  • Automated tool adds diff link
  • Select box to compare

Cons:

• Automated changes aren't a replacement for a maintainer's handmade release notes

  2 minutes of effort would give a better outcome than the automated notes.

  Example: Mention of pre-commit updates, doc updates, intermixed with bug fixes

• Bloat (in the eyes of a downstream user that simply wants to see what's happening)

  • Paginated, not scroll friendly
  • Blog-like design (white spacing, type setting)
  • Unnecessary elements: Asset files (I don't know if anyone uses these?)

• Not portable

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[bellini666]

Hey @tony ,

Thanks for bringing this up.

I want to use autopub for this, to make releases work the same way as they do on https://github.com/strawberry-graphql/strawberry, but I was waiting for v1.0 to be ready.

Maybe I'll use the current version in the meantime so we can have a nice CHANGELOG.md again soon :)

[tony]

Hi, thank you for the response!

I want to use autopub for this, to make releases work the same way as they do on https://github.com/strawberry-graphql/strawberry, but I was waiting for v1.0 to be ready.

First time hearing of autopub!

Does autopub's AGPL license give you any pause?

[bellini666]

Does autopub's AGPL license give you any pause?

What do you mean?

[tony]

License compatibility.

My opinion / I am not a lawyer (sorry if this doesn't go over well!):

Viral licensed dependencies intermixing with MIT licensed code risk creating a derivitive work. This is purely subjective, hypothetical - but downstream users may interpret it as a legal risk. Even if maintainers interpet the situation as fine.

This is the first case I've witnessed it in CI. Ideally permissively licensed code (strawberry being MIT license) would eschew viral dependencies from being in the codebase (unless it's unavoidable).

[bellini666]

Oh, I see.

Not sure if that applies to something used in CI, but if it does, it is actually something to think about in strawberry itself.

cc @patrick91 what do you think about this issue?

[tony]

Opinion again:

I highly doubt an AGPL dependency in a github action will be a stumbling block. But I'd gravitate toward finding an alternative so it's not causing friction.

Back to the original point of the thread, it's pretty easy to update CHANGELOG.md by hand 😄. Open the file, edit it while details are fresh on your mind, save it, stage it, commit, and push. I do it on 10+ projects.

[patrick91]

I can definitely ask Justin if we could change the library license to be MIT, or we could move autopub v1.0 to our org, after all autopub was part of Strawberry itself in the past 😊

There's also the option to migrate to https://github.com/knope-dev/knope (which is maintained by a friend of mine)

I think the easier thing would be to use the current version of autopub, and then migrate to v1.0 or something else in future :D