[Summary view] [Print] [Text view]

   1  @title Differential User Guide: Large Changes
   2  @group userguide
   3  
   4  Dealing with huge changesets, and when **not** to use Differential.
   5  
   6  = Overview =
   7  
   8  When you want code review for a given changeset, Differential is not always the
   9  right tool to use. The rule of thumb is that you should only send changes to
  10  Differential if you expect humans to review the actual differences in the source
  11  code from the web interface. This should cover the vast majority of changes but,
  12  for example, you usually should //not// submit changes like these through
  13  Differential:
  14  
  15    - Committing an entire open source project to a private repo somewhere so
  16      you can fork it or link against it.
  17    - Committing an enormous text datafile, like a list of every English word or a
  18      dump of a database.
  19    - Making a trivial (e.g., find/replace or codemod) edit to 10,000 files.
  20  
  21  You can still try submitting these kinds of changes, but you may encounter
  22  problems getting them to work (database or connection timeouts, for example).
  23  Differential is pretty fast and scalable, but at some point either it or the
  24  browser will break down: you simply can't show nine million files on a webpage.
  25  
  26  More importantly, in all these cases, the text of the changes won't be reviewed
  27  by a human. The metadata associated with the change is what needs review (e.g.,
  28  what are you checking in, where are you putting it, and why? Does the change
  29  make sense? In the case of automated transformations, what script did you use?).
  30  To get review for these types of changes, one of these strategies will usually
  31  work better than trying to get the entire change into Differential:
  32  
  33    - Send an email/AIM/IRC to your reviewer(s) like "Hey, I'm going to check in
  34      the source for MySQL 9.3.1 to /full/path/to/whatever. The change is staged
  35      in /home/whatever/path/somewhere if you want to take a look. Can I put your
  36      name on the review?". This is best for straightforward changes. The reviewer
  37      is not going to review MySQL's source itself, instead they are reviewing the
  38      change metadata: which version are you checking in, why are you checking it
  39      in, and where are you putting it? You won't be able to use "arc commit" or
  40      "arc amend" to actually push the change. Just use "svn" or "git" and
  41      manually edit the commit message instead. (It is normally sufficient to add
  42      a "Reviewed By: <username>" field.)
  43    - Create a Differential revision with only the metadata, like the script you
  44      used to make automated changes or a text file explaining what you're doing,
  45      and maybe a sample of some of the changes if they were automated. Include a
  46      link to where the changes are staged so reviewers can look at the actual
  47      changeset if they want to. This is best for more complicated changes, since
  48      Differential can still be used for discussion and provide a permanent record
  49      others can refer to. Once the revision is accepted, amend your local commit
  50      (e.g. by `git commit --amend`) with the real change and push as usual.
  51  
  52  These kinds of changes are generally rare and don't have much in common, which
  53  is why there's no explicit support for them in Differential. If you frequently
  54  run into cases which Differential doesn't handle, let us know what they are.