Add contributing and history chapters to the guide

3 files changed, 173 insertions, 6 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index f084e6f..316df7f 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -62,6 +62,4 @@ include::why.asciidoc[Why erlang.mk?]
 
 include::history.asciidoc[Short history]
 
-include::architecture.asciidoc[Architecture]
-
 include::contributing.asciidoc[Contributing]
diff --git a/doc/src/guide/contributing.asciidoc b/doc/src/guide/contributing.asciidoc
index e712788..b4d31fb 100644
--- a/doc/src/guide/contributing.asciidoc
+++ b/doc/src/guide/contributing.asciidoc
@@ -1,5 +1,114 @@
 == Contributing
 
-// @todo Write it.
+You are welcome and encouraged to contribute.
 
-Placeholder chapter.
+This is how.
+
+=== Priorities
+
+From the most important to the least important:
+
+* Bugs
+* Package issues/additions
+* Refactoring
+* Features
+
+=== Bugs
+
+If you have found a bug, you should open a ticket. Include
+everything relevant including the command you used, output,
+a link to the code that triggers the issue, why you think
+this is a bug, etc.
+
+If you think you have found a bug but you are not sure, you
+should open a ticket as previously explained.
+
+If you have found a bug and you need it to be solved RIGHT
+NOW, open a ticket as previously explained.
+
+Once you have opened a ticket, be patient, try to answer
+questions in a timely manner and confirm that the bug was
+indeed fixed when it is.
+
+If you can't be patient, either try to solve the bug and
+contribute the fix back or become a paying customer.
+
+=== Code
+
+The code is located in the 'core/*.mk' and 'plugins/*.mk' files.
+The tests are located in the 'test/Makefile' and 'test/*.mk' files.
+
+If you have a fix or a hack for a bug, you should open a
+pull request. Any fix should include a test case that fails
+before the fix and is working after.
+
+If you have a test case that reproduces a bug, but no fix for
+it, you should open a pull request.
+
+Changes need to be tested with at least the `make check`
+command. A specific test case can be tested using `make check c=CASE`
+with `CASE` the name of the target to run. Output can be
+modulated using the `V` variable, which is an integer
+from 0 to 4. A typical use would be `make check c=dialyzer V=3`.
+The value 4 is particular and shows expanded commands right
+before they are executed.
+
+To run tests in parallel, use the `-j` option. It is generally
+a good idea to also use the `-k` option to run all tests even
+if one fails. For example: `make check -j 32 -k`.
+
+Some changes should be tested against all packages. Continue
+reading for more details on testing them.
+
+=== Packages
+
+You can search existing packages using the `make search q=STRING`
+command. This can be done both from an Erlang.mk project or
+directly from the Erlang.mk repository.
+
+Packages can be added to the index using the `pkg_add.sh` script.
+
+[source,bash]
+----
+$ git clone https://github.com/$YOURUSERNAME/erlang.mk
+$ cd erlang.mk
+$ ./pkg_add.sh cowboy git https://github.com/ninenines/cowboy 1.0.0
+  http://ninenines.eu "Small, fast and modular HTTP server."
+$ git push origin master
+----
+
+Before sending a pull request, you should test your package.
+You can use the following command: `make check p=PACKAGE`,
+where `PACKAGE` is the name of the package, for example
+`cowboy`.
+
+To test all packages, the `make packages` command can be used.
+This can take a long time. Some packages will fail with certain
+versions of Erlang, or if a prerequisite is missing from your system.
+You can of course speed things up using the `-j` and `-k` flags.
+
+After all packages have been tested, you can run the command
+`make summary` to know what changed since the previous run.
+
+=== Documentation
+
+The documentation is always right.
+
+If you think you have found a mistake in the documentation,
+this is a bug. You can either open a ticket or send a pull
+request.
+
+To make sure that the documentation changes work, install
+Asciidoc on your system and run `make docs`.
+
+=== Feature requests
+
+If you have an awesome idea or need something that Erlang.mk
+doesn't provide yet, open a ticket. Provide as much detail as
+possible.
+
+If you have code, great! Open a pull request as previously
+explained.
+
+If not, you can still improve your feature request by writing
+the related documentation.
diff --git a/doc/src/guide/history.asciidoc b/doc/src/guide/history.asciidoc
index 41eec09..30fc9a2 100644
--- a/doc/src/guide/history.asciidoc
+++ b/doc/src/guide/history.asciidoc
@@ -1,5 +1,65 @@
 == Short history
 
-// @todo Write it.
+This chapter aims to be a brief record of the life of the
+Erlang.mk project.
 
-Placeholder chapter.
+=== Before Erlang.mk
+
+Erlang.mk originates from the Cowboy project. Cowboy started
+as a Rebar project and I, Loïc Hoguin, was very happy with it
+for a couple years. Over time however I started getting annoyed
+and frustrated by a number of things, including bad defaults,
+changing defaults and overall slowness.
+
+In particular, at the time I gave up on Erlang.mk, the Cowboy
+test suite was taking about five minutes to run. A quick experiment
+showed I could get much lower times by simply invoking `ct_run`
+directly. On January 4th, 2013, the Cowboy test suite took less
+than a minute to complete.
+
+Following this success I started removing a little more and,
+on the fateful day of January 5th, 2013, removed the dependency
+on Rebar entirely. Rebar, and in particular the concept of
+dependencies, was, and still is, a pretty strong influence.
+
+Erlang.mk was conceived.
+
+A few months passed and, on May 1st, 2013, the Erlang.mk
+repository was created. Erlang.mk was born.
+
+Little did I know how much it would grow.
+
+=== Lifetime of the project
+
+Erlang.mk would eventually become a much larger file able to
+deal with many more projects than just Cowboy. From the birth
+of the project, the biggest force for growth was user contributions,
+because Erlang.mk appealed to a variety of people with different
+needs, needs that Erlang.mk was not fulfilling yet.
+
+The project was split into smaller files focused on a different
+feature each, and a build script was written to build the single
+Erlang.mk file.
+
+A test suite was contributed by a user, and later taken as a basis
+for the current, much more complete test suite. Turns out testing
+a Makefile is pretty straightforward.
+
+A package index was added to solve the problem of discovering
+Erlang projects.
+
+After trying to see if Erlang build tools could cooperate, the
+decision was made to improve compatibility with existing Rebar
+projects by patching Rebar out, using Rebar. This feature, called
+autopatch, proved very successful and made Erlang.mk compatible
+with more than 90% of all Erlang projects.
+
+Erlang.mk documentation was much improved and the Erlang.mk website
+was created in the summer of 2015.
+
+Over the year of 2015, Erlang.mk went from curiosity to a serious
+alternative to other Erlang build tools. The user base increased
+immensely and large projects started using it, including RabbitMQ
+from the 3.6.0 release onward.
+
+A bright future lies ahead.