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

Open
wants to merge 17 commits into
base: master
from

Conversation

@newpavlov
Copy link
Contributor

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

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

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

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

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

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 referenced this pull request Aug 27, 2017
@nvzqz

This comment has been minimized.

Copy link

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

commented Aug 27, 2017

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

@vorner

This comment has been minimized.

Copy link

commented Aug 31, 2017

I think the current set of rules makes some kind of sense. I mean, changelog is technically free form and every author can do whatever they like, but:

  • It can hardly be called a changelog if it is not separated by versions.
  • The rules need to be followed only if you want your changelog to be rendered on crates.io. If you want to link to it (then you provide an url), have it as a .bmp image in your repository (then you don't provide the changelog key), etc, you're free to do that, only crates.io won't provide the service of rendering and hosting it. And if you ask it to render it for you, it is sane to provide a format it understands.
  • It is always possible to relax the rules in the future.

There's only the question of the unreleased section. On one hand, it makes sense, because at the time you publish the crate, nothing is unreleased, so that's a lint you forgot to move the entries to specific version. On the other hand it might make sense to keep it there in the meantime, not delete and recreate it every time a release is made. There's the possibility of allowing only empty unreleased section, but that feels a bit adhoc.

Also, I was wondering, could cargo new crate an empty changelog, as a hint that it's a good idea to have one?

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

commented Aug 31, 2017

On the other hand it might make sense to keep it there in the meantime, not delete and recreate it every time a release is made.

Good point, I will add it to unresolved questions. Personally I do not like that much idea to keep it, as I think initially changelog will be rendered in the same way as readme, so it will be strange to see empty "unreleased" section in it. Or we'll need to add filtering which will feel even more adhoc.

Also, I was wondering, could cargo new crate an empty changelog, as a hint that it's a good idea to have one?

I think it сould be done as a separate RFC. Because for example currently cargo new does not create empty readme file, while arguably good readme is more important than changelog, especially for potential crate users.

@bluss

This comment has been minimized.

Copy link
Member

commented Aug 31, 2017

Some existing crates have a changelog in a different format (restructuredtext) so anything that allows such things are a plus to me. It's not required that it can render it, but it requires that non-markdown isn't forced through a markdown renderer.

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

commented Aug 31, 2017

@bluss
As I wrote in the RFC it's definitely possible to extend number of supported markup languages. But to simplify the process I think it should be done through issues for cargo and crates.io after implementation of this RFC using MarkDown. If we'll support validation it will be logical to synchronously add rendering support to crates.io as well.

@dbrgn

This comment has been minimized.

Copy link

commented Sep 12, 2017

As the author of the first linked blogpost I very much approve of this RFC in general :) I have a few remarks though.

In my opinion some things in this RFC are too strict:

As a consequence of the last requirement changelog must not contain "Unreleased" section

I think that's overly strict and that Cargo should not add such a requirement. It will only result in workarounds, like not adding a heading for the unreleased changes.

All crate versions listed in the changelog must have been published earlier on crates.io, except the first entry

Why is that? It only makes it harder for projects that have had a few releases before their first crates.io release to publish. I see no advantage in adding this restriction.

In general, I'd either go for a specification that makes the format machine readable (to make it easier for automated tooling), or keep the format unspecified (except for markdown, so it can be rendered). I tend to favor the second approach. It can also be a gradual approach, where advanced rendering is done if the format corresponds to certain rules. As others in this thread have written, we could wait until some conventions form and until some tooling exists. If - for example - cargo would start to show changes on package updates, people would probably automatically start to format their changelogs in a way that they're supported by the tooling.

Oh, and I like the fact that you can link an external changelog, as an escape hatch for people that don't want to conform to the rules required for an explicit changelog file.

Regarding one of the unresolved questions:

Should we check correctness and/or availability of URL in the changelog field?

I would definitely do a check and warn the user if the URL isn't reachable (e.g. if a status code different than 2xx or 3xx is returned). But I'd provide a way to publish even if that URL is (temporarily?) unavailable.

(PS: I found two typos: additionall -> additional and externall -> external)

@tapeinosyne

This comment has been minimized.

Copy link

commented Sep 17, 2017

I feel we should open another RFC for the sole introduction of the changelog key. That much is uncontroversional, indisputably useful, and there is a strong precedent in readme, whereas detailed changelog formats require far more discussion. If we can agree that any guidelines can be established incrementally as conventions emerge, instead of enforcing a standard from the start, there would be no risk of breaking changes; even then, stabilization could still be delayed.

@newpavlov

This comment has been minimized.

Copy link
Contributor Author

commented Sep 18, 2017

@dbrgn

I think that's overly strict and that Cargo should not add such a requirement. It will only result in workarounds, like not adding a heading for the unreleased changes.

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.

Why is that? It only makes it harder for projects that have had a few releases before their first crates.io release to publish. I see no advantage in adding this restriction.

Hm, you are right, I haven't considered cases when crate can be initially developed without getting published on crates.io. I've removed this requirement.

@tapeinosyne
This "detailed changelog format" currently essentially boils down to "headline must start with the version", plus a safeguard to help crate authors remember to update their changelogs before publishing new crate version, which can be disabled if needed. As I see it, what you propose is to have the second readme, which seriously hinders any attempts to develop tooling around changelogs. And I believe it's overly optimistic to think that such approach will result in emergence of a common convention.

Also it's always useful to keep in mind that: "nothing is more permanent than the temporary".

@dbrgn

This comment has been minimized.

Copy link

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

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

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

commented Sep 21, 2019

@rfcbot reviewed

2 similar comments
@Eh2406

This comment has been minimized.

Copy link

commented Sep 21, 2019

@rfcbot reviewed

@smarnach

This comment has been minimized.

Copy link

commented Sep 22, 2019

@rfcbot reviewed

@sgrif

This comment has been minimized.

Copy link
Contributor

commented Sep 22, 2019

@Turbo87

This comment has been minimized.

Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.