linux/Documentation/development-process/7.AdvancedTopics
<<
>>
Prefs
   17: ADVANCED TOPICS
   2
   3At this point, hopefully, you have a handle on how the development process
   4works.  There is still more to learn, however!  This section will cover a
   5number of topics which can be helpful for developers wanting to become a
   6regular part of the Linux kernel development process.
   7
   87.1: MANAGING PATCHES WITH GIT
   9
  10The use of distributed version control for the kernel began in early 2002,
  11when Linus first started playing with the proprietary BitKeeper
  12application.  While BitKeeper was controversial, the approach to software
  13version management it embodied most certainly was not.  Distributed version
  14control enabled an immediate acceleration of the kernel development
  15project.  In current times, there are several free alternatives to
  16BitKeeper.  For better or for worse, the kernel project has settled on git
  17as its tool of choice.
  18
  19Managing patches with git can make life much easier for the developer,
  20especially as the volume of those patches grows.  Git also has its rough
  21edges and poses certain hazards; it is a young and powerful tool which is
  22still being civilized by its developers.  This document will not attempt to
  23teach the reader how to use git; that would be sufficient material for a
  24long document in its own right.  Instead, the focus here will be on how git
  25fits into the kernel development process in particular.  Developers who
  26wish to come up to speed with git will find more information at:
  27
  28        http://git-scm.com/
  29
  30        http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
  31
  32and on various tutorials found on the web.
  33
  34The first order of business is to read the above sites and get a solid
  35understanding of how git works before trying to use it to make patches
  36available to others.  A git-using developer should be able to obtain a copy
  37of the mainline repository, explore the revision history, commit changes to
  38the tree, use branches, etc.  An understanding of git's tools for the
  39rewriting of history (such as rebase) is also useful.  Git comes with its
  40own terminology and concepts; a new user of git should know about refs,
  41remote branches, the index, fast-forward merges, pushes and pulls, detached
  42heads, etc.  It can all be a little intimidating at the outset, but the
  43concepts are not that hard to grasp with a bit of study.
  44
  45Using git to generate patches for submission by email can be a good
  46exercise while coming up to speed.
  47
  48When you are ready to start putting up git trees for others to look at, you
  49will, of course, need a server that can be pulled from.  Setting up such a
  50server with git-daemon is relatively straightforward if you have a system
  51which is accessible to the Internet.  Otherwise, free, public hosting sites
  52(Github, for example) are starting to appear on the net.  Established
  53developers can get an account on kernel.org, but those are not easy to come
  54by; see http://kernel.org/faq/ for more information.
  55
  56The normal git workflow involves the use of a lot of branches.  Each line
  57of development can be separated into a separate "topic branch" and
  58maintained independently.  Branches in git are cheap, there is no reason to
  59not make free use of them.  And, in any case, you should not do your
  60development in any branch which you intend to ask others to pull from.
  61Publicly-available branches should be created with care; merge in patches
  62from development branches when they are in complete form and ready to go -
  63not before.
  64
  65Git provides some powerful tools which can allow you to rewrite your
  66development history.  An inconvenient patch (one which breaks bisection,
  67say, or which has some other sort of obvious bug) can be fixed in place or
  68made to disappear from the history entirely.  A patch series can be
  69rewritten as if it had been written on top of today's mainline, even though
  70you have been working on it for months.  Changes can be transparently
  71shifted from one branch to another.  And so on.  Judicious use of git's
  72ability to revise history can help in the creation of clean patch sets with
  73fewer problems.
  74
  75Excessive use of this capability can lead to other problems, though, beyond
  76a simple obsession for the creation of the perfect project history.
  77Rewriting history will rewrite the changes contained in that history,
  78turning a tested (hopefully) kernel tree into an untested one.  But, beyond
  79that, developers cannot easily collaborate if they do not have a shared
  80view of the project history; if you rewrite history which other developers
  81have pulled into their repositories, you will make life much more difficult
  82for those developers.  So a simple rule of thumb applies here: history
  83which has been exported to others should generally be seen as immutable
  84thereafter.
  85
  86So, once you push a set of changes to your publicly-available server, those
  87changes should not be rewritten.  Git will attempt to enforce this rule if
  88you try to push changes which do not result in a fast-forward merge
  89(i.e. changes which do not share the same history).  It is possible to
  90override this check, and there may be times when it is necessary to rewrite
  91an exported tree.  Moving changesets between trees to avoid conflicts in
  92linux-next is one example.  But such actions should be rare.  This is one
  93of the reasons why development should be done in private branches (which
  94can be rewritten if necessary) and only moved into public branches when
  95it's in a reasonably advanced state.
  96
  97As the mainline (or other tree upon which a set of changes is based)
  98advances, it is tempting to merge with that tree to stay on the leading
  99edge.  For a private branch, rebasing can be an easy way to keep up with
 100another tree, but rebasing is not an option once a tree is exported to the
 101world.  Once that happens, a full merge must be done.  Merging occasionally
 102makes good sense, but overly frequent merges can clutter the history
 103needlessly.  Suggested technique in this case is to merge infrequently, and
 104generally only at specific release points (such as a mainline -rc
 105release).  If you are nervous about specific changes, you can always
 106perform test merges in a private branch.  The git "rerere" tool can be
 107useful in such situations; it remembers how merge conflicts were resolved
 108so that you don't have to do the same work twice.
 109
 110One of the biggest recurring complaints about tools like git is this: the
 111mass movement of patches from one repository to another makes it easy to
 112slip in ill-advised changes which go into the mainline below the review
 113radar.  Kernel developers tend to get unhappy when they see that kind of
 114thing happening; putting up a git tree with unreviewed or off-topic patches
 115can affect your ability to get trees pulled in the future.  Quoting Linus:
 116
 117        You can send mpatches f, but r moneit54">2r4.i#L79" id= href="D Ia>
      , neey tonelow that yoonelow that yonmore pogck, anI , neey td be aba>
      intor musa>this *e wiabo*in tain vpting tgogy and chee, etory
       kiividualed chanon ba hace.

  22http:lwn.net/Apartedl/224135o22
masw the revint proces  P mosahen
linux-nece.
maintato thc mt roen
y;t have tadds; re&quoF hr:re"inliny tw th79" ids if it has bees reyrted en

Whe, quesnrning 54">,ld be more tgivwan alw the leAdvtlp informati:ny wware
yr a tree ,ow thae branch t54">,ly any amit changey will resulr from tre
ch.  The gi, quesn-54">2, coy and can be helpfue in thiregardns; iy wion




mthe readgey wilt certainlobrojecy to puttint This section thit &quoa.Advanca>






especialll for a nek Kerna>
y;wepullernee nervous abouquesnronagincodes-ne in publio -
which has bee="poized br thosn thih mors e rievanes.  evecodesrewritted a>

releadue in thig ph?re"y will alwame worr better tio/.statinre&quom tre

fromiffeurrene pointe orevirs.  come
wte spaanes.O othert willofocuprimarially ny wnothee the chan  simpopmenca>
thinl for the kerne fos not.Y set othea>

perfodvanee, ur-spaan ABIic changes, ette


ThorigiioniLXRto softwa d br the LXRt, counili74lin.no">lxt@a>lin.no74 lxt.a>lin.noit kiallh"poized be Redpn ing Le p AS74 /bodyiv /l.htiv