TEXT   50

maintain git

Guest on 12th May 2022 01:20:08 AM

  1. The maintainer's git time is spent on three activities.
  2.  
  3.  - Communication (60%)
  4.  
  5.    Mailing list discussions on general design, fielding user
  6.    questions, diagnosing bug reports; reviewing, commenting on,
  7.    suggesting alternatives to, and rejecting patches.
  8.  
  9.  - Integration (30%)
  10.  
  11.    Applying new patches from the contributors while spotting and
  12.    correcting minor mistakes, shuffling the integration and
  13.    testing branches, pushing the results out, cutting the
  14.    releases, and making announcements.
  15.  
  16.  - Own development (10%)
  17.  
  18.    Scratching my own itch and sending proposed patch series out.
  19.  
  20. The policy on Integration is informally mentioned in "A Note
  21. from the maintainer" message, which is periodically posted to
  22. this mailing list after each feature release is made.
  23.  
  24. The policy.
  25.  
  26.  - Feature releases are numbered as vX.Y.Z and are meant to
  27.    contain bugfixes and enhancements in any area, including
  28.    functionality, performance and usability, without regression.
  29.  
  30.  - Maintenance releases are numbered as vX.Y.Z.W and are meant
  31.    to contain only bugfixes for the corresponding vX.Y.Z feature
  32.    release and earlier maintenance releases vX.Y.Z.V (V < W).
  33.  
  34.  - 'master' branch is used to prepare for the next feature
  35.    release. In other words, at some point, the tip of 'master'
  36.    branch is tagged with vX.Y.Z.
  37.  
  38.  - 'maint' branch is used to prepare for the next maintenance
  39.    release.  After the feature release vX.Y.Z is made, the tip
  40.    of 'maint' branch is set to that release, and bugfixes will
  41.    accumulate on the branch, and at some point, the tip of the
  42.    branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on.
  43.  
  44.  - 'next' branch is used to publish changes (both enhancements
  45.    and fixes) that (1) have worthwhile goal, (2) are in a fairly
  46.    good shape suitable for everyday use, (3) but have not yet
  47.    demonstrated to be regression free.  New changes are tested
  48.    in 'next' before merged to 'master'.
  49.  
  50.  - 'pu' branch is used to publish other proposed changes that do
  51.    not yet pass the criteria set for 'next'.
  52.  
  53.  - The tips of 'master', 'maint' and 'next' branches will always
  54.    fast-forward, to allow people to build their own
  55.    customization on top of them.
  56.  
  57.  - Usually 'master' contains all of 'maint', 'next' contains all
  58.    of 'master' and 'pu' contains all of 'next'.
  59.  
  60.  - The tip of 'master' is meant to be more stable than any
  61.    tagged releases, and the users are encouraged to follow it.
  62.  
  63.  - The 'next' branch is where new action takes place, and the
  64.    users are encouraged to test it so that regressions and bugs
  65.    are found before new topics are merged to 'master'.
  66.  
  67.  
  68. A typical git day for the maintainer implements the above policy
  69. by doing the following:
  70.  
  71.  - Scan mailing list and #git channel log.  Respond with review
  72.    comments, suggestions etc.  Kibitz.  Collect potentially
  73.    usable patches from the mailing list.  Patches about a single
  74.    topic go to one mailbox (I read my mail in Gnus, and type
  75.    \C-o to save/append messages in files in mbox format).
  76.  
  77.  - Review the patches in the saved mailboxes.  Edit proposed log
  78.    message for typofixes and clarifications, and add Acks
  79.    collected from the list.  Edit patch to incorporate "Oops,
  80.    that should have been like this" fixes from the discussion.
  81.  
  82.  - Classify the collected patches and handle 'master' and
  83.    'maint' updates:
  84.  
  85.    - Obviously correct fixes that pertain to the tip of 'maint'
  86.      are directly applied to 'maint'.
  87.  
  88.    - Obviously correct fixes that pertain to the tip of 'master'
  89.      are directly applied to 'master'.
  90.  
  91.    This step is done with "git am".
  92.  
  93.      $ git checkout master    ;# or "git checkout maint"
  94.      $ git am -3 -s mailbox
  95.      $ make test
  96.  
  97.  - Merge downwards (maint->master):
  98.  
  99.      $ git checkout master
  100.      $ git merge maint
  101.      $ make test
  102.  
  103.  - Review the last issue of "What's cooking" message, review the
  104.    topics scheduled for merging upwards (topic->master and
  105.    topic->maint), and merge.
  106.  
  107.      $ git checkout master    ;# or "git checkout maint"
  108.      $ git merge ai/topic     ;# or "git merge ai/maint-topic"
  109.      $ git log -p ORIG_HEAD.. ;# final review
  110.      $ git diff ORIG_HEAD..   ;# final review
  111.      $ make test              ;# final review
  112.      $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic"
  113.  
  114.  - Merge downwards (maint->master) if needed:
  115.  
  116.      $ git checkout master
  117.      $ git merge maint
  118.      $ make test
  119.  
  120.  - Merge downwards (master->next) if needed:
  121.  
  122.      $ git checkout next
  123.      $ git merge master
  124.      $ make test
  125.  
  126.  - Handle the remaining patches:
  127.  
  128.    - Anything unobvious that is applicable to 'master' (in other
  129.      words, does not depend on anything that is still in 'next'
  130.      and not in 'master') is applied to a new topic branch that
  131.      is forked from the tip of 'master'.  This includes both
  132.      enhancements and unobvious fixes to 'master'.  A topic
  133.      branch is named as ai/topic where "ai" is typically
  134.      author's initial and "topic" is a descriptive name of the
  135.      topic (in other words, "what's the series is about").
  136.  
  137.    - An unobvious fix meant for 'maint' is applied to a new
  138.      topic branch that is forked from the tip of 'maint'.  The
  139.      topic is named as ai/maint-topic.
  140.  
  141.    - Changes that pertain to an existing topic are applied to
  142.      the branch, but:
  143.  
  144.      - obviously correct ones are applied first;
  145.  
  146.      - questionable ones are discarded or applied to near the tip;
  147.  
  148.    - Replacement patches to an existing topic are accepted only
  149.      for commits not in 'next'.
  150.  
  151.    The above except the "replacement" are all done with:
  152.  
  153.      $ git am -3 -s mailbox
  154.  
  155.    while patch replacement is often done by:
  156.  
  157.      $ git format-patch ai/topic~$n..ai/topic ;# export existing
  158.  
  159.    then replace some parts with the new patch, and reapplying:
  160.  
  161.      $ git reset --hard ai/topic~$n
  162.      $ git am -3 -s 000*.txt
  163.  
  164.    The full test suite is always run for 'maint' and 'master'
  165.    after patch application; for topic branches the tests are run
  166.    as time permits.
  167.  
  168.  - Update "What's cooking" message to review the updates to
  169.    existing topics, newly added topics and graduated topics.
  170.  
  171.    This step is helped with Meta/UWC script (where Meta/ contains
  172.    a checkout of the 'todo' branch).
  173.  
  174.  - Merge topics to 'next'.  For each branch whose tip is not
  175.    merged to 'next', one of three things can happen:
  176.  
  177.    - The commits are all next-worthy; merge the topic to next:
  178.  
  179.      $ git checkout next
  180.      $ git merge ai/topic     ;# or "git merge ai/maint-topic"
  181.      $ make test
  182.  
  183.    - The new parts are of mixed quality, but earlier ones are
  184.      next-worthy; merge the early parts to next:
  185.  
  186.      $ git checkout next
  187.      $ git merge ai/topic~2   ;# the tip two are dubious
  188.      $ make test
  189.  
  190.    - Nothing is next-worthy; do not do anything.
  191.  
  192.  - Rebase topics that do not have any commit in next yet.  This
  193.    step is optional but sometimes is worth doing when an old
  194.    series that is not in next can take advantage of low-level
  195.    framework change that is merged to 'master' already.
  196.  
  197.      $ git rebase master ai/topic
  198.  
  199.    This step is helped with Meta/git-topic.perl script to
  200.    identify which topic is rebaseable.  There also is a
  201.    pre-rebase hook to make sure that topics that are already in
  202.    'next' are not rebased beyond the merged commit.
  203.  
  204.  - Rebuild "pu" to merge the tips of topics not in 'next'.
  205.  
  206.      $ git checkout pu
  207.      $ git reset --hard next
  208.      $ git merge ai/topic     ;# repeat for all remaining topics
  209.      $ make test
  210.  
  211.    This step is helped with Meta/PU script
  212.  
  213.  - Push four integration branches to a private repository at
  214.    k.org and run "make test" on all of them.
  215.  
  216.  - Push four integration branches to /pub/scm/git/git.git at
  217.    k.org.  This triggers its post-update hook which:
  218.  
  219.     (1) runs "git pull" in $HOME/git-doc/ repository to pull
  220.         'master' just pushed out;
  221.  
  222.     (2) runs "make doc" in $HOME/git-doc/, install the generated
  223.         documentation in staging areas, which are separate
  224.         repositories that have html and man branches checked
  225.         out.
  226.  
  227.     (3) runs "git commit" in the staging areas, and run "git
  228.         push" back to /pub/scm/git/git.git/ to update the html
  229.         and man branches.
  230.  
  231.     (4) installs generated documentation to /pub/software/scm/git/docs/
  232.         to be viewed from http://www.kernel.org/
  233.  
  234.  - Fetch html and man branches back from k.org, and push four
  235.    integration branches and the two documentation branches to
  236.    repo.or.cz
  237.  
  238.  
  239. Some observations to be made.
  240.  
  241.  * Each topic is tested individually, and also together with
  242.    other topics cooking in 'next'.  Until it matures, none part
  243.    of it is merged to 'master'.
  244.  
  245.  * A topic already in 'next' can get fixes while still in
  246.    'next'.  Such a topic will have many merges to 'next' (in
  247.    other words, "git log --first-parent next" will show many
  248.    "Merge ai/topic to next" for the same topic.
  249.  
  250.  * An unobvious fix for 'maint' is cooked in 'next' and then
  251.    merged to 'master' to make extra sure it is Ok and then
  252.    merged to 'maint'.
  253.  
  254.  * Even when 'next' becomes empty (in other words, all topics
  255.    prove stable and are merged to 'master' and "git diff master
  256.    next" shows empty), it has tons of merge commits that will
  257.    never be in 'master'.
  258.  
  259.  * In principle, "git log --first-parent master..next" should
  260.    show nothing but merges (in practice, there are fixup commits
  261.    and reverts that are not merges).
  262.  
  263.  * Commits near the tip of a topic branch that are not in 'next'
  264.    are fair game to be discarded, replaced or rewritten.
  265.    Commits already merged to 'next' will not be.
  266.  
  267.  * Being in the 'next' branch is not a guarantee for a topic to
  268.    be included in the next feature release.  Being in the
  269.    'master' branch typically is.

Raw Paste


Login or Register to edit or fork this paste. It's free.