From 85e456ec22382634ba3ef72294a5261db682292a Mon Sep 17 00:00:00 2001 From: Kris Giesing <kgiesing@google.com> Date: Wed, 15 Feb 2017 18:32:59 -0800 Subject: [PATCH] Update getting started instructions * Move source control documentation to docs repository * Add instructions for referencing issues in commit messages * Split out monolithic jiri doc into smaller docs Change-Id: I171e933aaac70b758ea9f290fb4339a5f0532a4a --- CONTRIBUTING.md | 83 ++++++++++++++++++++++++++++++++++++++++--- building_toolchain.md | 24 +++++++++++++ getting_source.md | 47 ++++++++++++++++++++++++ getting_started.md | 14 +++++--- 4 files changed, 158 insertions(+), 10 deletions(-) create mode 100644 building_toolchain.md create mode 100644 getting_source.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 81e293807a0..8b5ea52f0bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,82 @@ -This repository accepts contributions using Gerrit. +Contributing Changes +==================== -Instructions for using Gerrit: +Fuchsia manages commits through Gerrit at +https://fuchsia-review.googlesource.com. Not all projects accept patches; +please see the CONTRIBUTING.md document in individual projects for +details. - * https://gerrit-review.googlesource.com/Documentation/ +## Submitting changes -Before we can land your change, you need to sign the Google CLA: +To submit a patch to Fuchsia, you may first need to generate a cookie to +authenticate you to Gerrit. To generate a cookie, log into Gerrit and click +the "Generate Password" link at the top of https://fuchsia.googlesource.com. +Then, copy the generated text and execute it in a terminal. + +Once authenticated, follow these steps to submit a patch to Fuchsia: + +``` +# create a new branch +git checkout -b branch_name + +# write some awesome stuff, commit to branch_name +vim some_file ... +git commit ... + +# upload the patch to gerrit +git push origin HEAD:refs/for/master + +# once the change is landed, clean up the branch +git branch -d branch_name +``` + +See the Gerrit documentation for more detail: +[https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change](https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change) + +## [Googlers only] Issue actions + +Commit messages may reference issue IDs in Fuchsia's +(issue tracker)[https://fuchsia.atlassian.net/]; such references will become +links in the Gerrit UI. Issue actions may also be specified, for example to +automatically close an issue when a commit is landed: + +BUG-123 #done + +`done` is the most common issue action, though any workflow action can be +indicated in this way. + +*Note*: Fuchsia's issue tracker is not open to external contributors at this +time. + +## Cross-repo changes + +Changes in two separate repos will be automatically tracked for you by Gerrit +if you use the same topic. + +``` +# make and commit the first change, upload it with topic 'add_feature_foo' +cd fuchsia/bin/fortune +git checkout -b new add_feature_foo +vim foo_related_files ... +git commit ... +git push origin HEAD:refs/for/master%topic=add_feature_foo + +# make and commit the second change in another repository +cd fuchsia/build +git checkout -b new add_feature_foo +vim more_foo_related_files ... +git commit ... +git push origin HEAD:refs/for/master%topic=add_feature_foo + +# after the changes are reviewed, approved and submitted, cleanup the local branch +cd fuchsia/bin/fortune +git branch -d add_feature_foo + +cd fuchsia/build +git branch -d add_feature_foo +``` + +Multipart changes are tracked in gerrit via topics, will be tested together, +and can be landed in Gerrit at the same time with `Submit Whole Topic`. Topics +can be edited via the web UI. - * https://cla.developers.google.com/ diff --git a/building_toolchain.md b/building_toolchain.md new file mode 100644 index 00000000000..284aa18c993 --- /dev/null +++ b/building_toolchain.md @@ -0,0 +1,24 @@ +# Building the toolchain + +To build Fuchsia's toolchain, you can use the `scripts/build-toolchain.sh` +script as follows: + +``` +./scripts/build-toolchain.sh +``` + +After the build finishes, you can find the built toolchain in `out/toolchain`. + +Please note that build can take significant amount of time, especially on +slower machines. + +When the sources get updated, you can rebuild the toolchain using the following +commands: + +```sh +# update +jiri update + +# cleanup the artifacts from the previous build and rebuild the toolchain +./scripts/build-toolchain.sh -c +``` diff --git a/getting_source.md b/getting_source.md new file mode 100644 index 00000000000..289834466c0 --- /dev/null +++ b/getting_source.md @@ -0,0 +1,47 @@ +Fuchsia Source +============== + +Fuchsia uses the `jiri` tool to manage git repositories +[https://fuchsia.googlesource.com/jiri](https://fuchsia.googlesource.com/jiri). +This tool manages a set of repositories specified by a manifest. + +## Prerequisites + +On Ubuntu: + + * `sudo apt-get install golang git-all build-essential curl unzip` + +On Mac: + + * Install Xcode Command Line Tools + * `brew install golang` + +## Creating a new checkout + +The bootstrap procedure requires that you have Go 1.6 or newer and Git +installed and on your PATH. To create a new Fuchsia checkout in a directory +called `fuchsia` run the following commands. The `fuchsia` directory should +not exist before running these steps. + +``` +curl -s https://raw.githubusercontent.com/fuchsia-mirror/jiri/master/scripts/bootstrap_jiri | bash -s fuchsia +cd fuchsia +export PATH=`pwd`/.jiri_root/bin:$PATH +jiri import fuchsia https://fuchsia.googlesource.com/manifest +jiri update +``` + +### Working without altering your PATH + +If you don't like having to mangle your environment variables, and you want +`jiri` to "just work" depending on your current working directory, there's a +shim for that. + +``` +sudo cp .jiri_root/bin/jiri /usr/local/bin +sudo chmod 755 /usr/local/bin/jiri +``` + +That script is just a wrapper around the real `jiri`. It crawls your parent +directory structure until it finds a `.jiri_root` directory, then executes the +`jiri` it finds there. diff --git a/getting_started.md b/getting_started.md index cf132399893..8edddba045f 100644 --- a/getting_started.md +++ b/getting_started.md @@ -1,4 +1,5 @@ -# Fuchsia +Fuchsia +============ Pink + Purple == Fuchsia (a new Operating System) @@ -8,8 +9,8 @@ Fuchsia. ## Getting the source Get the Fuchsia source by following these two steps and then return to this document: - * [Install prerequisites](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Prerequisites) for Jiri, a tool for multi-repo development. - * [Create a new checkout](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Creating-a-new-checkout) of Fuchsia. + * [Install prerequisites](https://fuchsia.googlesource.com/docs/+/HEAD/getting_source.md#Prerequisites) for Jiri, a tool for multi-repo development. + * [Create a new checkout](https://fuchsia.googlesource.com/docs/+/HEAD/getting_source.md#Creating-a-new-checkout) of Fuchsia. ## Prerequisites @@ -169,14 +170,17 @@ frun -N -u $FUCHSIA_SCRIPTS_DIR/start-dhcp-server.sh The `-u` flag runs a script that sets up a local DHCP server and NAT to configure the IPv4 interface and routing. -### Run Fuchsia on hardware +### Running Fuchsia on hardware * [Acer Switch Alpha 12](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/acer12.md) * [Intel NUC](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/nuc.md) * [Raspberry Pi 3](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/rpi3.md) +## Contributing changes +* See [contributing.md](https://fuchsia.googlesource.com/docs/+/HEAD/contributing.md). + ## Additional helpful documents * [Fuchsia documentation](https://fuchsia.googlesource.com/docs) hub. -* [Contributing changes](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Submitting-changes). +* Building [Fuchsia's toolchain](https://fuchsia.googlesource.com/docs/+/HEAD/building_toolchain.md) * More about the [build commands](build_system.md) called under-the-hood by `fbuild`. -- GitLab