Hi Denton, On Tue, 23 Jun 2020, Denton Liu wrote: > As of 2020-06-22, the name of git.git's integration branch has been > renamed from 'pu' to 'seen'.[0] Update git.git-specific documentation to > refer to the new branch name. In particular, update documents that refer > to the workflow and also "how to contribute"-type docs. > > There still remains other uses of 'pu' in the docs. In these cases, it > is generally used as an example and there isn't much value in updating > these examples since they aren't git.git specific. > > [0]: https://lore.kernel.org/git/xmqqimfid2l1.fsf@xxxxxxxxxxxxxxxxxxxxxx/ Whoops, I only saw this now. In the meantime I submitted what I hope is a more complete version of this patch. Sorry for duplicating your work, Dscho > > Signed-off-by: Denton Liu <liu.denton@xxxxxxxxx> > --- > Documentation/MyFirstContribution.txt | 4 +-- > Documentation/SubmittingPatches | 10 +++--- > Documentation/giteveryday.txt | 10 +++--- > Documentation/gitworkflows.txt | 12 +++---- > Documentation/howto/maintain-git.txt | 52 +++++++++++++-------------- > 5 files changed, 44 insertions(+), 44 deletions(-) > > diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt > index 427274df4d..d85c9b5143 100644 > --- a/Documentation/MyFirstContribution.txt > +++ b/Documentation/MyFirstContribution.txt > @@ -1179,8 +1179,8 @@ look at the section below this one for some context.) > [[after-approval]] > === After Review Approval > > -The Git project has four integration branches: `pu`, `next`, `master`, and > -`maint`. Your change will be placed into `pu` fairly early on by the maintainer > +The Git project has four integration branches: `seen`, `next`, `master`, and > +`maint`. Your change will be placed into `seen` fairly early on by the maintainer > while it is still in the review process; from there, when it is ready for wider > testing, it will be merged into `next`. Plenty of early testers use `next` and > may report issues. Eventually, changes in `next` will make it to `master`, > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index ecf9438cf0..291b61e262 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -19,7 +19,7 @@ change is relevant to. > base your work on the tip of the topic. > > * A new feature should be based on `master` in general. If the new > - feature depends on a topic that is in `pu`, but not in `master`, > + feature depends on a topic that is in `seen`, but not in `master`, > base your work on the tip of that topic. > > * Corrections and enhancements to a topic not yet in `master` should > @@ -28,7 +28,7 @@ change is relevant to. > into the series. > > * In the exceptional case that a new feature depends on several topics > - not in `master`, start working on `next` or `pu` privately and send > + not in `master`, start working on `next` or `seen` privately and send > out patches for discussion. Before the final merge, you may have to > wait until some of the dependent topics graduate to `master`, and > rebase your work. > @@ -38,7 +38,7 @@ change is relevant to. > these parts should be based on their trees. > > To find the tip of a topic branch, run `git log --first-parent > -master..pu` and look for the merge commit. The second parent of this > +master..seen` and look for the merge commit. The second parent of this > commit is the tip of the topic branch. > > [[separate-commits]] > @@ -424,7 +424,7 @@ help you find out who they are. > and cooked further and eventually graduates to `master`. > > In any time between the (2)-(3) cycle, the maintainer may pick it up > -from the list and queue it to `pu`, in order to make it easier for > +from the list and queue it to `seen`, in order to make it easier for > people play with it without having to pick up and apply the patch to > their trees themselves. > > @@ -435,7 +435,7 @@ their trees themselves. > master. `git pull --rebase` will automatically skip already-applied > patches, and will let you know. This works only if you rebase on top > of the branch in which your patch has been merged (i.e. it will not > - tell you if your patch is merged in pu if you rebase on top of > + tell you if your patch is merged in `seen` if you rebase on top of > master). > > * Read the Git mailing list, the maintainer regularly posts messages > diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt > index 1bd919f92b..faba2ef088 100644 > --- a/Documentation/giteveryday.txt > +++ b/Documentation/giteveryday.txt > @@ -278,13 +278,13 @@ $ git am -3 -i -s ./+to-apply <4> > $ compile/test > $ git switch -c hold/linus && git am -3 -i -s ./+hold-linus <5> > $ git switch topic/one && git rebase master <6> > -$ git switch -C pu next <7> > +$ git switch -C seen next <7> > $ git merge topic/one topic/two && git merge hold/linus <8> > $ git switch maint > $ git cherry-pick master~4 <9> > $ compile/test > $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> > -$ git fetch ko && for branch in master maint next pu <11> > +$ git fetch ko && for branch in master maint next seen <11> > do > git show-branch ko/$branch $branch <12> > done > @@ -294,14 +294,14 @@ $ git push --follow-tags ko <13> > <1> see what you were in the middle of doing, if anything. > <2> see which branches haven't been merged into `master` yet. > Likewise for any other integration branches e.g. `maint`, `next` > -and `pu` (potential updates). > +and `seen`. > <3> read mails, save ones that are applicable, and save others > that are not quite ready (other mail readers are available). > <4> apply them, interactively, with your sign-offs. > <5> create topic branch as needed and apply, again with sign-offs. > <6> rebase internal topic branch that has not been merged to the > master or exposed as a part of a stable branch. > -<7> restart `pu` every time from the next. > +<7> restart `seen` every time from the next. > <8> and bundle topic branches still cooking. > <9> backport a critical fix. > <10> create a signed tag. > @@ -323,7 +323,7 @@ repository at kernel.org, and looks like this: > fetch = refs/heads/*:refs/remotes/ko/* > push = refs/heads/master > push = refs/heads/next > - push = +refs/heads/pu > + push = +refs/heads/seen > push = refs/heads/maint > ------------ > > diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt > index abc0dc6bc7..ae38ff3fed 100644 > --- a/Documentation/gitworkflows.txt > +++ b/Documentation/gitworkflows.txt > @@ -85,7 +85,7 @@ As a given feature goes from experimental to stable, it also > > There is a fourth official branch that is used slightly differently: > > -* 'pu' (proposed updates) is an integration branch for things that are > +* 'seen' is an integration branch for things that are > not quite ready for inclusion yet (see "Integration Branches" > below). > > @@ -93,7 +93,7 @@ Each of the four branches is usually a direct descendant of the one > above it. > > Conceptually, the feature enters at an unstable branch (usually 'next' > -or 'pu'), and "graduates" to 'master' for the next release once it is > +or 'seen'), and "graduates" to 'master' for the next release once it is > considered stable enough. > > > @@ -207,7 +207,7 @@ If you make it (very) clear that this branch is going to be deleted > right after the testing, you can even publish this branch, for example > to give the testers a chance to work with it, or other developers a > chance to see if their in-progress work will be compatible. `git.git` > -has such an official throw-away integration branch called 'pu'. > +has such an official throw-away integration branch called 'seen'. > > > Branch management for a release > @@ -291,7 +291,7 @@ This will not happen if the content of the branches was verified as > described in the previous section. > > > -Branch management for next and pu after a feature release > +Branch management for next and seen after a feature release > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > After a feature release, the integration branch 'next' may optionally be > @@ -319,8 +319,8 @@ so. > If you do this, then you should make a public announcement indicating > that 'next' was rewound and rebuilt. > > -The same rewind and rebuild process may be followed for 'pu'. A public > -announcement is not necessary since 'pu' is a throw-away branch, as > +The same rewind and rebuild process may be followed for 'seen'. A public > +announcement is not necessary since 'seen' is a throw-away branch, as > described above. > > > diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt > index 73be8b49f8..a67130debb 100644 > --- a/Documentation/howto/maintain-git.txt > +++ b/Documentation/howto/maintain-git.txt > @@ -66,7 +66,7 @@ this mailing list after each feature release is made. > demonstrated to be regression free. New changes are tested > in 'next' before merged to 'master'. > > - - 'pu' branch is used to publish other proposed changes that do > + - 'seen' branch is used to publish other proposed changes that do > not yet pass the criteria set for 'next'. > > - The tips of 'master' and 'maint' branches will not be rewound to > @@ -76,7 +76,7 @@ this mailing list after each feature release is made. > of the cycle. > > - Usually 'master' contains all of 'maint' and 'next' contains all > - of 'master'. 'pu' contains all the topics merged to 'next', but > + of 'master'. 'seen' contains all the topics merged to 'next', but > is rebuilt directly on 'master'. > > - The tip of 'master' is meant to be more stable than any > @@ -229,12 +229,12 @@ by doing the following: > series?) > > - Prepare 'jch' branch, which is used to represent somewhere > - between 'master' and 'pu' and often is slightly ahead of 'next'. > + between 'master' and 'seen' and often is slightly ahead of 'next'. > > - $ Meta/Reintegrate master..pu >Meta/redo-jch.sh > + $ Meta/Reintegrate master..seen >Meta/redo-jch.sh > > The result is a script that lists topics to be merged in order to > - rebuild 'pu' as the input to Meta/Reintegrate script. Remove > + rebuild 'seen' as the input to Meta/Reintegrate script. Remove > later topics that should not be in 'jch' yet. Add a line that > consists of '### match next' before the name of the first topic > in the output that should be in 'jch' but not in 'next' yet. > @@ -291,29 +291,29 @@ by doing the following: > merged to 'master'. This may lose '### match next' marker; > add it again to the appropriate place when it happens. > > - - Rebuild 'pu'. > + - Rebuild 'seen'. > > - $ Meta/Reintegrate master..pu >Meta/redo-pu.sh > + $ Meta/Reintegrate master..seen >Meta/redo-seen.sh > > - Edit the result by adding new topics that are not still in 'pu' > + Edit the result by adding new topics that are not still in 'seen' > in the script. Then > > - $ git checkout -B pu jch > - $ sh Meta/redo-pu.sh > + $ git checkout -B seen jch > + $ sh Meta/redo-seen.sh > > - When all is well, clean up the redo-pu.sh script with > + When all is well, clean up the redo-seen.sh script with > > - $ sh Meta/redo-pu.sh -u > + $ sh Meta/redo-seen.sh -u > > Double check by running > > - $ git branch --no-merged pu > + $ git branch --no-merged seen > > to see there is no unexpected leftover topics. > > At this point, build-test the result for semantic conflicts, and > if there are, prepare an appropriate merge-fix first (see > - appendix), and rebuild the 'pu' branch from scratch, starting at > + appendix), and rebuild the 'seen' branch from scratch, starting at > the tip of 'jch'. > > - Update "What's cooking" message to review the updates to > @@ -323,14 +323,14 @@ by doing the following: > > $ Meta/cook > > - This script inspects the history between master..pu, finds tips > + This script inspects the history between master..seen, finds tips > of topic branches, compares what it found with the current > contents in Meta/whats-cooking.txt, and updates that file. > - Topics not listed in the file but are found in master..pu are > + Topics not listed in the file but are found in master..seen are > added to the "New topics" section, topics listed in the file that > - are no longer found in master..pu are moved to the "Graduated to > + are no longer found in master..seen are moved to the "Graduated to > master" section, and topics whose commits changed their states > - (e.g. used to be only in 'pu', now merged to 'next') are updated > + (e.g. used to be only in 'seen', now merged to 'next') are updated > with change markers "<<" and ">>". > > Look for lines enclosed in "<<" and ">>"; they hold contents from > @@ -360,7 +360,7 @@ Observations > Some observations to be made. > > * Each topic is tested individually, and also together with other > - topics cooking first in 'pu', then in 'jch' and then in 'next'. > + topics cooking first in 'seen', then in 'jch' and then in 'next'. > Until it matures, no part of it is merged to 'master'. > > * A topic already in 'next' can get fixes while still in > @@ -411,7 +411,7 @@ new use of the variable under its old name. When these two topics > are merged together, the reference to the variable newly added by > the latter topic will still use the old name in the result. > > -The Meta/Reintegrate script that is used by redo-jch and redo-pu > +The Meta/Reintegrate script that is used by redo-jch and redo-seen > scripts implements a crude but usable way to work this issue around. > When the script merges branch $X, it checks if "refs/merge-fix/$X" > exists, and if so, the effect of it is squashed into the result of > @@ -431,14 +431,14 @@ commit that can be squashed into a result of mechanical merge to > correct semantic conflicts. > > After finding that the result of merging branch "ai/topic" to an > -integration branch had such a semantic conflict, say pu~4, check the > +integration branch had such a semantic conflict, say seen~4, check the > problematic merge out on a detached HEAD, edit the working tree to > fix the semantic conflict, and make a separate commit to record the > fix-up: > > - $ git checkout pu~4 > + $ git checkout seen~4 > $ git show -s --pretty=%s ;# double check > - Merge branch 'ai/topic' to pu > + Merge branch 'ai/topic' to seen > $ edit > $ git commit -m 'merge-fix/ai/topic' -a > > @@ -450,9 +450,9 @@ result: > Then double check the result by asking Meta/Reintegrate to redo the > merge: > > - $ git checkout pu~5 ;# the parent of the problem merge > + $ git checkout seen~5 ;# the parent of the problem merge > $ echo ai/topic | Meta/Reintegrate > - $ git diff pu~4 > + $ git diff seen~4 > > This time, because you prepared refs/merge-fix/ai/topic, the > resulting merge should have been tweaked to include the fix for the > @@ -464,7 +464,7 @@ branch needs this merge-fix is because another branch merged earlier > to the integration branch changed the underlying assumption ai/topic > branch made (e.g. ai/topic branch added a site to refer to a > variable, while the other branch renamed that variable and adjusted > -existing use sites), and if you changed redo-jch (or redo-pu) script > +existing use sites), and if you changed redo-jch (or redo-seen) script > to merge ai/topic branch before the other branch, then the above > merge-fix should not be applied while merging ai/topic, but should > instead be applied while merging the other branch. You would need > -- > 2.27.0.307.g7979e895e7 > >
