From fdbe28b964ca7608307f131eb928ec9bc076fa23 Mon Sep 17 00:00:00 2001
From: Jonathan Lebon <jlebon@redhat.com>
Date: Tue, 21 Jun 2016 12:30:47 -0400
Subject: [PATCH] docs: fix README.md and add HACKING.md

Add a HACKING.md document detailing how to get started and test
rpm-ostree using the vagrant box.

Fix the CONTRIBUTING.md link and add a link to HACKING.md in README.md.

Closes: #344
Approved by: cgwalters
---
 HACKING.md  | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md   |  7 ++++++-
 Vagrantfile |  2 +-
 3 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 HACKING.md

diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 00000000..b5673a96
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,53 @@
+The easiest way to get started hacking on `rpm-ostree` is to
+use the vagrant machine. This is also the set up used for
+our integration tests.
+
+One-time setup
+==============
+
+Starting the vagrant machine is as easy as:
+
+```
+host$ vagrant up
+host$ vagrant ssh
+```
+
+The VM for now uses the official
+[centos/atomic-host](https://atlas.hashicorp.com/centos/boxes/atomic-host)
+box. However, because `rpm-ostree` is tightly coupled with
+other projects such as `ostree` and `libhif`, the code in
+`HEAD` may require a more recent version than available in
+the latest official box.
+
+For this reason, you may want to rebase the VM onto the
+[CentOS Atomic Continuous](https://ci.centos.org/job/atomic-rdgo-centos7/)
+stream, which will contain the latest `HEAD` versions of
+these dependencies (normally within the hour). To rebase,
+simply do:
+
+```
+vm$ sudo rpm-ostree rebase centos-atomic-continuous:centos-atomic-host/7/x86_64/devel/continuous
+vm$ sudo systemctl reboot
+```
+
+If you need to test your code with custom `ostree` or
+`libhif` builds, you have no choice for now other than
+making your own tree (and yum repo for use by the build
+container). We're hoping to improve this workflow soon.
+
+Hacking
+=======
+
+The `make vmbuild` command will automatically sync the
+current files to the VM, build `rpm-ostree` and install it
+into a new deployment, and finally reboot the VM to use it.
+
+For convenience, the `make vmshell` command does the same
+but additionally places you in a shell, ready to test your
+changes.
+
+Testing
+=======
+
+The `make vmcheck` command performs the same task as `make
+vmbuild`, but additionally starts the integration testsuite.
diff --git a/README.md b/README.md
index c31b8da9..4ad6c007 100644
--- a/README.md
+++ b/README.md
@@ -68,8 +68,13 @@ More documentation
 
 New! See the docs online at [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/ )
 
+Hacking
+-------
+
+See [Hacking](HACKING.md).
+
 Contributing
 ------------
 
-See [Contributing](CONTRIBUTING.md).
+See [Contributing](docs/CONTRIBUTING.md).
 
diff --git a/Vagrantfile b/Vagrantfile
index 00701f54..fb19e8a4 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -1,6 +1,6 @@
 # vi: set ft=ruby :
 
-# See `tests/vmcheck/README.md` for more information on this.
+# See `HACKING.md` for more information on this.
 
 Vagrant.configure(2) do |config|
     config.vm.box = "centos/atomic-host"