-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
Change the way API changes are documented #15158
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
Conversation
What about #14589 (the towncrier PR)? It looks like the necessary upstream PR (twisted/towncrier#157) already went in. |
@dstanby I think that your proposed workflow would work fine. In terms of writing style, that should be fixed prior to merging the PR. Might be worth adding a note to the reviewing guidelines about that. |
@anntzer even though it's merged, it's not released and I don't think towncrier is the most actively developed project. I think (w/ no real evidence) adding to the same file that already has some changes will help first-timers see what kind of thing to write, and will hopefully reduce the amount of copy editing that needs to be done at release time. |
We used to do it that way and it caused so many re-bases that we moved to the many files. |
Could we do a mixture of both? Split between four categories, but keep several files with a strong naming conventions and structure, and "simply" do a cat before the release? |
We discussed this on the weekly call, and there was support for exactly the approach in this PR. Yes, there will be some rebasing needed, but usually new developers who would be burdened by rebasing are not doing deprecations etc which get hit heavily. And splitting into four categories lessens the chance of conflicts. |
Woops, not sure why I closed this! |
@dstansby What is the state of this? I think we want to get this enabled for 3.3 ASAP! |
Thanks for the nudge, I think modulo getting the docs to build this is almost there. Will try and sort this out in the next couple of days! |
a4456eb
to
2228c36
Compare
2228c36
to
654a4a5
Compare
f6adc10
to
63abf89
Compare
I think this is ready now! |
Doc builds complain:
|
63abf89
to
6d03309
Compare
6d03309
to
445e2c5
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess this will need follow up PRs from folks who have already committed API changes?
There's four API change notes on master so far. I can handle these in one go. Open PRs will need an update by the respective author. |
Given the pace at which we are making API changes in each new release, the current method of one change/file, then merge just before a release isn't very sustainable. I did the
3.1.0
changes, and I've given up doing the3.2.0
changes because it's a very boring task. Problems are:So I am proposing a change such that all API changes are added at the time the change is made to one of four files (categories up for discussion here):
I know this will involve merge conflicts along the way, but I honestly think it's a hit worth taking to make the ultimate task of putting together a coherent API changes page easier.