Meta task purpose
The purpose of this task is to track the initial big dump of documentation for code-review in Phabricator. Documentation is, by its very nature, on-going.
This task will track the major documentation work needed to be completed in FY1516-Q4 (April - June 2016). Documentation work will continue after that but this task will probably be resolved (if we can get the basics documented).
Submitting a differential diff (D36)
$ git checkout master $ git checkout -b sync_flag $ vim scap/main.py $ git add scap/main.py $ git commit # write commit message... [sync_flag 94d1df5] abort sync if a file named sync.flag exists 1 file changed, 16 insertions(+) $ arc diff Linting... LINT OKAY No lint problems. Running unit tests... UNIT OKAY No unit test failures. SKIP STAGING No staging area is configured for this repository. Updating commit message... Created a new Differential revision: Revision URI: https://phabricator.wikimedia.org/D36 Included changes: M scap/main.py
Submitting a draft diff
This allows you to start differential revision that is still a work in progress and not yet ready for review. The only difference from regular revisions is that you add --plan-changes argument to arc diff, to signify that your revision is a work in progress/draft. This also allows you to submit a diff without explicitly naming reviewers. Optionally, you may name interested parties via the --cc argument as I have done here:
$ git checkout master $ git checkout -b wip $ vim some_new_thing.py $ git commit -a -m 'WIP: some cool new thing' $ arc diff --plan-changes -cc bd808
Landing a revision
The arc land command has been greatly improved by rARCa03c6079bb71: Make "arc land" great again. Now the workflow is absolutely straightforward and arc land will almost always do the right thing.
To land your own revision that exists in a local branch, use arc land [branch-name]. To land a revision that you don't have in a local branch, pass the differential revision as the argument to arc land [revision], e.g. arc land D123
Here is a complete real-world example, including the output from the arc land command:
$ cd /path/to/local-copy/ $ arc land T119200 TARGET Landing onto "master", the default target under git. REMOTE Using remote "origin", the default remote under git. FETCH Fetching origin/master... These commits will be landed: - 763b3e6 search the environment specific path if specified - 4d264e9 Change search_path arg to a list - b6f3207 Add a search_path for finding target hosts files Landing revision 'D59: Add a search_path for finding target hosts files'... Harbormaster is still building the active diff for this revision: BUILDING Build 279: test harbormaster with jenkins PASSED Build 278: arc lint + arc unit You can review build details here: Harbormaster URI: https://phabricator.wikimedia.org/B217 Land revision anyway, despite ongoing build? [y/N] y PUSHING Pushing changes to "origin/master". Counting objects: 5, done. Delta compression using up to 4 threads. Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 1.19 KiB | 0 bytes/s, done. Total 5 (delta 4), reused 0 (delta 0) To ssh://vcs@git-ssh.wikimedia.org/diffusion/MSCA/scap.git b62f945..578cce9 578cce980ac8f78ababaed18f34c65e31851ed29 -> master UPDATE Local "master" tracks target remote "origin/master", checking out and pulling changes. PULL Checking out and pulling "master". Cleaning up branch "T119200"... (Use `git checkout -b T119200 763b3e6026ebe032e25f0eaf50a938ca733a69bb` if you want it back.) DONE Landed changes.
