Page Menu
Home
Phorge
Search
Configure Global Search
Log In
Files
F2892931
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Award Token
Flag For Later
Advanced/Developer...
View Handle
View Hovercard
Size
13 KB
Referenced Files
None
Subscribers
None
View Options
diff --git a/src/docs/flavortext/recommendations_on_revision_control.diviner b/src/docs/flavortext/recommendations_on_revision_control.diviner
index acca93ee5c..66b7bfc9d9 100644
--- a/src/docs/flavortext/recommendations_on_revision_control.diviner
+++ b/src/docs/flavortext/recommendations_on_revision_control.diviner
@@ -1,92 +1,92 @@
@title Recommendations on Revision Control
@group flavortext
Project recommendations on how to organize revision control.
This document is purely advisory. Phabricator works with a variety of revision
control strategies, and diverging from the recommendations in this document
will not impact your ability to use it for code review and source management.
This is my (epriestley's) personal take on the issue and not necessarily
representative of the views of the Phabricator team as a whole.
= Overview =
There are a few ways to use SVN, a few ways to use Mercurial, and many many many
ways to use Git. Particularly with Git, every project does things differently,
and all these approaches are valid for small projects. When projects scale,
strategies which enforce **one idea is one commit** are better.
= One Idea is One Commit =
Choose a strategy where **one idea is one commit** in the authoritative
master/remote version of the repository. Specifically, this means that an entire
conceptual changeset ("add a foo widget") is represented in the remote as
exactly one commit (in some form), not a sequence of checkpoint commits.
- In SVN, this means don't ##commit## until after an idea has been completely
written. All reasonable SVN workflows naturally enforce this.
- In Git, this means squashing checkpoint commits as you go (with ##git commit
- --amend##) or before pushing (with ##git rebase -i## or `git merge
- --squash`), or having a strict policy where your master/trunk contains only
+ --amend##) or before pushing (with ##git rebase -i## or ##git merge
+ --squash##), or having a strict policy where your master/trunk contains only
merge commits and each is a merge between the old master and a branch which
represents a single idea. Although this preserves the checkpoint commits
along the branches, you can view master alone as a series of single-idea
commits.
- In Mercurial, you can use the "queues" extension before 2.2 or `--amend`
after Mercurial 2.2, or wait to commit until a change is complete (like
SVN), although the latter is not recommended. Without extensions, older
versions of Mercurial do not support liberal mutability doctrines (so you
can't ever combine checkpoint commits) and do not let you build a default
out of only merge commits, so it is not possible to have an authoritative
repository where one commit represents one idea in any real sense.
= Why This Matters =
A strategy where **one idea is one commit** has no real advantage over any other
strategy until your repository hits a velocity where it becomes critical. In
particular:
- Essentially all operations against the master/remote repository are about
ideas, not commits. When one idea is many commits, everything you do is more
complicated because you need to figure out which commits represent an idea
("the foo widget is broken, what do I need to revert?") or what idea is
ultimately represented by a commit ("commit af3291029 makes no sense, what
goal is this change trying to accomplish?").
- Release engineering is greatly simplified. Release engineers can pick or
drop ideas easily when each idea corresponds to one commit. When an idea
is several commits, it becomes easier to accidentally pick or drop half of
an idea and end up in a state which is virtually guaranteed to be wrong.
- Automated testing is greatly simplified. If each idea is one commit, you
can run automated tests against every commit and test failures indicate a
serious problem. If each idea is many commits, most of those commits
represent a known broken state of the codebase (e.g., a checkpoint with a
syntax error which was fixed in the next checkpoint, or with a
half-implemented idea).
- Understanding changes is greatly simplified. You can bisect to a break and
identify the entire idea trivially, without fishing forward and backward in
the log to identify the extents of the idea. And you can be confident in
what you need to revert to remove the entire idea.
- There is no clear value in having checkpoint commits (some of which are
guaranteed to be known broken versions of the repository) persist into the
remote. Consider a theoretical VCS which automatically creates a checkpoint
commit for every keystroke. This VCS would obviously be unusable. But many
checkpoint commits aren't much different, and conceptually represent some
relatively arbitrary point in the sequence of keystrokes that went into
writing a larger idea. Get rid of them or create an abstraction layer (merge
commits) which allows you to ignore them when you are trying to understand
the repository in terms of ideas (which is almost always).
All of these become problems only at scale. Facebook pushes dozens of ideas
every day and thousands on a weekly basis, and could not do this (at least, not
without more people or more errors) without choosing a repository strategy where
**one idea is one commit**.
= Next Steps =
Continue by:
- reading recommendations on structuring branches with
@{article:Recommendations on Branching}; or
- reading recommendations on structuring changes with
@{article:Writing Reviewable Code}.
diff --git a/src/docs/userguide/arcanist_diff.diviner b/src/docs/userguide/arcanist_diff.diviner
index fcfbdf778d..1fbea61f3c 100644
--- a/src/docs/userguide/arcanist_diff.diviner
+++ b/src/docs/userguide/arcanist_diff.diviner
@@ -1,196 +1,196 @@
@title Arcanist User Guide: arc diff
@group userguide
Guide to running `arc diff`, to send changes to Differential for review.
This article assumes you have `arc` installed and running; if not, see
@{article:Arcanist User Guide} for help getting it set up.
Before running `arc diff`, you should create a `.arcconfig` file. If someone
set things up for you, they may already have done this. See
@{article:Arcanist User Guide: Configuring a New Project} for instructions and
information.
= Overview =
While `arc` has a large number of commands that interface with various
Phabricator applications, the primary use of `arc` is to send changes for
review in Differential (for more information on Differential, see
@{article:Differential User Guide}). If you aren't familiar with Differential,
it may be instructive to read that article first to understand the big picture
of how the code review workflow works.
You send changes for review by running `arc diff`. The rest of this document
explains how to use `arc diff`, and how the entire review workflow operates for
different version control systems.
= Subversion =
In Subversion, `arc diff` sends the **uncommitted changes in the working copy**
for review.
To **create a revision** in SVN:
$ nano source_code.c # Make changes.
$ arc diff
This will prompt you for information about the revision. To later **update an
existing revision**, just do the same thing:
$ nano source_code.c # Make more changes.
$ arc diff
This time, `arc` will prompt you to update the revision. Once your revision has
been accepted, you can commit it like this:
$ arc commit
= Git =
In Git, `arc diff` sends **all commits in a range** for review. By default,
this range is:
`git merge-base origin/master HEAD`..HEAD
That's a fancy way of saying "all the commits on the current branch that
you haven't pushed yet". So, to **create a revision** in Git, run:
$ nano source_code.c # Make changes.
$ git commit # Commit changes.
$ arc diff # Creates a new revision out of ALL unpushed commits on
# this branch.
Since it uses **all** the commits on the branch, you can make several commits
before sending your changes for review if you prefer.
You can specify a different commit range instead by running:
$ arc diff <commit>
This means to use the range:
`git merge-base <commit> HEAD`..HEAD
However, this is a relatively advanced feature. The default is usually correct
if you aren't creating branches-on-branches, juggling remotes, etc.
To **update a revision**, just do the same thing:
$ nano source_code.c # Make more changes.
$ git commit # Commit them.
$ arc diff # This prompts you to update revision information.
When your revision has been accepted, you can usually push it like this:
$ arc land <branch> # Merges <branch> into master and pushes.
`arc land` makes some assumptions about your workflow which might not be
true. Consult the documentation before you use it. You should also look at
`arc amend`, which may fit your workflow better.
= Mercurial =
In Mercurial, `arc diff` sends **all commits in a range** for review. By
default, this range is changes between the first non-outgoing parent of any
revision in history and the directory state. This is a fancy way of saying
"every outgoing change since the last merge". It includes any uncommitted
changes in the working copy, although you will be prompted to include these.
To **create a revision** in Mercurial, run:
$ nano source_code.c # Make changes.
$ hg commit # Commit changes.
$ arc diff # Creates a new revision out of ALL outgoing commits
# on this branch since the last merge.
Since it uses **all** the outgoing commits on the branch, you can make several
commits before sending your changes for review if you prefer.
You can specify a different commit range instead by running:
$ arc diff <commit>
This means to use the range from that commit to the directory state. However,
this is an advanced feature and the default is usually correct.
To **update a revision**, just do the same thing:
$ nano source_code.c # Make changes.
$ hg commit # Commit changes.
$ arc diff # This prompts you to update revision information.
When your revision has been accepted, push it normally. (`arc` does not have
push integration in Mercurial because it can't force merges and thus can't
guarantee it will be able to do anything useful.)
= Pushing and Closing Revisions =
After changes have been accepted, you generally push them and close the
revision. `arc` has several workflows which help with this, by:
- squashing or merging changes from a feature branch into a master branch
(if relevant);
- formatting a good commit message with all the information from Differential;
and
- automatically closing the revision.
You don't need to use any of these workflows: you can just run `git push`,
`hg push` or `svn commit` and then manually close the revision from the web.
However, these workflows can make common development strategies more convenient,
and give you better commit messages in the repository. The workflows `arc`
supports are:
- `arc land`: Works in Git if you develop in feature branches. Does a merge
or squash-merge from your feature branch into some master branch, provides
a detailed commit message, pushes master, and then deletes your branch.
- `arc amend`: Works in Git if you can't use `arc land`. Amends HEAD with
a detailed commit message.
- `arc commit`: Works in Subversion. Runs `svn commit` with a detailed commit
message.
- `arc close-revision`: Works anywhere, closes a revision from the CLI
without going through the web UI.
You can use `arc help <command>` for detailed help with any of these.
Differential will make a guess about a next step on accepted revisions, but it
may not be the best next step for your workflow.
Phabricator will also automatically close revisions, if the changes are pushed
to a repository that is tracked in Diffusion. Specifically, it will close
revisions based on commit and tree hashes, and `Differential Revision`
identifiers in commit messages. (You can disable this feature by disabling
"Autoclose" in the Repository configuration.)
If you push to an untracked repository (or `arc` can't figure out that it's
-tracked), `arc land`, `arc amend` and `arc commit` will implicitly run `arc
-close-revision`.
+tracked), `arc land`, `arc amend` and `arc commit` will implicitly run
+`arc close-revision`.
= General Information =
This information is not unique to a specific version control system.
== Force Diff Only ==
You can create just a diff (rather than a revision) with `--preview` (or
`--only`, but this disables other features). You can later use it to create
or update a revision from the web UI.
== Other Diff Sources ==
You can create a diff out of an arbitrary patch file by using `--raw` and piping
it to stdin. In most cases this will only create a diff, not a revision. You
can use the web UI to create a revision from the diff, or update an existing
revision.
== Force Create / Update ==
`arc` uses information about the working copy (like the path, branch name, local
commit hashes, and local tree hashes, depending on which version control system
you are using) to figure out whether you intend to create or update a revision.
If it guesses incorrectly, you can force it to either create or update a
revision with:
$ arc diff --create # Force "create".
$ arc diff --update <revision> # Force "update".
-You can figure out what `arc` believes to be in the working copy with `arc
-which`.
+You can figure out what `arc` believes to be in the working copy with
+`arc which`.
File Metadata
Details
Attached
Mime Type
text/x-diff
Expires
Sun, Jan 19, 17:34 (1 w, 5 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1127016
Default Alt Text
(13 KB)
Attached To
Mode
rP Phorge
Attached
Detach File
Event Timeline
Log In to Comment