From 3c5c8290e2df4ee915816fc59ccbca22174a42bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 4 Dec 2015 10:29:24 +0100 Subject: Add contributing and history chapters to the guide --- doc/src/guide/book.asciidoc | 2 - doc/src/guide/contributing.asciidoc | 113 +++++++++++++++++++++++++++++++++++- doc/src/guide/history.asciidoc | 64 +++++++++++++++++++- 3 files changed, 173 insertions(+), 6 deletions(-) (limited to 'doc') 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. -- cgit v1.2.3