Now that breaking changes are much more rare, and preceded by long discussion of how the breakage can be worked around, it may be worthwhile to provide a single document that lists:
Summary of the change.
Information that helps you identify that it is indeed this change that broke your code (e.g. the feature or function affected, or the compiler error messages mentioned).
How to fix your code:
If it’s a compile time error, how to rewrite the code to compile with the same semantics.
If it’s a behavioral change, how to rewrite code to keep the old behavior.
This came up while talking to the developers of ares about the recent change to accept leading plus in integer parsing. If you don’t follow the Rust repo closely, it can be difficult to make sense of the [breaking-change] commit messages and find the exact information that you need to fix your crate.
It could be as simple as a Markdown file in the repo. Since we don’t do as many breaking and behavioral changes any more, it may not be an undue burden to ask people to write a paragraph or two about their change in such a log. (Then again, we still cobble together the release notes on the day before the release…)
Can you elaborate a bit more on what makes the existing [breaking-chance] convention hard to follow, and why having a central markdown file would help things? It seems likely to me that it may be that we need better descriptions, for example, and not just the same descriptions in a different location.
Yes, better (more comprehensive) descriptions is a part of it. Many commit messages already hit some of the points mentioned above, in particular “how to fix your code” is often in the commit message. However, that’s not universal, so what I’d like is a code of honor to document all these aspects. The specific complaint from the ares authors (well, one of them) was that they could not find the change that broke their crate. Partly because that commit was not tagged as breaking, but I’ve also seen commit messages that would have been pretty useless to affected crate authors (and I’m guilty myself).
The reason I am suggesting a central markdown file is that commit messages, despite the very nice bitrust websites, are not the best medium. They cannot be modified afterwards, especially when we (author and reviewers) forget a [breaking-change] tag where it should be. That shouldn’t happen, but there is at least one recent example (the behavioral change for int .parse()-ing to accept leading plus). Additionally, you don’t have to cram all the details of the aforementioned better description into the commit message (where it often competes with Rust-internal remarks for space), hopefully leading to more elaboration on what the breakage is and how to fix it. And if you do miss something, the first person to fix their crate can complain about this lack of detail and someone will hopefully improve it.
This is a good point. I guess that it would also allow us to amend afterwards with further examples. Clearly, such a file will still become a vector for conflicts, but I am not opposed to the idea in principle.
I'm curious: have you looked at the actual frequency of breaking changes these days? I feel like I am seeing "breaking changes" quite regularly, but they are only breaking to authors of plugins and other unstable things. It might be worth trying to segregate out who is affected.
I don’t follow all the PRs, so I only have bitrust to go by, which may miss some breaking changes. As one data point, there were 12 [breaking-changes] commits in the last month (i.e. after September 15), four of which I’d categorize as being only interesting to plugin authors. Twelve is not a lot, but 8 will be easier to handle. IMHO there is no good reason to go through all this trouble when changing compiler internals — everyone who relies on those will be familiar with the rust repo anyway. Unstable but user-facing APIs can also be called into question, but I would err on the side of too much documentation there.
By bitrust, I guess you mean http://bitrust.octarineparrot.com/? I wasn't aware of that, but it looks handy (though the plain text formatting leaves something to be desired).
Well, plugin authors have complained in the past about it being hard to keep up or to figure out what they are supposed to do, so I'm not sure.
I still wonder if we can come up with some alternative scheme to a markdown file. For example, I could imagine creating an internals thread (and including a link), so that we can answer questions about the impact of a change, or something like that. (That doesn't address though marking a change as breaking after the fact.)
It is indeed handy, but only as good as the commit messages.
Suggestions for alternate schemes are certainly welcome! I like the idea of an internals thread (though, wouldn't users.rlo be more appropriate, especially if we exclude compiler-internal refactorings?). Someone (ideally the one who made the change) adds a post for one breaking change and edits it as necessary. Other people can ask for clarification and add further information. Those posts could even be deleted after the information is incorporated in the first post, to make the thread a short and neat long-term reference for breaking changes. If you notice breakage after the PR has landed, you can still add a post to the thread. Also, free e-mail notifications for breaking changes if you watch that thread.
I haven’t read this thread (sorry), but the problem with these ideas is always in the execution. Getting all the right people looking out for the changes, tagging them, and documenting them.
Right now we have process for tagging breaking commits, tagging regressed issues, tagging release notes, and these processes are followed by those who know, when they can, but not with perfect consistency. Just doing what we already are is a great burden!
Augmenting that with a human going in, understanding all of them, and writing coherent documentation, is a huge task.
Edit: I also try to point out the most relevant breakage in the release notes.
Yes, I am painfully aware of that. I hope a format like a forum thread will recruit more people into the process, including those who don't (closely) follow the repo, but that is just speculation.
Can you push and pull those? Does GitHub support PRs with them, especially if they alter nothing except notes? Can they meaningfully be merged?
I think just a reaffirmation of the breaking-change convention would be helpful. Just so that everyone thinks about it again and we remind each other to insert the tag (and helpful notes to describe the break).
@bluss Yeah, perhaps a top-level post that outlines the current accepted wisdom around breaking changes and regressions would be an easy start. I still want to get the regression* tags working in a more consistent way, and I’m not myself clear on how they should be used.
I realize I’m conflating breaking changes and regressions but they are closely related.
My intent is to improve the experience that users have with breaking changes. So we’re still perfectly on track. And while I believe there is a better format to be discovered, even just doing the commit message thing better would be an improvement and very welcome.
I am definitely intrigued by the idea of having some sort of editable-after-the-fact page, whether it be a thread or a wiki link, at least for major changes. It’s often hard to tell when writing the commit msg just what kinds of scenarios you should highlight. But I also don’t want to make it a big pain to post a PR.
Re: git notes - see also this blog post for further explanation of git notes.
They are regular git objects that just live in a separate namespace and leverage the same infrastructure as your regular commits.
In short, notes implement exactly the sort of use cases discussed in this thread.
This tool clog is supposed to help with commit->changelog management, and it’s written in Rust.
I might be in favor of adding a PR bot that validates commits are in some format, maybe suggesting proper relnotes when it sees api stabilization, implementations of RFCS or other scenarios, using an automated tool to generate a draft of relnotes for further editing, possibly by following ‘relnotes’ tags, milestone issues, etc.
