Maintain Git

7/28/2019 Maintain Git

http://slidepdf.com/reader/full/maintain-git 1/5

From: Junio C Hamano <[email protected]>Date: Wed, 21 Nov 2007 16:32:55 -0800Subject: Addendum to "MaintNotes"Abstract: Imagine that git development is racing along as usual, when our friendlyneighborhood maintainer is struck down by a wayward bus. Out of thehordes of suckers (loyal developers), you have been tricked (chosen) tostep up as the new maintainer. This howto will show you "how to" do it.Content-type: text/asciidoc

How to maintain Git===================

The maintainer's git time is spent on three activities.

- Communication (60%)

Mailing list discussions on general design, fielding userquestions, diagnosing bug reports; reviewing, commenting on,suggesting alternatives to, and rejecting patches.

- Integration (30%)

Applying new patches from the contributors while spotting and

correcting minor mistakes, shuffling the integration andtesting branches, pushing the results out, cutting thereleases, and making announcements.

- Own development (10%)

Scratching my own itch and sending proposed patch series out.

The policy on Integration is informally mentioned in "A Notefrom the maintainer" message, which is periodically posted tothis mailing list after each feature release is made.

The policy.

- Feature releases are numbered as vX.Y.Z and are meant tocontain bugfixes and enhancements in any area, includingfunctionality, performance and usability, without regression.

- Maintenance releases are numbered as vX.Y.Z.W and are meantto contain only bugfixes for the corresponding vX.Y.Z featurerelease and earlier maintenance releases vX.Y.Z.V (V < W).

- 'master' branch is used to prepare for the next featurerelease. In other words, at some point, the tip of 'master'branch is tagged with vX.Y.Z.

- 'maint' branch is used to prepare for the next maintenancerelease. After the feature release vX.Y.Z is made, the tipof 'maint' branch is set to that release, and bugfixes willaccumulate on the branch, and at some point, the tip of thebranch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on.

- 'next' branch is used to publish changes (both enhancementsand fixes) that (1) have worthwhile goal, (2) are in a fairlygood shape suitable for everyday use, (3) but have not yetdemonstrated to be regression free. New changes are tested



in 'next' before merged to 'master'.

- 'pu' branch is used to publish other proposed changes that donot yet pass the criteria set for 'next'.

- The tips of 'master', 'maint' and 'next' branches will alwaysfast-forward, to allow people to build their owncustomization on top of them.

- Usually 'master' contains all of 'maint', 'next' contains allof 'master' and 'pu' contains all of 'next'.

- The tip of 'master' is meant to be more stable than anytagged releases, and the users are encouraged to follow it.

- The 'next' branch is where new action takes place, and theusers are encouraged to test it so that regressions and bugsare found before new topics are merged to 'master'.

A typical git day for the maintainer implements the above policyby doing the following:

- Scan mailing list and #git channel log. Respond with review

comments, suggestions etc. Kibitz. Collect potentiallyusable patches from the mailing list. Patches about a singletopic go to one mailbox (I read my mail in Gnus, and type\C-o to save/append messages in files in mbox format).

- Review the patches in the saved mailboxes. Edit proposed logmessage for typofixes and clarifications, and add Ackscollected from the list. Edit patch to incorporate "Oops,that should have been like this" fixes from the discussion.

- Classify the collected patches and handle 'master' and'maint' updates:

- Obviously correct fixes that pertain to the tip of 'maint'are directly applied to 'maint'.

- Obviously correct fixes that pertain to the tip of 'master'are directly applied to 'master'.

This step is done with "git am".

$ git checkout master ;# or "git checkout maint"$ git am -3 -s mailbox$ make test

- Merge downwards (maint->master):

$ git checkout master$ git merge maint$ make test

- Review the last issue of "What's cooking" message, review thetopics scheduled for merging upwards (topic->master andtopic->maint), and merge.

$ git checkout master ;# or "git checkout maint"



$ git merge ai/topic ;# or "git merge ai/maint-topic"$ git log -p ORIG_HEAD.. ;# final review$ git diff ORIG_HEAD.. ;# final review$ make test ;# final review$ git branch -d ai/topic ;# or "git branch -d ai/maint-topic"

- Merge downwards (maint->master) if needed:

$ git checkout master$ git merge maint$ make test

- Merge downwards (master->next) if needed:

$ git checkout next$ git merge master$ make test

- Handle the remaining patches:

- Anything unobvious that is applicable to 'master' (in otherwords, does not depend on anything that is still in 'next'and not in 'master') is applied to a new topic branch thatis forked from the tip of 'master'. This includes both

enhancements and unobvious fixes to 'master'. A topicbranch is named as ai/topic where "ai" is typicallyauthor's initial and "topic" is a descriptive name of thetopic (in other words, "what's the series is about").

- An unobvious fix meant for 'maint' is applied to a newtopic branch that is forked from the tip of 'maint'. Thetopic is named as ai/maint-topic.

- Changes that pertain to an existing topic are applied tothe branch, but:

- obviously correct ones are applied first;

- questionable ones are discarded or applied to near the tip;

- Replacement patches to an existing topic are accepted onlyfor commits not in 'next'.

The above except the "replacement" are all done with:

$ git am -3 -s mailbox

while patch replacement is often done by:

$ git format-patch ai/topic~$n..ai/topic ;# export existing

then replace some parts with the new patch, and reapplying:

$ git reset --hard ai/topic~$n$ git am -3 -s 000*.txt

The full test suite is always run for 'maint' and 'master'after patch application; for topic branches the tests are runas time permits.



- Update "What's cooking" message to review the updates toexisting topics, newly added topics and graduated topics.

This step is helped with Meta/cook script (where Meta/ containsa checkout of the 'todo' branch).

- Merge topics to 'next'. For each branch whose tip is notmerged to 'next', one of three things can happen:

- The commits are all next-worthy; merge the topic to next:

$ git checkout next$ git merge ai/topic ;# or "git merge ai/maint-topic"$ make test

- The new parts are of mixed quality, but earlier ones arenext-worthy; merge the early parts to next:

$ git checkout next$ git merge ai/topic~2 ;# the tip two are dubious$ make test

- Nothing is next-worthy; do not do anything.

- [** OBSOLETE **] Optionally rebase topics that do not have any commitin next yet, when they can take advantage of low-level frameworkchange that is merged to 'master' already.

$ git rebase master ai/topic

This step is helped with Meta/git-topic.perl script toidentify which topic is rebaseable. There also is apre-rebase hook to make sure that topics that are already in'next' are not rebased beyond the merged commit.

- [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'.

$ git checkout pu$ git reset --hard next$ git merge ai/topic ;# repeat for all remaining topics$ make test

This step is helped with Meta/PU script

- Push four integration branches to a private repository atk.org and run "make test" on all of them.

- Push four integration branches to /pub/scm/git/git.git atk.org. This triggers its post-update hook which:

(1) runs "git pull" in $HOME/git-doc/ repository to pull'master' just pushed out;

(2) runs "make doc" in $HOME/git-doc/, install the generateddocumentation in staging areas, which are separaterepositories that have html and man branches checkedout.

(3) runs "git commit" in the staging areas, and run "gitpush" back to /pub/scm/git/git.git/ to update the html



Documents

Maintain Git