jiri: First pass at fuller README.
This includes:
* brief description of what jiri does
* quickstart (it probably still needs more)
* gerrit workflow with "jiri cl"
* placeholders for other sections I want to add
If the README gets too long, we might want to break it up a bit, but for
now I just want to focus on getting the content written up.
Change-Id: I470d014f9290392d968b2bcabd113025eaf51a2c
diff --git a/README.md b/README.md
index 9528e78..9c27885 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,367 @@
# Jiri
-"Jiri integrates repositories intelligently"
+*"Jiri integrates repositories intelligently"*
-This repository implements the Jiri repository management tool.
+Jiri is a tool for multi-repo development.
+It supports:
+* syncing multiple local repos with upstream,
+* capturing the current state of all local repos in a "snapshot",
+* restoring local project state from a snapshot, and
+* facilitating sending change lists to [Gerrit][gerrit].
-For documentation, see http://godoc.org/v.io/jiri
+Jiri is open-source. See the contributor guidelines [here][contributing].
+## Quickstart
+
+This section explains how to get started with jiri.
+
+First we "bootstrap" jiri so that it can sync and build itself.
+
+Then we create and import a new manifest, which specifies how jiri should
+manage your projects.
+
+### Bootstrapping
+
+You can get jiri up-and-running in no time with the help of the [bootstrap
+script][bootstrap_jiri].
+
+First, pick a jiri root directory. All projects will be synced to
+subdirectories of the root.
+
+```
+export MY_ROOT=$HOME/myroot
+```
+
+Execute the `jiri_bootstrap` script, which will fetch and build the jiri tool,
+and initialize the root directory.
+
+```
+curl -s
+https://raw.githubusercontent.com/vanadium/go.jiri/master/scripts/bootstrap_jiri | bash -s "$MY_ROOT"
+```
+
+The `jiri` command line tool will be installed in
+`$MY_ROOT/.jiri_root/scripts/jiri`, so add that to your `PATH`.
+
+```
+export PATH="$MY_ROOT"/.jiri_root/scripts:$PATH
+```
+
+Next, use the `jiri import` command to import the "minimal" manifest from the
+vanadium manifest repo. This manifest includes only the projects needed to
+build the jiri tool itself.
+
+You can see the minimal manifest [here][minimal manifest]. For more
+information on manifests, read the [manifest docs][manifests].
+
+```
+cd "$MY_ROOT"
+jiri import minimal https://vanadium.googlesource.com/manifest
+```
+
+You should now have a file in the root directory called `.jiri_manifest`, which
+will contain a single import.
+
+Finally, run `jiri update`, which will sync all local projects to the revisions
+listed in the manifest (which in this case will be `HEAD`).
+
+
+```
+jiri update
+```
+
+You should now see the jiri project and dependencies in
+`$MY_ROOT/release/go/src/v.io`, and the vanadium manifest repo in
+`$MY_ROOT/manifest`.
+
+Running `jiri update` again will sync the local repos to the remotes, and
+rebuild the jiri tool.
+
+### Managing your projects with jiri
+
+Now that jiri is able to sync and build itself, we must tell it how to manage
+your projects.
+
+In order for jiri to manage a set of projects, those projects must be listed in
+a [manifest][manifests], and that manifest must be hosted in a git repo.
+
+If you already have a manifest hosted in a git repo, you can import that
+manifest the same way we imported the "minimal" manifest.
+
+For example, if your manifest is called "my_manifest" and is in a repo hosted
+at "https://github.com/my_org/manifests", then you can import that manifest
+as follows.
+
+```
+jiri import my_manifest https://github.com/my_org/manifests
+```
+
+The rest of this section walks through how to create a manifest from scratch,
+host it from a local git repo, and get jiri to manage it.
+
+Suppose that the project you want jiri to manage is the "Hello-World" repo
+located at https://github.com/Test-Octowin/Hello-World.
+
+First we'll create a new git repo to host the manifest we'll be writing.
+
+```
+mkdir -p /tmp/my_manifest_repo
+cd /tmp/my_manifest_repo
+git init
+```
+
+Next we'll create a manifest and commit it to the manifest repo.
+
+The manifest file will include the Hello-World repo as well as the manifest
+repo itself.
+
+```
+cat <<EOF > my_manifest
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+ <projects>
+ <project name="Hello-World"
+ remote="https://github.com/Test-Octowin/Hello-World"
+ path="helloworld"/>
+ <project name="manifest"
+ remote="/tmp/my_manifest_repo"
+ path="manifest"/>
+ </projects>
+</manifest>
+EOF
+
+git add my_manifest
+git commit -m "Add my_manifest."
+```
+
+This manifest contains a single project with the name "Hello-World" and the
+remote of the repo. The `path` attribute tells jiri to sync this repo inside
+the `helloworld` directory.
+
+Normally we would want to push this repo to some remote to make it accessible
+to other users who want to sync the same projects. For now, however, we'll
+just refer to the repo by its path in the local filesystem.
+
+Now we just need to import that new manifest and `jiri update`. Since we don't
+want the new manifest repo to conflict with the minimal manifest repo, we must
+pass the `-path` flag to the import statement.
+
+```
+cd "$MY_ROOT"
+jiri import -path="my_manifest_repo" my_manifest /tmp/my_manifest_repo
+jiri update
+```
+
+You should now see the Hello-World repo in `$MY_ROOT/helloworld`, and your
+manifest repo in `$MY_ROOT/my_manifest_repo`.
+
+## Command-line help
+
+The `jiri help` command will print help documentation about the `jiri` tool and
+its subcommands.
+
+For general documentation, including a list of subcommands, run `jiri help`.
+To find documentation about a specific topic or subcommand, run `jiri help
+<command>`.
+
+You can read all the command-line documentation in a single page here:
+http://godoc.org/v.io/jiri.
+
+## Filesystem
+
+TODO(nlacasse): There's a pretty good description of the filesystem layout at
+`jiri help filesystem`. Do we want to keep those docs there, or move them
+here? Maybe figure out a way to include them in both places but only have a
+single copy in source control.
+
+## Manifests<a name="manifests"></a>
+
+TODO(nlacasse): There's a brief description of manifests in `jiri help
+manifest`, but it needs a lot of improvement. Do we want to keep those docs
+there, or move them here? Maybe figure out a way to include them in both
+places but only have a single copy in source control.
+
+## Snapshots
+
+TODO(nlacasse): Write me.
+
+## Profiles
+
+TODO(nlacasse): Write me.
+
+## Gerrit CL workflow
+
+[Gerrit][gerrit] is a collaborative code-review tool used by many open source
+projects.
+
+One of the peculiarities of Gerrit is that it expects a changelist to be
+represented by a single commit. This constrains the way developers may use git
+to work on their changes. In particular, they must use the --amend flag with
+all but the first git commit operation and they need to use git rebase to sync
+their pending code change with the remote master. See Android's [repo command
+reference][android repo] or Go's [contributing instructions][go contrib] for
+examples of how intricate the workflow for resolving conflicts between the
+pending code change and the remote master is.
+
+The `jiri cl` command enables interaction with Gerrit without having to use
+such a complex and error-prone workflow. With `jiri cl`, users commit as often
+as they want on feature branches, and `jiri cl` handles the hard work of
+squashing all commits into a single commit and sending to Gerrit.
+
+The rest of this section describes common development operations using `jiri
+cl`. The term "CL" (short for "ChangeList") refers to a set of code changes
+uploaded for review.
+
+### Using feature branches
+
+The "master" branch of each local repository is reserved for tracking its
+remote counterpart. All development should take place on a non-master
+"feature" branch. Once the code is reviewed and approved, it is merged into
+the remote master via the Gerrit code review system. The change can then be
+merged into the local master branch with `jiri update`.
+
+TODO(nlacasse): dje is changing this behavior. The plan is that "master" will
+be the default reserved branch for each repo, but that can be overridden with
+the `localbranch` attribute in the manifest. Update this section once this
+change lands.
+
+### Creating a new CL
+
+1. Sync the master branch with the remote.
+```
+jiri update
+```
+2. Create a new feature branch for the CL.
+```
+jiri cl new <branch-name>
+```
+3. Make modifications to the project source code.
+4. Stage any changed files for commit.
+```
+git add <file1> <file2> ... <fileN>
+```
+5. Commit the changes.
+```
+git commit
+```
+6. Repeat steps 3-5 as necessary.
+
+### Syncing a CL with the remote
+
+1. Sync the master branch with the remote.
+```
+jiri update
+```
+2. Switch to the feature branch that corresponds to the CL under development.
+```
+git checkout <branch-name>
+```
+3. Sync the feature branch with the master branch.
+```
+jiri cl sync
+```
+4. If there are no conflicts between the master and the feature branch, the CL
+ has been successfully synced with the remote.
+5. If there are conflicts:
+ 1. Manually [resolve the conflicts][github resolve conflict].
+ 2. Stage any changed files for a commit.
+ ```
+ git add <file1> <file2> ... <fileN>
+ ```
+ 3. Commit the changes.
+ ```
+ git commit
+ ```
+
+### Requesting a code review
+
+1. Switch to the feature branch that corresponds to the CL under development.
+```
+git checkout <branch-name>
+```
+2. Upload the CL to Gerrit.
+```
+jiri cl mail
+```
+
+If the CL upload is successful, this will print the URL of the CL hosted on
+Gerrit. You can add reviewers and comments through the [Gerrit web UI][gerrit
+web ui] at that URL.
+
+Note that there are many useful flags for `jiri cl`. You can learn about them
+by running `jiri cl --help`.
+
+### Reviewing a CL
+
+1. Follow the link received in the code review email request.
+2. Use the [Gerrit web UI][gerrit web UI] to comment on the CL and click the
+ "Reply" button to submit comments, selecting the appropriate code-review
+ score.
+
+### Addressing review comments
+
+
+1. Switch to the feature branch that corresponds to the CL under development.
+```
+git checkout <branch-name>
+```
+2. Modify and commit the code as described above.
+3. Reply to each Gerrit comment and click the "Reply" button to send them.
+4. Send the updated CL to Gerrit.
+```
+jiri cl mail
+```
+
+### Submitting a CL
+1. Note that if the CL conflicts with any changes that have been submitted
+ since the last update of the CL, these conflicts need to be resolved before
+ the CL can be submitted. To do so, follow the steps in the "Syncing a CL
+ with the remote" section above and then upload the updated CL to Gerrit.
+```
+jiri cl mail
+```
+2. Once a CL meets the conditions for being submitted, it can be merged into
+ the remote master branch by clicking the "Submit" button on the Gerrit web
+ UI.
+3. Delete the local feature branch after the CL has been submitted to Gerrit.
+ 1. Sync the master branch to the laster version of the remote.
+ ```
+ jiri update
+ ```
+ 2. Safely delete the feature branch that corresponds to the CL.
+ ```
+ jiri cl cleanup <branch-name>
+ ```
+
+Note that deleting the feature branch with `git branch -d <branch-name>` won't
+work in general because the git history on the local feature branch differs
+from the history on the remote master. The local feature branch might have
+many small commits, while the remote will have the same changes squashed into a
+single commit. This difference in the history will prevent git from letting
+you do `git branch -d <branch-name>`. You *can* use `git branch -D
+<branch-name>`, but that can potentially cause you to lose work if the branch
+has not been merged into master yet. For this reason, we recommend using `jiri
+cl cleanup` to delete the feature branch safely.
+
+## FAQ
+TODO(nlacasse): Answer these questions.
+
+### Why not repo/gclient/etc?
+
+### Why can't I commit to my master branch?
+
+### How can I test changes to a manifest without pushing it upstream?
+
+### Why the name "jiri" ?
+"Jiří" is a very popular boys name in the Czech Republic.
+
+
+[android repo]: https://source.android.com/source/using-repo.html "Repo command reference"
+[bootstrap_jiri]: scripts/bootstrap_jiri "bootstrap_jiri"
+[contributing]: CONTRIBUTING.md "contributing"
+[gerrit]: https://code.google.com/p/gerrit/ "Gerrit code review"
+[gerrit web ui]: https://gerrit-review.googlesource.com/Documentation/user-review-ui.html "Gerrit review UI"
+[github resolve conflict]: https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/ "Resolving a merge conflict"
+[go contrib]: https://golang.org/doc/contribute.html#Code_review "Go Contribution Guidelines - Code Review"
+[manifests]: #manifests "manifests"
+[minimal manifest]: https://vanadium.googlesource.com/manifest/+/refs/heads/master/minimal "minimal manifest"
