No OneTemporary
Actions

Size

3 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/userguide/differential_large_changes.diviner b/src/docs/userguide/differential_large_changes.diviner
	new file mode 100644
	index 0000000000..d9a58237a3
	--- /dev/null
	+++ b/src/docs/userguide/differential_large_changes.diviner
	@@ -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.

File Metadata

Mime Type: text/x-diff
Expires: Sun, Jan 19, 16:10 (2 w, 6 d ago)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 1126341
Default Alt Text: (3 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions