Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce a changelog #519

Closed
simbleau opened this issue Mar 13, 2024 · 1 comment · Fixed by #552
Closed

Introduce a changelog #519

simbleau opened this issue Mar 13, 2024 · 1 comment · Fixed by #552
Labels
documentation Improvements or additions to documentation

Comments

@simbleau
Copy link
Member

Get a changelog asap since vello is released, which would/should? also include a pull request template to remind the person to update the changelog.

@simbleau simbleau added the documentation Improvements or additions to documentation label Mar 13, 2024
@xStrom
Copy link
Member

xStrom commented Mar 13, 2024

Having a changelog in general is something that I heavily support. Having spent a lot of time writing and managing the Druid changelog, I also have thoughts about its structure and the logistics of adding entries - with some potential automation to help with merge conflicts.

Now when I say automation, I don't mean it being a list of commit messages. Commit messages and a changelog are meant for very different audiences. With commit messages / PR titles being written for the maintainers using specific internal lingo, while the changelog is meant for consumers of the project who probably have no clue about the internal workings. Thus the changelog should communicate changes that actually pierce through the API surface, whether that is changes to the API itself, effect changes, or performance impact. Written in simplified language. It is easy to link to a list of commits for those who want all the details.

On the ASAP part, that's fine as I think generally we should advocate for PRs to contain the changelog changes. Otherwise making releases can get too taxing with going through and understanding all past PRs. I also think that changelogs should contain consistent use of language, a style of how to say certain things. However those sort of style guidelines don't need to be there at the start.

I think it would be fine to start simple by just gathering some changes. The Druid CHANGELOG.md and CONTRIBUTING.md's changelog section could serve as a base to start from.

I'm thinking it might make sense to gather my thoughts on more thorough guidelines and submit it as an RFC for Linebender. Probably better for me to get to it sooner than later too, to prevent too much changelog rewriting later.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants