Merge branch 'jc/how-to-maintain-updates'

Doc update.

* jc/how-to-maintain-updates:
  howto-maintain: update daily tasks
  howto-maintain: cover a whole development cycle

Documentation/howto/maintain-git.txt

@@ -37,22 +37,20 @@ The Policy
 
 The policy on Integration is informally mentioned in "A Note
 from the maintainer" message, which is periodically posted to
-this mailing list after each feature release is made.
+the mailing list after each feature release is made:
 
  - Feature releases are numbered as vX.Y.0 and are meant to
    contain bugfixes and enhancements in any area, including
    functionality, performance and usability, without regression.
 
- - One release cycle for a feature release is expected to last for
-   eight to ten weeks.
-
- - Maintenance releases are numbered as vX.Y.Z and are meant
+ - Maintenance releases are numbered as vX.Y.Z (0 < Z) and are meant
    to contain only bugfixes for the corresponding vX.Y.0 feature
    release and earlier maintenance releases vX.Y.W (W < Z).
 
- - 'master' branch is used to prepare for the next feature
+ - The 'master' branch is used to prepare for the next feature
    release. In other words, at some point, the tip of 'master'
-   branch is tagged with vX.Y.0.
+   branch is tagged as vX.(Y+1).0, when vX.Y.0 is the latest
+   feature release.
 
  - 'maint' branch is used to prepare for the next maintenance
    release.  After the feature release vX.Y.0 is made, the tip
@@ -63,11 +61,13 @@ this mailing list after each feature release is made.
  - 'next' branch is used to publish changes (both enhancements
    and fixes) that (1) have worthwhile goal, (2) are in a fairly
    good shape suitable for everyday use, (3) but have not yet
-   demonstrated to be regression free.  New changes are tested
-   in 'next' before merged to 'master'.
+   demonstrated to be regression free.  Reviews from contributors on
+   the mailing list help to make the determination.  After a topic
+   is merged to 'next', it is tested for at least 7 calendar days
+   before getting merged to 'master'.
 
  - 'seen' branch is used to publish other proposed changes that do
-   not yet pass the criteria set for 'next'.
+   not yet pass the criteria set for 'next' (see above).
 
  - The tips of 'master' and 'maint' branches will not be rewound to
    allow people to build their own customization on top of them.
@@ -86,6 +86,38 @@ this mailing list after each feature release is made.
    users are encouraged to test it so that regressions and bugs
    are found before new topics are merged to 'master'.
 
+ - When a problem is found in a topic in 'next', the topic is marked
+   not to be merged to 'master'.  Follow-up patches are discussed on
+   the mailing list and applied to the topic after being reviewed and
+   then the topic is merged (again) to 'next'.  After going through
+   the usual testing in 'next', the entire (fixed) topic is merged
+   to 'master'.
+
+ - One release cycle for a feature release is expected to last for
+   eight to ten weeks.  A few "release candidate" releases are
+   expected to be tagged about a week apart before the final
+   release, and a "preview" release is tagged about a week before
+   the first release candidate gets tagged.
+
+ - After the preview release is tagged, topics that were well
+   reviewed may be merged to 'master' before spending the usual 7
+   calendar days in 'next', with the expectation that any bugs in
+   them can be caught and fixed in the release candidates before
+   the final release.
+
+ - After the first release candidate is tagged, the contributors are
+   strongly encouraged to focus on finding and fixing new regressions
+   introduced during the cycle, over addressing old bugs and any new
+   features.  Topics stop getting merged down from 'next' to 'master',
+   and new topics stop getting merged to 'next'. Unless they are fixes
+   to new regressions in the cycle, that is.
+
+ - Soon after a feature release is made, the tip of 'maint' gets
+   fast-forwarded to point at the release.  Topics that have been
+   kept in 'next' are merged down to 'master' and a new development
+   cycle starts.
+
+
 Note that before v1.9.0 release, the version numbers used to be
 structured slightly differently.  vX.Y.Z were feature releases while
 vX.Y.Z.W were maintenance releases for vX.Y.Z.
@@ -179,12 +211,12 @@ by doing the following:
    The initial round is done with:
 
      $ git checkout ai/topic ;# or "git checkout -b ai/topic master"
-     $ git am -sc3 mailbox
+     $ git am -sc3 --whitespace=warn mailbox
 
    and replacing an existing topic with subsequent round is done with:
 
      $ git checkout master...ai/topic ;# try to reapply to the same base
-     $ git am -sc3 mailbox
+     $ git am -sc3 --whitespace=warn mailbox
 
    to prepare the new round on a detached HEAD, and then
 
@@ -209,39 +241,59 @@ by doing the following:
    (trivial typofixes etc. are often squashed directly into the
    patches that need fixing, without being applied as a separate
    "SQUASH???" commit), so that they can be removed easily as needed.
+   The expectation is that the original author will make corrections
+   in a reroll.
 
+ - By now, new topic branches are created and existing topic
+   branches are updated.  The integration branches 'next', 'jch',
+   and 'seen' need to be updated to contain them.
 
- - Merge maint to master as needed:
+ - If there are topics that have been merged to 'master' and should
+   be merged to 'maint', merge them to 'maint', and update the
+   release notes to the next maintenance release.
+
+ - Review the latest issue of "What's cooking" again.  Are topics
+   that have been sufficiently long in 'next' ready to be merged to
+   'master'?  Are topics we saw earlier and are in 'seen' now got
+   positive reviews and are ready to be merged to 'next'?
+
+ - If there are topics that have been cooking in 'next' long enough
+   and should be merged to 'master', merge them to 'master', and
+   update the release notes to the next feature release.
+
+ - If there were patches directly made on 'maint', merge 'maint' to
+   'master'; make sure that the result is what you want.
 
      $ git checkout master
