tl;dr: it is difficult for users, distro package maintainers, and others to know what kind of potential disruptions are expected from an upcoming release. I think it would make sense to have a low-traffic announcement list for times when Clang is changing in a way that we think may be significantly disruptive. It’s not a channel for proposing such changes, but announcing once they’ve landed in the tree.
It was pointed out during discussion of Configure script breakage with the new -Werror=implicit-function-declaration that disruptive changes are hard for folks not living at HEAD to notice and it would be nice to communicate those kinds of changes more proactively in an effort to avoid surprises after we’ve made a release. For example, changing a warning to be an error by default, fixing long-time accepts-invalid bugs, removing command line options, etc are all changes that might cause significant disruption and are worth pointing out. Less potentially disruptive changes (adding new warnings which may break -Werror code, rewording diagnostics that might be read in by scripts, etc) would not be reported in this channel, so it’s not expected to alert users to any potential disruptions, only ones where someone (patch author, reviewer, etc) believes we need to warn people to get early feedback on a finished change.
We currently add that information to our release notes, and ⚙ D133771 Add a "Potentially Breaking Changes" section to the Clang release notes proposes making that information more prominent there. But notifying users more proactively would be a big improvement as well, because users cannot subscribe to release notes like they can do a Discourse channel.
CC @tonic for awareness as I don’t know how we go about getting new channels added to Discourse or what the criteria are when thinking about adding one, but I’m betting she knows.
Rather than creating a new Discourse category, perhaps broadcasting these notices to the existing Announcements category would make sense. I imagine most downstream consumers of community releases already monitor that category (or they should) and may appreciate being notified via the same channel.
In Discourse it’s also possible to subscribe to a certain tag - I wondered if you’d considered introducing a new tag and encouraging users to subscribe to that as an alternative? The downside is it’s perhaps less discoverable. A potential upside is it might mean that any follow-on discussion in these threads is more discoverable due to minimising fragmentation into lots of sub-forums.
I would suggest posting to Announcements. This is supposed to be similar to the announce mailing list we had before. Lower traffic and for announcements in the the project.
I would also suggest tagging the post as an additional layer of categorization.
I think Announcements would work well enough. I was concerned the non-Clang posts such as the one about the LLVM dev conference would make it more difficult to find the “we might break you with this change” kind of announcements, but the channel has low enough traffic that it’s probably fine, especially with the use of tags.
The idea behind the list is that its major announcements that we want to reach the largest number of people. The traffic is low and people can subscribe to “First Post” only style notifications if they wish.
How often do changes that have such big impacts occur? I’m wondering if this could be communicated with a release testing announcement that combines everything into one. It could capture all the major changes that might cause some impact to distributions, etc and then be communicated in a timely manner before the release is final. It sounds like being in the Release Notes is too late for some, but maybe asking those to test for each new change might be a lot? Thoughts?
Another thought… should the Release Schedule announcement be going to Announcements as well?
Well, either you pick one tag to communicate all of these sorts of changes or use tags to communicate a more specific type of change (“config-changes”?). Or both. I’m not sure what to call the high level type tag. Maybe “upcoming-release-impact”?
I like the idea! I would propose not to limit it to Clang, but use it for all Potential Breaking/Disruptive changes in the LLVM project. We can add a tag for the subproject(s) affected by the change.
In Phabricator there is a group libc++ vendors. When we have potential disruptive libc++ changes for vendors we add this group to the review. Maybe Clang can consider to create a Clang vendors group.
Thanks for driving this, +1. It’s not only helpful for upcoming releases but also serves as a good warning for those frequently building their codebase against ToT to catch issues early.
Less potentially disruptive changes (adding new warnings which may break -Werror code, rewording diagnostics that might be read in by scripts, etc) would not be reported in this channel, so it’s not expected to alert users to any potential disruptions, only ones where someone (patch author, reviewer, etc) believes we need to warn people to get early feedback on a finished change.
My take is that we should encourage reports from authors who care about breakages, regardless of how potentially disruptive changes might be - I have the feeling this is somewhat what you’re saying, but I got a bit confused
I would have appreciated that when I was maintaining a downstream distribution. I was aware of the schedule posted to https://llvm.org, and would occasionally check it, but notifications to my inbox would have been useful to keep me better aware.
If we’re talking about “big impact” changes, mayyyybe once a month (guessing here based on recent activity). If we’re talking about “we can dream of a way this will break people” it’s probably more frequent.
That might be reasonable too. I had the impression some people wanted “warn me as early as possible so I can test” and other people wanted “warn me before the release goes out the door so I can test”, so I was imagining we’d want to announce as the changes happen and then make sure the potentially disruptive changes can all be found in one spot in the release notes rather than sprinkled all over.
That seems like a reasonable idea to me!
Oh! Today I learned that we can use hyphens in these tags! upcoming-release-impact would be fine by me, as would potentially-breaking-change, etc.
Based on the members list yes. Several of these vendors are actively contributing to LLVM.
For some patches it is great to get vendor feedback during the review. For others it’s good to inform them. But I really like @AaronBallman’s suggestion to post it on Discourse. So yes I think we should do that even for the ones where they vendors were added to the review. I think a discourse group is easier to “collect” these changes than Phab reviews.
Nowhere. I would say libc++'s documentation is good, but some details are missing. Especially things that are well known by active contributors. Still it would be great to document these missing pieces, when we learn about them.
Thank you everyone for the good discussion and ideas! It sounds like there’s general agreement that Announcements is a good place to put this information and use a tag to distinguish potentially breaking change announcements from other kinds of announcements. I think it also makes sense to start adding clang-vendors as a subscriber to any Clang code review we think may impact vendors. Between all of these mechanisms (and the fact that we’re announcing potentially breaking changes more clearly in the release notes), I think we’ve made some really good steps at improving communication with our users.
I have some breaking changes from the release notes to announce, so I’ll make the inaugural post and put it under the tags potential-disruption and clang; other projects that want to make similar announcements can use their own project’s tag.
Oops, found a minor bump in the road. The announcements forum is locked so nobody can make new posts in it.
I think we’d need to unlock that forum for this to work (we want to encourage patch authors to make these announcements rather than funnel them through someone else; the less friction there is in the process the more likely it is people will follow it), but maybe @tonic has other ideas?
(I feel like moderation should be sufficient to handle any use of Announcements that’s inappropriate.)
