Update docs
A lot of the documentation was completely outdated. There's less total
documentation now because a lot of what we do has gotten a lot simpler
and so requires less documentation.
Change-Id: I6c862472aef167fcd3d5e877a1c83715b3caeb20
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7447085
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# Introduction
+This is FRC Team 971's main code repository. There are `README*` files throughout the source tree documenting specifics for their respective folders.
+
+## Access to the code
+The main central location for our code is our [Gerrit](https://www.gerritcodereview.com/) server at https://robotics.mvla.net/gerrit. To get a copy of the code on your computer to work with, follow these steps:
+ 1. Contact Michael Schuh to get an SVN account.
+ 2. Go to Gerrit and create an account.
+ 3. Contact Brian Silverman with your SVN username to get access to the code in Gerrit.
+ 4. Go to [the 971-Robot-Code project in Gerrit](https://robotics.mvla.net/gerrit/#/admin/projects/971-Robot-Code) and run the command.
+ Running the `clone with commit-msg hook` command will save you trouble later.
+
+To learn more about git, see git(1) (`man git` or [git(1)](http://manpages.debian.net/cgi-bin/man.cgi?query=git>) (especially the NOTES section).
+
+## Code reviews
+We want all code to at least have a second person look over it before it gets merged into the `master` branch. Gerrit has [extensive documentation on starting reviews](https://robotics.mvla.net/gerrit/Documentation/user-upload.html). TL;DR: `git push origin HEAD:refs/for/master` and then click on the link.
+[git-review](http://manpages.debian.org/cgi-bin/man.cgi?query=git-review) can make the upload process simpler.
+
+## Building the code
+The currently supported operating system for building the code is amd64 Debian Jessie. It is likely to work on any x86\_64 GNU/Linux system, but that's not at all well-tested.
+
+We use [Bazel](http://bazel.io) to build the code. Bazel has [extensive](http://bazel.io/docs/build-ref.html) [docs](http://bazel.io/docs/build-encyclopedia.html) and does a nice job with fast, correct increment rebuilds.
+
+Steps to set up a computer to build the code:
+ 0. Set up the required APT repositories:
+ Download
+ [frc971.list](http://robotics.mvla.net/files/frc971/packages/frc971.list)
+ and
+ [llvm.org.list](http://robotics.mvla.net/files/frc971/packages/llvm.org.list)
+ and put them in `/etc/apt/sources.list.d/`.
+ 1. Install the required packages:
+```console
+apt-get install python bazel ruby clang-format-3.5 clang-3.6
+```
+ 2. Allow Bazel's sandboxing to work
+
+Some useful Bazel commands:
+ * Build and test everything (on the host system):
+```console
+bazel test //...
+```
+ This currently requires adding `-//{y2014,y2015,bot3,frc971}/wpilib/... -//aos/externals:wpilib` to avoid trying to build WPILib to work.
+ * Build the code for a specific robot:
+```console
+bazel build --cpu=roborio --compilation_mode=opt //y2015/...
+```
+ * Download code to a robot:
+```console
+bazel run --cpu=roborio --compilation_mode=opt //y2015/prime:download roboRIO-971.local
+```
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 89fa70a..0000000
--- a/README.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-This is the README.txt file for git. If you are looking at this file and you got it through SVN, somebody messed up and it should be fixed.
-
-This is team 971's code. We only keep code in this git repository. For details about how we use git, see doc/gitsetup.txt.
-
-You can get to this code in a web browser through <https://robotics.mvla.net/git971> (useful for ie sending links). You have to use your SVN credentials to log in there.
-
-aos/README.txt has some more details about what's where.
diff --git a/doc/building-the-code.txt b/doc/building-the-code.txt
deleted file mode 100644
index c2676d1..0000000
--- a/doc/building-the-code.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-This file contains instructions on how to set up a computer to build the code.
-
-[OS]
-Most of these instructions assume 64 bit Debian Wheezy.
-
-[Install Packages]
-First, you have to download and follow the directions in
- <http://robotics.mvla.net/files/frc971/packages/frc971.list>.
-Then, run `apt-get install python3`.
-The build script will tell you what other packages to install when you run it.
- It's pretty smart about not checking for things it doesn't need, so you might
- want to build 'deploy all' to see everything it wants.
- You will have to accept the
- "WARNING: The following packages cannot be authenticated!" warning for
- various packages downloaded from our package repository.
- This works for amd64 Wheezy, no guarantees or support for anything else.
-
-[Running Locally]
-If you want to be able to run the realtime code on your development machine
- without just disabling the realtime part (set the AOS_NO_REALTIME environment
- variable), follow the directions in //aos/config/aos.conf.
-If you want to run the clang or gcc_4.8 amd64 code, add /opt/clang-3.5/lib64/ to
- LD_LIBRARY_PATH. Using the system gcc-compiled versions should just work.
-
-[Compiling and Downloading]
-Run //frc971/*/build.sh.
- Give it clean, tests, or deploy as a first argument to do something other
- than just build.
- Each action (build (the default), clean, tests, or deploy) has a different
- default set of versions of the code it builds. You can change those by
- passing another argument. Some popular ones are 'all' (build everything),
- 'clang-amd64-none' (the most basic one for local testing), and
- 'gcc_frc-arm-nodebug' (the one that gets downloaded). See its --help for
- more details.
-
-[Communicating with the cRIO]
-Use netconsole (in the amd64 outputs directories) to communicate directly with
- the cRIO.
-Use "reboot" from within netconsole.sh will reboot the cRIO. ^C will
- stop the netconsole program. "version" will tell you the the
- VxWorks and WIND versions and "help" will give you a list of VxWorks
- commands that you can use.
-Make sure your computer is on the right subnet first.
diff --git a/doc/codereview-directions.txt b/doc/codereview-directions.txt
deleted file mode 100644
index 4610c95..0000000
--- a/doc/codereview-directions.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-This file has some general information about how 971 does code reviews.
-
-We use Rietveld (<https://code.google.com/p/rietveld>) running in an app engine
- app of ours. It is at <http://971code.appspot.com/>.
-
-[General Procedure]
-We try to code review all code before it gets checked in to svn. Code reviews
- are also sometimes useful for getting feedback about documentation etc.
-First, somebody starts a code review and sends out emails to people asking them
- to look. Then, other people look at it and make suggestions (in the form of
- comments). The person who started the review (the owner of it) looks at the
- comments and responds to them and/or changes their code and uploads new
- versions for everybody to look at. Once all of the reviewers approve the code,
- the owner checks it in and closes the code review (issue).
-
-[Reviewing]
-This is the section for people who have received emails about reviewing code
- should look.
-The email that you receive will have a link to the issue (like
- <http://971code.appspot.com/82001/>). Click on it to go to the issue page.
- The most useful form of diff are the "Side-by-side diffs". Click the "View"
- link in that column next to each file to look at it. After the first set of
- comments, the "Delta from patch set" links are also helpful to see what got
- changed so that you don't have to look at everything again. While looking at
- a diff, double-click on any line of code to leave a comment there. You can
- also reply to existing comments. The web interface sometimes hides comments
- right after you create/edit them. Refresh the page to fix that (don't just do
- it again, or you'll end up with 2 identical comments). Once you are done
- looking at all of the files and making comments, click the
- "Publish+Mail Comments" link (at the top of each diff or on the left of the
- main issue page) to send out your comments. You can also put general notes in
- the "Message" box. If you think that it looks good, then put "LGTM" at the top
- of the message. The owner of the code review will keep looking at your
- comments, making changes, and sending out more messages until it's finished.
-
-[Starting a Review]
-To begin, log in to <http://971code.appspot.com/> then click the "Create Issue"
- link. Download the "upload.py" script and use that, not the web form, for
- uploading a diff. (The web form has too many problems and is unusable with
- git.) The script will find svn, git, or hg diffs in your current directory. If
- you want the diff to cover back to an earlier change number, use the --rev
- arg.
-
- You don't need to give it a -s (--server) arg since the right default server
- address is in the script. You can give it a -e (--email) arg with your gmail
- address or let it ask you. (If you use 2-factor login for gmail, which I
- recommend, you'll need to create an application-specific password instead of
- using your regular password + OTP code.)
-
- After it uploads, you can review the diffs on the web page. You can change
- code and upload another diff. When ready, use the web UI to send the code
- review email. Don't delete the old diffs; they are helpful for reviewers to
- figure out what changed.
-
-For more information about using Rietveld, see
- <https://code.google.com/p/rietveld/wiki/CodeReviewHelp>.
diff --git a/doc/frc971.conf b/doc/frc971.conf
new file mode 100644
index 0000000..743ca69
--- /dev/null
+++ b/doc/frc971.conf
@@ -0,0 +1,5 @@
+# Put this file in /etc/sysctl.d/ to enable Bazel's sandboxing on Debian
+# kernels.
+# Run `sudo sysctl --system` to load it without rebooting.
+
+kernel.unprivileged_userns_clone = 1
diff --git a/doc/git-setup.txt b/doc/git-setup.txt
deleted file mode 100644
index 6fc52b5..0000000
--- a/doc/git-setup.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-Some of us are using git for managing quickly changing code. This file has
-notes for setting that up.
-
-[Cloning]
-`git clone \
- ssh://USERNAME@robotics.mvla.net/www/https/git/frc971/SOMEBODY/2014.git`
- where USERNAME is your login on the server and SOMEBODY is whoever's git
- repo you want to clone
-If you don't have a login on the server, then cloning
- https://robotics.mvla.net/git/frc971/somebody/2014.git instead should work
- (with your SVN username and password). However, that form of URL is read-
- only. In order for this to work, you have to either set the environment
- variable GIT_SSL_NO_VERIFY to 1 or set the git option http.sslverify to false.
- If you get an error like the one below, install a newer version of git.
- Unable to find 8fcd87533b76ca5b4b83fb6031ddf0de5e03eb57 under https://robotics.mvla.net/git/frc971/brian/2013.git
- Cannot obtain needed object 8fcd87533b76ca5b4b83fb6031ddf0de5e03eb57
- error: Fetch failed.
- I get this error sometimes with version 1.7.2.5 but not with version 1.7.10.4.
-
-[Adding Other People's Repositories]
-`git remote add SOMEBODY \
- ssh://USERNAME@robotics.mvla.net/www/https/git/frc971/SOMEBODY/2014.git`
- where USERNAME is your login on the server and SOMEBODY is another person's
- git repository
-The https:// URL discussed above in [Cloning] will work too.
-
-[Working with Other People's Repositories]
-`git fetch SOMEBODY` will pull their changes, and then you can rebase on top of
- them, merge them in, etc.
-`git push --mirror` will push all of your local branches so that everybody else
- can see them. (This is the default if the configuration option remote.<remote>.mirror is set.)
- However, you can not do that with an https:// URL.
-
-[Synchronizing with SVN]
-Somebody should occasionally copy all of the files from git (bbb_cape,
- frc971, and aos) into svn.
-
-[Server Setup]
-You need a place to store your files. You will need an adminstrator to
- create a folder for you in /www/https/git/frc971 (on the server) with the
- correct permissions and group.
-
-[Repository Setup]
-To create a git repository on the server,
- `git init --bare 2014.git` in your folder (ie
- "/www/https/git/frc971/USERNAME/"), `cd 2014.git`,
- `git config --local gc.pruneExpire never`, `rm -r objects/`, and then
- `ln -s /www/https/git/frc971/objects/2014 objects`. That will set you up
- with a repository in the standard location and make it so all of the objects
- in it won't be duplicated with the identical ones in everybody else's
- repositories.
-In order for https:// access to work, you have to make sure to rename
- .git/hooks/post-update.sample to .git/hooks/post-update (and then run
- `git update-server-info` if you're not going to push immediately).
-
-To learn more about git, see git(1) (`man git` or
- <http://manpages.debian.net/cgi-bin/man.cgi?query=git>) (especially the NOTES
- section).