-
Notifications
You must be signed in to change notification settings - Fork 17.8k
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
api: document the purpose of and review process for next.txt #32793
Comments
Updating the next.txt file affects the warnings that are printed at the end of an all.bash run. The go1.13.txt file should be reviewed to make sure that all new symbols and all changes are intentional, and to make sure that they are all referenced, at least implicitly, by some release note. |
next.txt = "in all.bash please don't tell me about this anymore; we know this is new." The copying of lines from next.txt to go1.13.txt is meant to be accompanied by an actual audit that we want to commit to that API. |
Created #32813 for the audit of go1.13.txt. |
next.txt went empty for most of the Go 1.13 cycle, so I think it's clear the all.bash warnings are not very effective. Why not make them errors instead? It would mean that a CL that adds new exported symbols also has to change next.txt at the same time, which seems like a good thing to me: it requires conscious acknowledgment of the new API surface. /cc @dmitshur |
Failing all.bash on missing symbols from next.txt would also avoid the current scenario (https://golang.org/cl/189458) of missing symbols going unnoticed until the release. We'd still have to check that everything moved over from next.txt to go1.13.txt, but that's an audit step appropriate for release time. |
Changing next.txt in the same CL as the actual changes makes it less likely that revert CLs will apply cleanly. |
@andybons sent me CL 183919 and I wasn't quite sure what to do with it:
api/next.txt
toapi/go1.13.txt
was not entirely trivial, but there were no visible failures on the build dashboard indicating any kind of skew (even for the symbols found innext.txt
that were subsequently removed from the API).go1.13.txt
goes through @golang/osp-team as part of the release process, but it's not obvious to me what kinds of problems we're supposed to look for.api/next.txt
were sent between folks very central in the project, with very minimal descriptions and almost no visible discussion on the review thread.api/next.txt
in the same CL as the API addition itself, but it's not obvious to me which CLs should do the API update simultaneously vs. saving or leaving the update for someone else to review later.api/README
doesn't clarify these points very much. Its description of the file is:We should expand the
README
file to more clearly describe the purpose and review process fornext.txt
.The text was updated successfully, but these errors were encountered: