Documentation updates for v0.5.0

CONTRIBUTING.md

@@ -9,33 +9,74 @@ We gratefully welcome improvements to documentation as well as to code.
 ## Community and Access
 
 Join [weaveworks-ignite@googlegroups.com](https://groups.google.com/forum/#!forum/weaveworks-ignite) for calendar invites to calls and edit access to community documents.
+You can ask questions and discuss features on the [#ignite](https://weave-community.slack.com/messages/ignite/) slack channel.
 
 We also hope to see you at our [developer meetings](https://docs.google.com/document/d/1fv8_WD6qXfvlIq7Bb5raCGyBvc42dNF-l8uaoZzoUYI/edit).
 
 ## Guidelines
 
-TODO: Add contributing guidelines here after we formalize them.
+If you have a feature suggestion or found a bug, head over to [GitHub issues](https://github.com/weaveworks/ignite/issues)
+and see if there's an open issue matching your description. If not feel free to open a new issue and add short description:
+ - In case of a bug, be sure to include the steps you performed and what Ignite responded so it's easy for others to reproduce
+ - If you have a feature suggestion, describe it in moderate detail and include some potential uses you see for the feature.
+   We prioritize the features to be implemented based on their usefulness/popularity. Of course if you want to start contributing
+   yourself, go ahead! We'll be more than happy to review your pull requests.
+
+The maintainers will add the correct labels/milestones to the issue for you.
+
+### Contributing your code
+
+The process to contribute code to Ignite is very straight forward.
+1. Go to the project on [GitHub](https://github.com/weaveworks/ignite) and click the `Fork` button in the top-right corner.
+   This will create your own copy of the repository in your personal account.
+1. Using standard `git` workflow, `clone` your fork, make your changes and then `commit` and `push` them to _your_ repository.
+1. Run `make autogen tidy`, then `commit` and `push` the changes. Just put `make autogen tidy` as the commit message.
+   This (re)generates any new/changed autogenerated content and cleans up the code's formatting.
+1. Go back to [GitHub](https://github.com/weaveworks/ignite), select `Pull requests` from the top bar and click
+   `New pull request` to the right. Select the `compare across forks` link. This will show repositories in addition to branches.
+1. From the `head repository` dropdown, select your forked repository. If you made a new branch, select it in the `compare` dropdown.
+   You should always target `weaveworks/ignite` and `master` as the base repository and branch.
+1. With your changes visible, click `Create pull request`. Give it a short, descriptive title and write a comment describing your changes.
+   Click `Create pull request`.
+
+That's it! Maintainers follow pull requests closely and will add the correct labels and milestones.
+After a maintainer's review small changes/improvements could be requested, don't worry, feedback can
+be easily addressed by performing the requested changes and doing a `commit` and `push`. Your new
+changes will automatically be added to the pull request. (Don't forget to add a new `make autogen tidy`
+commit if needed.)
+
+We also have Continuous Integration (CI) set up (powered by [CircleCI](https://circleci.com/)) that will build the code
+and verify it compiles and passes all tests successfully. If your changes didn't pass CI, you can click
+`Details` to go and check why it happened. To integrate your changes, we require CI to pass.
+
+If you have any questions or need help, don't hesitate to ask on our [mailing list](https://groups.google.com/forum/#!forum/weaveworks-ignite)
+or the [#ignite](https://weave-community.slack.com/messages/ignite/) slack channel. Have fun contributing!
 
 ## Make targets
 
-To compile the `ignite` binary, run
-```
-make
+To compile the `ignite`, `ignited` and `ignite-spawn` binaries, run
+```console
+make build-all-amd64
 ```
 
-To compile the `ignite-spawn` binary and build the Docker image, run
-```
-make ignite-spawn
-```
+`ignite`, `ignited` and `ignite-spawn` are also Make targets if you only need to build specific ones.
+Building `ignite-spawn` binary using either way also automatically packages it in its Docker container,
+and tags it as `weaveworks/ignite:dev` for development.
 
-Before submitting a PR, run
+To (re)generate autogenerated content in case your changes require it:
+```console
+make autogen
 ```
-make tidy
+
+Before submitting a PR:
+```console
+make autogen tidy
 ```
+This will clean up the code (run e.g. `gofmt`) in addition
+to making sure all autogenerated content is up to date.
 
 Other targets:
-- Install the `ignite` binary: `make install`
-- (Re)generate autogenerated content: `make autogen`
+- Install the `ignite` and `ignited` binaries: `make install`
 - Generate dependency graph: `make graph`
   - Depends on `sfdp` (usually found in the `graphviz` package)
 - Push the `weaveworks/ignite` Docker image: `make image-push`

README.md

@@ -1,6 +1,6 @@
 # Weave Ignite
 
-![Ignite Logo](docs/logo.png)
+<img width="300" align="right" alt="Ignite Logo" src="https://raw.githubusercontent.com/weaveworks/ignite/master/docs/logo.png">
 
 Weave Ignite is an open source Virtual Machine (VM) manager with a container UX and
 built-in GitOps management.
@@ -10,7 +10,7 @@ built-in GitOps management.
 - Works in a [GitOps](https://www.weave.works/blog/what-is-gitops-really) fashion and can
  manage VMs declaratively and automatically like Kubernetes and Terraform.
 
-Ignite is fast and secure because of Firecracker. This is an
+Ignite is fast and secure because of Firecracker. Firecracker is an
 [open source KVM implementation](https://firecracker-microvm.github.io/) from AWS that is
 optimised for [high security](https://github.com/firecracker-microvm/firecracker/blob/master/docs/design.md#threat-containment), isolation, speed and low resource consumption. AWS uses it as the foundation for their
 serverless offerings (AWS Lambda and Fargate) that need to load nearly instantly while also
@@ -27,17 +27,20 @@ execute **`ignite run`** instead of **`docker run`**.  There’s no need to use
 `.vdi`, `.vmdk`, or `.qcow2` images, just do a `docker build` from any base image you want
 (e.g. `ubuntu:18.04` from Docker Hub), and add your preferred contents.
 
-When you run your OCI image using `ignite run`, Firecracker will boot a new VM in c.125 milliseconds (!) for you, using a default 4.19 linux kernel. If you want to use some other kernel, just specify the `--kernel-image` flag, pointing to another OCI image containing a kernel at /boot/vmlinux, and optionally your preferred modules. Next, the kernel executes /sbin/init in the VM, and it all starts up.  After this, Ignite connects the VMs to any CNI network, integrating with e.g. Weave Net.
+When you run your OCI image using `ignite run`, Firecracker will boot a new VM in about 125 milliseconds (!) for you
+using a default 4.19 Linux kernel. If you want to use some other kernel, just specify the `--kernel-image` flag,
+pointing to another OCI image containing a kernel at `/boot/vmlinux`, and optionally your preferred modules. Next,
+the kernel executes `/sbin/init` in the VM, and it all starts up. After this, Ignite connects the VMs to any CNI network,
+integrating with e.g. Weave Net.
 
-Ignite is a declarative Firecracker microVM administration tool, like Docker manages
-runC containers.
-Ignite runs VM from OCI images, spins VMs up/down in lightning speed,
+Ignite is a declarative Firecracker microVM administration tool, similar to how Docker manages runC containers.
+Ignite runs VM from OCI images, spins VMs up/down at lightning speed,
 and can manage fleets of VMs efficiently using [GitOps](https://www.weave.works/technologies/gitops/).
 
 The idea is that Ignite makes Firecracker VMs look like Docker containers.
 Now we can deploy and manage full-blown VM systems just like e.g. Kubernetes workloads.
 The images used are OCI/Docker images, but instead of running them as containers, it executes
-as a real VM with a dedicated kernel and `/sbin/init` as PID 1.
+their contents as a real VM with a dedicated kernel and `/sbin/init` as PID 1.
 
 Networking is set up automatically, the VM gets the same IP as any docker container on the host would.
 
@@ -47,44 +50,45 @@ at most some seconds. With Ignite you can get started with Firecracker in no tim
 ## Use-cases
 
 With Ignite, Firecracker is now much more accessible for end users, which means the ecosystem
-can achieve the next level of momentum due to the easy onboarding path thanks to a docker-like UX.
+can achieve a next level of momentum due to the easy onboarding path thanks to the docker-like UX.
 
 Although Firecracker was designed with serverless workloads in mind, it can equally well boot a
 normal Linux OS, like Ubuntu, Debian or CentOS, running an init system like `systemd`.
 
 Having a super-fast way of spinning up a new VM, with a kernel of choice, running an init system
-like `systemd` allows to run system-level applications like the kubelet, which needs to “own” the full system.
+like `systemd` allows running system-level applications like the kubelet, which need to “own” the full system.
 
 Example use-cases:
 
-- Set up many secure VMs lightning fast. It's great for testing, CI and ephemeral workloads
+- Set up many secure VMs lightning fast. It's great for testing, CI and ephemeral workloads.
 - Launch and manage entire “app ready” stacks from Git because Ignite supports GitOps!
-- Run even legacy or special apps in lightweight VMs (eg for multi-tenancy, or using weird/edge kernels)
+- Run even legacy or special apps in lightweight VMs (eg for multi-tenancy, or using weird/edge kernels).
 
-And - potentially - we can run a cloud of VMs ‘anywhere’ using Kubernetes for orchestration, Ignite for virtualization, GitOps for management, and supporting cloud native tools and APIs.
+And - potentially - we can run a cloud of VMs ‘anywhere’ using Kubernetes for orchestration,
+Ignite for virtualization, GitOps for management, and supporting cloud native tools and APIs.
 
 ### Scope
 
-Ignite is different from Kata Containers or gVisor. They don’t let you run real VMs, but only wrap a container in new layer providing some kind of security boundary (or sandbox).
+Ignite is different from Kata Containers or gVisor. They don’t let you run real VMs, but only wrap a container in a VM layer providing some kind of security boundary (or sandbox).
 
 Ignite on the other hand lets you run a full-blown VM, easily and super-fast, but with the familiar container UX. This means you can “move down one layer” and start managing your fleet of VMs powering e.g. a Kubernetes cluster, but still package your VMs like containers.
 
 ## Installing
 
 Please check out the [Releases Page](https://github.com/weaveworks/ignite/releases).
 
-How to install Ignite is covered in [docs/installation.md](https://ignite.readthedocs.io/en/latest/installation.html).
+How to install Ignite is covered in [docs/installation.md](docs/installation.md) or on [Read the Docs](https://ignite.readthedocs.io/en/latest/installation.html).
 
 Guidance on Cloud Providers' instances that can run Ignite is covered in [docs/cloudprovider.md](docs/cloudprovider.md).
 
 ## Getting Started
 
-**WARNING**: In it's `v0.X` series, Ignite is in **alpha**, which means that it might change in backwards-incompatible ways.
+**WARNING:** In it's `v0.X` series, Ignite is in **alpha**, which means that it might change in backwards-incompatible ways.
 
 [![asciicast](https://asciinema.org/a/252221.svg)](https://asciinema.org/a/252221)
 
-Note: At the moment `ignite` needs root privileges on the host to operate,
-for certain specific operations (e.g. `mount`). This will change in the future.
+Note: At the moment `ignite` and `ignited` need root privileges on the host to operate
+due to certain operations (e.g. `mount`). This will change in the future.
 
 ```bash
 # Let's run the weaveworks/ignite-ubuntu docker image as a VM
@@ -126,21 +130,28 @@ For a walkthrough of how to use Ignite, go to [**docs/usage.md**](https://ignite
 
 ## Getting Started the GitOps way
 
-In Git you [declaratively store](https://ignite.readthedocs.io/en/latest/declarative-config.html) the desired state of a set of VMs you want to manage.
-`ignite gitops` reconciles the state from Git, and applies the desired changes as state is updated in the repo.
+Ignite is a “GitOps-first” project, GitOps is supported out of the box using the `ignited gitops` command.
+Previously this was integrated as `ignite gitops`, but this functionality has now moved to `ignited`,
+Ignite's upcoming daemon binary.
+
+In Git you declaratively store the desired state of a set of VMs you want to manage.
+`ignited gitops` reconciles the state from Git, and applies the desired changes as state is updated in the repo.
+It also commits and pushes any local changes/additions to the managed VMs back to the repository.
 
 This can then be automated, tracked for correctness, and managed at scale - [just some of the benefits of GitOps](https://www.weave.works/technologies/gitops/).
 
 The workflow is simply this:
 
-- Run `ignite gitops [repo]`, where repo points to your Git repo
-- Create a file with the VM specification, specifying how much vCPUs, RAM, disk, etc. you’d like from the VM
-- Run `git push` and see your VM start on the host
+ - Run `ignited gitops [repo]`, where repo is an **SSH url** to your Git repo
+ - Create a file with the VM specification, specifying how much vCPUs, RAM, disk, etc. you’d like for the VM
+ - Run `git push` and see your VM start on the host
 
-See it in action!
+See it in action! (Note: The screencast is from an older version which differs somewhat)
 
 [![asciicast](https://asciinema.org/a/255797.svg)](https://asciinema.org/a/255797)
 
+For the complete guide, see [docs/gitops.md](docs/gitops.md).
+
 ### Awesome Ignite
 
 Want to see how awesome Ignite is?
@@ -149,7 +160,7 @@ Take a look at the [awesome-ignite](https://ignite.readthedocs.io/en/latest/awes
 
 ### Documentation
 
-Please refer to the following documents:
+Please refer to the following documents powered by [Read the Docs](https://readthedocs.org/):
 
 - **[Documentation Page](https://ignite.readthedocs.io/)**
 - [Installing Ignite](https://ignite.readthedocs.io/en/latest/installation.html)
@@ -180,9 +191,9 @@ You can follow normal `docker build` patterns for customizing your VM's rootfs.
 
 A _kernel image_ is an OCI-compliant image containing a `/boot/vmlinux` (an uncompressed kernel)
 executable (can be a symlink). You can also put supporting kernel modules in `/lib/modules`
-if needed. You can match and mix any kernel and any base image.
+if needed. You can mix and match any kernel and any base image to create a VM.
 
-As the upstream `centos:7` and `ubuntu:18.04` images from Docker Hub doesn't
+As the upstream `centos:7` and `ubuntu:18.04` images from Docker Hub don't
 have all the utilities and packages you'd expect in a VM (e.g. an init system), we have packaged some
 reference base images and a sample kernel image to get started quickly.
 
@@ -196,6 +207,8 @@ but add `systemd`, `openssh`, and similar utilities.
 - [Amazon Linux 2 Dockerfile](images/amazonlinux/Dockerfile) (`weaveworks/ignite-amazonlinux`)
 - [The Firecracker Team's Alpine Image](images/alpine/Dockerfile) (`weaveworks/ignite-alpine`)
 
+These prebuilt images can be given to `ignite run` directly.
+
 #### Kernel Images
 
 - [Default Kernel Image](images/kernel/Dockerfile) (`weaveworks/ignite-kernel`)
@@ -204,8 +217,7 @@ but add `systemd`, `openssh`, and similar utilities.
 #### Tutorials
 
 - [Guide: Run a HA Kubernetes cluster with Ignite and kubeadm](images/kubeadm) (`weaveworks/ignite-kubeadm`)
-
-These prebuilt images can be given to `ignite run` directly.
+- [Guide: Run a set of Ignite VMs with Footloose](docs/footloose.md)
 
 ## Contributing