mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-19 05:12:41 +01:00
Add user documentation for managing large changesets
Summary: See task and P91, this just adapts my Discussion post to be more general. I'll follow up by linking to it from the Arcanist error message. Test Plan: Read the document. Reviewed By: jungejason Reviewers: jungejason, tuomaspelkonen, aran CC: aran, jungejason Differential Revision: 701
This commit is contained in:
parent
08ded289b7
commit
1bf8180d65
1 changed files with 54 additions and 0 deletions
54
src/docs/userguide/differential_large_changes.diviner
Normal file
54
src/docs/userguide/differential_large_changes.diviner
Normal file
|
@ -0,0 +1,54 @@
|
||||||
|
@title Differential User Guide: Large Changes
|
||||||
|
@group userguide
|
||||||
|
|
||||||
|
Dealing with huge changesets, and when **not** to use Differential.
|
||||||
|
|
||||||
|
= Overview =
|
||||||
|
|
||||||
|
When you want code review for a given changeset, Differential is not always the
|
||||||
|
right tool to use. The rule of thumb is that you should only send changes to
|
||||||
|
Differential if you expect humans to review the actual differences in the source
|
||||||
|
code from the web interface. This should cover the vast majority of changes but,
|
||||||
|
for example, you usually should //not// submit changes like these through
|
||||||
|
Differential:
|
||||||
|
|
||||||
|
- Committing an entire open source project to a private repo somewhere so
|
||||||
|
you can fork it or link against it.
|
||||||
|
- Committing an enormous text datafile, like a list of every English word or a
|
||||||
|
dump of a database.
|
||||||
|
- Making a trivial (e.g., find/replace) edit to 10,000 files.
|
||||||
|
|
||||||
|
You can still try submitting these kinds of changes, but you may encounter
|
||||||
|
problems getting them to work (database or connection timeouts, for example).
|
||||||
|
Differential is pretty fast and scalable, but at some point either it or the
|
||||||
|
browser will break down: you simply can't show nine million files on a webpage.
|
||||||
|
|
||||||
|
More importantly, in all these cases, the text of the changes won't be reviewed
|
||||||
|
by a human. The metadata associated with the change is what needs review (e.g.,
|
||||||
|
what are you checking in, where are you putting it, and why? Does the change
|
||||||
|
make sense? In the case of automated transformations, what script did you use?).
|
||||||
|
To get review for these types of changes, one of these strategies will usually
|
||||||
|
work better than trying to get the entire change into Differential:
|
||||||
|
|
||||||
|
- Send an email/AIM/IRC to your reviewer(s) like "Hey, I'm going to check in
|
||||||
|
the source for MySQL 9.3.1 to /full/path/to/whatever. The change is staged
|
||||||
|
in /home/whatever/path/somewhere if you want to take a look. Can I put your
|
||||||
|
name on the review?". This is best for straightforward changes. The reviewer
|
||||||
|
is not going to review MySQL's source itself, instead they are reviewing the
|
||||||
|
change metadata: which version are you checking in, why are you checking it
|
||||||
|
in, and where are you putting it?
|
||||||
|
- Create a Differential revision with only the metadata, like the script you
|
||||||
|
used to make automated changes or a text file explaining what you're doing,
|
||||||
|
and maybe a sample of some of the changes if they were automated. Include a
|
||||||
|
link to where the changes are staged so reviewers can look at the actual
|
||||||
|
changeset if they want to. This is best for more complicated changes, since
|
||||||
|
Differential can still be used for discussion and provide a permanent record
|
||||||
|
others can refer to.
|
||||||
|
|
||||||
|
In both cases, you won't be able to use "arc commit" or "arc amend" to actually
|
||||||
|
push the change. Just use "svn" or "git" and manually edit the commit message
|
||||||
|
instead. (It is normally sufficient to add a "Reviewed By: <username>" field.)
|
||||||
|
|
||||||
|
These kinds of changes are generally rare and don't have much in common, which
|
||||||
|
is why there's no explicit support for them in Differential. If you frequently
|
||||||
|
run into cases which Differential doesn't handle, let us know what they are.
|
Loading…
Reference in a new issue