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

RFC: Crate changelogs #2129

Closed
wants to merge 17 commits into from
Closed

RFC: Crate changelogs #2129

wants to merge 17 commits into from

Conversation

@newpavlov
Copy link
Contributor

newpavlov commented Aug 27, 2017

Rendered

This RFC proposes addition of changelog support to cargo and crates.io.

The main proposal is to add changelog field to [package] section of Cargo.toml which can point either to changelog file supplied with the crate, or to external resources. (e.g. GitHub releases or custom websites)

In the first case, changelog file should follow the minimal set of rules. Also this RFC specifies additional check for cargo publish, so crate authors will not forget to update changelog before publishing the new version.

Changelog rendering on the crates.io can be done through additional link on top bar:
1

This proposal initially also included a multi-file approach to handling changelogs. (most of the initial comments discuss this part) While I believe it would be good for ecosystem to define stricter conventions around changelogs with enhanced machine readability, but based on response, I've moved this part to a separate (closed) RFC.

newpavlov added 3 commits Aug 26, 2017
@Lokathor

This comment has been minimized.

Copy link

Lokathor commented Aug 27, 2017

I'm not professional enough to write changelogs. Will cargo and/or crates.io be able to automatically generate an API diff from one version to the next and spit out that as the change log?

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

newpavlov commented Aug 27, 2017

@Lokathor
Certainly not as part of this RFC. But this functionality can be introduced by subsequent RFCs in the form of additional cargo changelog subcommands.

@nvzqz

This comment has been minimized.

Copy link

nvzqz commented Aug 27, 2017

Glad my post could help get this discussion going! :)

I don't think that having a changelog be a commit diff is a good idea. There's lots of irrelevant messages from commits like with merge commits.

@Lokathor If you don't believe you're professional enough to write a changelog, open an issue to ask for help with it. The issue will bring attention to the lack of changelog to people who see the repo.


Edit:

For this scenario, having a decent grasp of the project's native language (usually English) should be enough for writing a base changelog. If others expect more from it, they can open pull requests to improve it. This can also happen to explain certain nuances of changes that may not be expressed in the original text.

@nvzqz

This comment has been minimized.

Copy link

nvzqz commented Aug 27, 2017

How should a changelog address a project that has been deprecated in favor of another project?

And if not in favor of another, it should address that the author may not have enough time to support it. Or maybe the project had unsafe effects (accidental malware?) that people want to study rather than used in legitimate software?

@boustrophedon

This comment has been minimized.

Copy link

boustrophedon commented Aug 27, 2017

@nvzqz Wouldn't that sort of stuff just go in the README? Changelogs (as promoted by keepachangelog) don't usurp readmes.

@Lokathor Lokathor mentioned this pull request Aug 27, 2017
@nvzqz

This comment has been minimized.

Copy link

nvzqz commented Aug 27, 2017

@boustrophedon the changelog described has an Unreleased section. It would just be a message stating that no more releases should be expected.

@tblair

This comment has been minimized.

Copy link

tblair commented Aug 27, 2017

I'm uncomfortable with Rust tooling taking an opinionated view towards changelogs, especially when that opinion marginalizes a project like clog that's been part of the Rust ecosystem for a long time now. I can definitely see why people would prefer the keepachangelog.com approach, but I don't think Cargo should make that decision for project authors. This would be especially galling to any project that has put the time and effort into maintaining a conventional commit history.

This is an area where there are multiple specifications and whatever Rust tooling gets built should allow project authors to choose whichever approach they prefer.

For anyone unfamiliar, here is the spec for the conventional commit method of handling changelogs and here are the Angular commit guidelines on which its based.

@sunjay

This comment has been minimized.

Copy link
Member

sunjay commented Aug 27, 2017

I think changelog support would be awesome, but I don't get the need for the custom split-file format. As stated in the RFC, this deviates from the norm. I don't know if anyone would think to look for a changelog folder. I certainly wouldn't want to have one in my repo because I prefer the single file changelog.

I like everything about adding the changelog link to crates.io and I'm in favor of having the key for that in Cargo.toml, but I'm not sold on the split changelog thing. I don't see why the changelog needs be generated at all.

I know maintaining a changelog by updating it's links and adding new sections can be a pain, so maybe an external tool that makes that awesome would be a good idea. Just working on changelogs doesn't seem like something that should be part of cargo.