-     $ git merge maint
+     $ git merge -m "Sync with 'maint'" --no-log maint
+     $ git log -p --first-parent ORIG_HEAD..
      $ make test
 
- - Merge master to next as needed:
-
-     $ git checkout next
-     $ git merge master
-     $ make test
-
- - Review the last issue of "What's cooking" again and see if topics
-   that are ready to be merged to 'next' are still in good shape
-   (e.g. has there any new issue identified on the list with the
-   series?)
-
- - Prepare 'jch' branch, which is used to represent somewhere
-   between 'master' and 'seen' and often is slightly ahead of 'next'.
+ - Prepare to update the 'jch' branch, which is used to represent
+   somewhere between 'master' and 'seen' and often is slightly ahead
+   of 'next', and the 'seen' branch, which is used to hold the rest.
 
      $ Meta/Reintegrate master..jch >Meta/redo-jch.sh
 
    The result is a script that lists topics to be merged in order to
-   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.
+   rebuild the current 'jch'.  Do the same for 'seen'.
 
- - Now we are ready to start merging topics to 'next'.  For each
-   branch whose tip is not merged to 'next', one of three things can
-   happen:
+ - Review the Meta/redo-jch.sh and Meta/redo-seen.sh scripts.  The
+   former should have a line '### match next'---the idea is that
+   merging the topics listed before the line on top of 'master'
+   should result in a tree identical to that of 'next'.
+
+ - As newly created topics are usually merged near the tip of
+   'seen', add them to the end of the Meta/redo-seen.sh script.
+   Among the topics that were in 'seen', there may be ones that
+   are not quite ready for 'next' but are getting there.  Move
+   them from Meta/redo-seen.sh to the end of Meta/redo-jch.sh.
+   The expectation is that you'd use 'jch' as your daily driver
+   as the first guinea pig, so you should choose carefully.
+
+ - Now we are ready to start rebuilding 'jch' and merging topics to
+   'next'.  For each branch whose tip is not merged to 'next', one
+   of three things can happen:
 
    - The commits are all next-worthy; merge the topic to next;
    - The new parts are of mixed quality, but earlier ones are
@@ -252,10 +304,12 @@ by doing the following:
    If a topic that was already in 'next' gained a patch, the script
    would list it as "ai/topic~1".  To include the new patch to the
    updated 'next', drop the "~1" part; to keep it excluded, do not
-   touch the line.  If a topic that was not in 'next' should be
-   merged to 'next', add it at the end of the list.  Then:
+   touch the line.
 
-     $ git checkout -B jch master
+   If a topic that was not in 'next' should be merged to 'next', add
+   it before the '### match next' line.  Then:
+
+     $ git checkout --detach master
      $ sh Meta/redo-jch.sh -c1
 
    to rebuild the 'jch' branch from scratch.  "-c1" tells the script
@@ -267,26 +321,29 @@ by doing the following:
    reference to the variable under its old name), in which case
    prepare an appropriate merge-fix first (see appendix), and
    rebuild the 'jch' branch from scratch, starting at the tip of
-   'master'.
+   'master', this time without using "-c1" to merge all topics.
 
-   Then do the same to 'next'
+   Then do the same to 'next'.
 
      $ git checkout next
      $ sh Meta/redo-jch.sh -c1 -e
 
    The "-e" option allows the merge message that comes from the
    history of the topic and the comments in the "What's cooking" to
-   be edited.  The resulting tree should match 'jch' as the same set
-   of topics are merged on 'master'; otherwise there is a mismerge.
-   Investigate why and do not proceed until the mismerge is found
-   and rectified.
+   be edited.  The resulting tree should match 'jch^{/^### match next'}'
+   as the same set of topics are merged on 'master'; otherwise there
+   is a mismerge. Investigate why and do not proceed until the mismerge
+   is found and rectified.
 
-     $ git diff jch next
+   If 'master' was updated before you started redoing 'next', then
 
-   Then build the rest of 'jch':
+     $ git diff 'jch^{/^### match next}' next
 
-     $ git checkout jch
-     $ sh Meta/redo-jch.sh
+   would show differences that went into 'master' (which 'jch' has,
+   but 'next' does not yet---often it is updates to the release
+   notes).  Merge 'master' back to 'next' if that is the case.
+
+     $ git merge -m "Sync with 'master'" --no-log master
 
    When all is well, clean up the redo-jch.sh script with
 
@@ -296,12 +353,7 @@ by doing the following:
    merged to 'master'.  This may lose '### match next' marker;
    add it again to the appropriate place when it happens.
 
- - Rebuild 'seen'.
-
-     $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh
-
-   Edit the result by adding new topics that are not still in 'seen'
-   in the script.  Then
+ - Rebuild 'seen' on top of 'jch'.
 
      $ git checkout -B seen jch
      $ sh Meta/redo-seen.sh
@@ -312,7 +364,7 @@ by doing the following:
 
    Double check by running
 
-     $ git branch --no-merged seen
+     $ git branch --no-merged seen '??/*'
 
    to see there is no unexpected leftover topics.