strawberry-django
strawberry-django copied to clipboard
Maintain `CHANGELOG.md` again?
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.
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 :)
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?
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).
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?
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.
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