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: " 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.