Thanks for making the RFC! I'm glad someone is talking about this. :)

@vorner

This comment has been minimized.

Copy link

vorner commented Aug 27, 2017

I like the intent to add a changelog to crates.io and to Cargo.toml. I even agree with requiring certain format (it makes sense, if it needs to be rendered somewhere).

However, I very much dislike the split into files. I keep changelogs with my crates (at least once the API settles a bit), but I prefer having all the changes in one file. It's easier to search for something. And when I download a repository (or open it at github), having to either generate the changelog locally or searching multiple files feels like a lot of added work for no real gain (and keeping a generated file in git is also wrong). Also, having to be online for generating the changelog feels somewhat inconsistent with the fact that almost everything cargo does works offline (except when adding and downloading dependencies).

What work is actually saved by that split? Adding the dates? Moving the lines from unreleased section to the current version? If the changelog has a standardized format (MD with the given sections), any tooling should be able to handle it in a single file as well.

@mehcode

This comment has been minimized.

Copy link

mehcode commented Aug 27, 2017

👍 on prescribing a general format as loose as possible

  • Headers with version/date
  • Bullet lists with updates
  • Bullet lists can be optionally categorized

I'd like to define the layout enough that we could do this on crates.io but no more.

I strongly dislike the tool that generates a changelog from a folder structure being officially part of Rust. I'd rather see that tool compete with clog as separate crates.


Huge +💯 to a link. I just think we can do better than a link ( see gemnasium link above ) if we describe a loose format as well.

@est31

This comment has been minimized.

Copy link
Contributor

est31 commented Aug 27, 2017

I'm not really a fan of adding yet another folder. One file should be enough IMO. If I look at the changelog I keep for my lewton crate, I see some releases with only two bullet points. Making a file for only one or two bullet points is a waste IMO.

Generally I think we should be as liberal as possible with the changelog format, and not dictate one.

@bluss

This comment has been minimized.

Copy link
Member

bluss commented Aug 27, 2017

I agree with @est31. From the author's perspective, a file per release is neat and simple. From the user's perspective, when I look at a change log, I am probably reading it like a timeline: I'm going to read everything from some point and up until the current state, so I'll read through multiple releases, and a single file is then much easier to read.

Of course for big enough projects, splitting the change log per release again becomes reasonable.

@sunng87

This comment has been minimized.

Copy link

sunng87 commented Aug 27, 2017

+1 for keeping changelogs in a single file. Also I think a changelog needs to be written by hand to include information curated and prioritized.

In recent version of handlebars, I put unreleased changes in an Unreleased section, when the change is merged into master. And I configured cargo-release to replace Unreleased with new version number. Then the changelog is ready.

I knew a lot effort has been put into changelog auto generation. But this is my best workflow by far.

Sent from my Google Nexus 9 using FastHub

@flosse

This comment has been minimized.

Copy link

flosse commented Aug 27, 2017

+1 for keeping changelogs in a single file. Also I think a changelog needs to be written by hand to include information curated and prioritized.

+1

@arthurprs

This comment has been minimized.

Copy link

arthurprs commented Aug 27, 2017

I have mixed feelings about this.

What about just inserting a changelog link on crates.io that shows the rendered CHANGELOG{.md} if present?

@ruuda

This comment has been minimized.

Copy link

ruuda commented Aug 27, 2017

It looks like the consensus so far is that a single file is preferred over multiple files. What the format of that file should be is less clear.

  • It could be strictly specified, which can be useful for machine readability, but which would force a format onto projects that might not be suitable for them.
  • Projects could be free to choose the format which makes sense for them, just like they can with a readme.

I would prefer the second option. What a good changelog looks like depends a lot on the size, release schedule, and purpose of the project.

@mathstuf

This comment has been minimized.

Copy link

mathstuf commented Aug 27, 2017

I'd love to have the changelog rendered, but I'd rather it just be "we will render any of these paths in crates.io" and how it gets there is uncared about (additional tooling is fine). I really don't like the type: prefix specs because I feel it wastes precious subject space (I prefer area: prefixes because they are easier to sort/skim on).

The way I usually do release notes is that each PR which needs one drops a new file in a specified directory and at release time, they get collated into a single file and deleted. This stops conflicts from happening, supports cherry-picking into backport branches easily with no change in process, and allows for the maintainer to collate and group release notes as necessary or wanted.

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

newpavlov commented Aug 27, 2017

Thank you for your responses!

While it was not my intention I think emphasis on a new multi-file approach was too strong. I've moved it into a separate RFC and updated this one to a minimal version.

One thing which I think is very important is to have at least minimal degree of machine readability and safety check in cargo publish based on that. So cargo will be able to help library authors to remember to update their changelogs.

[alternatives]: #alternatives

This proposal defines minimal format for changelog, leaving as much flexibilty
for crate authors as possible withoout droping the basic machine readability.

This comment has been minimized.

Copy link
@mathstuf

mathstuf Aug 27, 2017

typo: "dropping"

@jimmycuadra

This comment has been minimized.

Copy link

jimmycuadra commented Aug 27, 2017

The changelog field in the Cargo manifest should just be a URL like the documentation field. It doesn't make sense to impose any particular mechanism for change logging. As proposed in the RFC, this would not be useful to me because I use GitHub's releases page instead of a file in the repository. I've also seen some projects use detailed commit messages on Git tags instead of a file. I don't think users really care what format the change log is in, just that there is one and that they can find it.

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

newpavlov commented Aug 27, 2017

@jimmycuadra
I don't agree with your position, I think it's quite important to have a coherent way of showing changelogs, instead of linking to a dozen of external resources. Also projects which would like to use a different approach always can specify it in the readme.

But either way I will mention your proposal as an alternative solution.

@killercup

This comment has been minimized.

Copy link
Member

killercup commented Aug 27, 2017

My comment on your other changelog RFC is also valid for this one :) #2131 (comment)

@dbrgn

This comment has been minimized.

Copy link

dbrgn commented Sep 18, 2017

I don't think it makes much sense to have "unreleased" section in the changelog for published crate, especially if changelogs will be initially rendered as readme without any post-processing.

Hm, that's a good point. Some workflows will need to change, as some people add the unreleased section at the same time they release the previous version. But that change can just as well be done after the release commit.

text/0000-crate-changelogs.md Outdated Show resolved Hide resolved
@Centril Centril added the A-changelog label Nov 22, 2018
@nrc nrc added the T-crates-io label Sep 4, 2019
@ehuss

This comment has been minimized.

Copy link
Contributor

ehuss commented Sep 21, 2019

We discussed this RFC in the Cargo team meeting, and we feel like we probably don't want to move forward with this at this time. There are some points, such as the proposal for a single format that could be machine-readable that we think may be a little too strict. If the proposal then reduces to just a link that will be displayed, then it seems to not bring much value over placing a link within a README.

We acknowledge that there is a desire to encourage crate authors to provide a changelog, and to make it easier to access that information. We thank everyone for their work and discussion. There may be some solution to improve communication of release notes, but it's not clear what that would look like.

@rfcbot fcp close

@rfcbot

This comment has been minimized.

Copy link

rfcbot commented Sep 21, 2019

Team member @ehuss has proposed to close this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

@ishitatsuyuki

This comment has been minimized.

Copy link
Contributor

ishitatsuyuki commented Sep 21, 2019

@rfcbot reviewed

2 similar comments
@Eh2406

This comment has been minimized.

Copy link

Eh2406 commented Sep 21, 2019

@rfcbot reviewed

@smarnach

This comment has been minimized.

Copy link

smarnach commented Sep 22, 2019

@rfcbot reviewed

@sgrif

This comment has been minimized.

Copy link
Contributor

sgrif commented Sep 22, 2019

@Turbo87

This comment has been minimized.

Copy link
Member

Turbo87 commented Sep 23, 2019

@rfcbot reviewed

While I do agree that crates with more than one release should probably have a changelog, I don't think enforcing them like that is something we should do. If we built some sort of rating system into crates.io that judges the quality of a crate we could consider it as part of the metric though.

@jtgeibel

This comment has been minimized.

Copy link
Member

jtgeibel commented Jan 4, 2020

@rfcbot reviewed

1 similar comment
@locks

This comment has been minimized.

Copy link

locks commented Jan 10, 2020

@rfcbot reviewed

@rfcbot

This comment has been minimized.

Copy link

rfcbot commented Jan 22, 2020

🔔 This is now entering its final comment period, as per the review above. 🔔

@rfcbot

This comment has been minimized.

Copy link

rfcbot commented Feb 1, 2020

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC is now closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

You can’t perform that action at this time.