Update user guide

author: Loïc Hoguin <[email protected]> 2015-12-29 00:29:21 +0100
committer: Loïc Hoguin <[email protected]> 2015-12-29 00:29:21 +0100
commit: 6e4fcfabb728dfa2114a4076a4d8247caf25fe09 (patch)
tree: 284d14397f4121eafe8ae94cc6bdd988d26169b8 /guide/contributing.html
parent: c29515fcf341036c83edf29a8c1d4233c9261f11 (diff)
download: erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.tar.gz
erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.tar.bz2
erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.zip
1 files changed, 86 insertions, 0 deletions
diff --git a/guide/contributing.html b/guide/contributing.html
new file mode 100644
index 0000000..ba91d94
--- /dev/null
+++ b/guide/contributing.html
@@ -0,0 +1,86 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Erlang.mk User Guide</title>
+<style type="text/css"><!--
+body{background:white;color:black;font-family:"Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;justify-content:center;margin:0 auto;padding:0;width:600px}
+header {align-items:center;display:flex;justify-content:center}
+header nav.left{text-align:right;width:150px}
+header nav.right{text-align:left;width:150px}
+header nav a{display:block;margin:1.5em 1em}
+main{margin-top:2em;text-align:justify}
+main h2, main h3{margin-top:2em}
+a{color:#d9230f;text-decoration:none}
+a:hover{text-decoration:underline}
+h1, h2, h3{font-weight:normal}
+div.navfooter{margin-bottom:1em}
+--></style>
+</head>
+<body>
+<header>
+	<nav class="left">
+		<a href="index.html">User guide</a>
+		<a href="ch02.html">Tutorials</a>
+	</nav>
+	<a href="/" class="logo"><img src="../res/logo-small.png" alt="Erlang.mk" title="Erlang.mk: A build tool for Erlang that just works" height="200" width="206"/></a>
+	<nav class="right">
+		<a href="https://github.com/ninenines/erlang.mk/tree/master/index">470+ packages</a>
+		<a href="https://github.com/ninenines/erlang.mk/issues">Issues?</a>
+	</nav>
+</header>
+<main>
+
+<div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="history.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="contributing"></a>Chapter 25. Contributing</h2></div></div></div><p>You are welcome and encouraged to contribute.</p><p>This is how.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_priorities"></a>25.1. Priorities</h2></div></div></div><p>From the most important to the least important:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+Bugs
+</li><li class="listitem">
+Package issues/additions
+</li><li class="listitem">
+Refactoring
+</li><li class="listitem">
+Features
+</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_bugs"></a>25.2. Bugs</h2></div></div></div><p>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.</p><p>If you think you have found a bug but you are not sure, you
+should open a ticket as previously explained.</p><p>If you have found a bug and you need it to be solved RIGHT
+NOW, open a ticket as previously explained.</p><p>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.</p><p>If you can’t be patient, either try to solve the bug and
+contribute the fix back or become a paying customer.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_code"></a>25.3. Code</h2></div></div></div><p>The code is located in the <span class="emphasis"><em>core/*.mk</em></span> and <span class="emphasis"><em>plugins/*.mk</em></span> files.
+The tests are located in the <span class="emphasis"><em>test/Makefile</em></span> and <span class="emphasis"><em>test/*.mk</em></span> files.</p><p>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.</p><p>If you have a test case that reproduces a bug, but no fix for
+it, you should open a pull request.</p><p>Changes need to be tested with at least the <code class="literal">make check</code>
+command. A specific test case can be tested using <code class="literal">make check c=CASE</code>
+with <code class="literal">CASE</code> the name of the target to run. Output can be
+modulated using the <code class="literal">V</code> variable, which is an integer
+from 0 to 4. A typical use would be <code class="literal">make check c=dialyzer V=3</code>.
+The value 4 is particular and shows expanded commands right
+before they are executed.</p><p>To run tests in parallel, use the <code class="literal">-j</code> option. It is generally
+a good idea to also use the <code class="literal">-k</code> option to run all tests even
+if one fails. For example: <code class="literal">make check -j 32 -k</code>.</p><p>Some changes should be tested against all packages. Continue
+reading for more details on testing them.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_packages"></a>25.4. Packages</h2></div></div></div><p>You can search existing packages using the <code class="literal">make search q=STRING</code>
+command. This can be done both from an Erlang.mk project or
+directly from the Erlang.mk repository.</p><p>Packages can be added to the index using the <code class="literal">pkg_add.sh</code> script.</p><pre class="programlisting">$ 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</pre><p>Before sending a pull request, you should test your package.
+You can use the following command: <code class="literal">make check p=PACKAGE</code>,
+where <code class="literal">PACKAGE</code> is the name of the package, for example
+<code class="literal">cowboy</code>.</p><p>To test all packages, the <code class="literal">make packages</code> 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 <code class="literal">-j</code> and <code class="literal">-k</code> flags.</p><p>After all packages have been tested, you can run the command
+<code class="literal">make summary</code> to know what changed since the previous run.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_documentation"></a>25.5. Documentation</h2></div></div></div><p>The documentation is always right.</p><p>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.</p><p>To make sure that the documentation changes work, install
+Asciidoc on your system and run <code class="literal">make docs</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_feature_requests"></a>25.6. Feature requests</h2></div></div></div><p>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.</p><p>If you have code, great! Open a pull request as previously
+explained.</p><p>If not, you can still improve your feature request by writing
+the related documentation.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="history.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="about.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
+</main>
+</body>
+</html>
author	Loïc Hoguin <[email protected]>	2015-12-29 00:29:21 +0100
committer	Loïc Hoguin <[email protected]>	2015-12-29 00:29:21 +0100
commit	6e4fcfabb728dfa2114a4076a4d8247caf25fe09 (patch)
tree	284d14397f4121eafe8ae94cc6bdd988d26169b8 /guide/contributing.html
parent	c29515fcf341036c83edf29a8c1d4233c9261f11 (diff)
download	erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.tar.gz erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.tar.bz2 erlang.mk-6e4fcfabb728dfa2114a4076a4d8247caf25fe09.zip