[muddle] [PATCH] Add contributing guide

Jason Self j at jxself.org
Wed Feb 7 11:32:28 PST 2018

The guide aims to provide helpful information like how to submit
patches and where to go for help, along with style and other
information. It's based on what currently exists in the interpreter
repository, with some changes.

Signed-off-by: Jason Self <j at jxself.org>
 get-involved/index.html | 142 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 139 insertions(+), 3 deletions(-)

diff --git a/get-involved/index.html b/get-involved/index.html
index 6571977..9caa1b0 100644
--- a/get-involved/index.html
+++ b/get-involved/index.html
@@ -16,15 +16,151 @@
   bug, help work on the Muddle language (or related software), help
   with documentation, translation, or something else, there is a
   place for you.</p>
+  <h2>Contributing to Muddle</h2>
+  <p>In addition to this document please read and follow the <a href=
+  "/get-involved/code-of-conduct.html">Code Of Conduct</a> and
+  <a href="/get-involved/attestation.html">Attestation</a>. If you
+  will submit contributions of code or documentation please also read
+  GNU Coding Standards: <a href=
+  "https://www.gnu.org/prep/standards/">https://www.gnu.org/prep/standards/</a>.
+  Reading through this information helps to set basic ground rules,
+  both social and technical, and make sure that everyone is on the
+  same page.</p>
+  <p>It's important to keep communication lines open. Please discuss
+  major changes and enhancements that you wish to make in advance
+  with your fellow contributors.</p>
   <p><strong>Mailing Lists</strong> - Join the <a href=
   "/cgi-bin/mailman/listinfo/">mailing lists</a> to stay informed and
   discuss all things Muddle.</p>
   <p><strong>IRC</strong> - Chat in real-time with other muddlers in
   <strong>#muddle</strong> on <strong>irc.freenode.net</strong>.</p>
-  <p>Please be sure to read and understand our <a href=
-  "/get-involved/code-of-conduct.html">Code Of Conduct</a> and
-  <a href="/get-involved/attestation.html">Attestation</a>.</p>
+  <h1>Submitting Patches</h1>
+  <p>First you will need to set up the git version control system.
+  Your GNU/Linux distro has probably already packaged it for easy
+  installation.</p>
+  <p>Read through the Attestation document and run the commands
+  mentioned in there to set up your name and email address.</p>
+  <p>Be sure to review the information in the rest of this page, then
+  make your changes and commit locally, using <code>git commit
+  --signoff</code> to add your <code>Signed-off-by</code> to
+  <em>each</em> commit.</p>
+  <p>Once ready, use <code>git format-patch origin/master</code> to
+  generate patches for your commits. Email those to the<a href=
+  "/cgi-bin/mailman/listinfo/">mailing list</a> for review.</p>
+  <p>If you have write access to the repository and there is no
+  feedback about the proposed change within a reasonable period of
+  time (at least 24 hours depending on the nature of the change) feel
+  free to push it to the repository (silence = consent.)</p>
+  <h1>Basic Information</h1>
+  <ul>
+    <li>A commit should address one, and only one, concern. For
+    example, a bug fix.</li>
+    <li>Rebase commits rather than merging, to have a linear history
+    (which is easier to follow).</li>
+    <li>Don't rewrite public history.</li>
+    <li>Don't commit anything that can be regenerated from other
+    things that were committed.</li>
+    <li>Make commits against the master branch. All development
+    happens on the master branch. Releases are branched out from
+    master in git.</li>
+    <li>Add or update documentation in the commit, as
+    appropriate.</li>
+    <li>Write or update tests in the commit, as appropriate.</li>
+    <li>Individual commits should be as small as possible, consisting
+    of atomic changes. A single commit should neither be in a partial
+    state, nor should it contain multiple unrelated changes that
+    could be split into separate commits.</li>
+    <li>The software should be reproducible. See <a href=
+    "https://reproducible-builds.org">https://reproducible-builds.org</a>
+    for more information.
+    </li>
+    <li>When adding stuff that you did not directly make yourself
+    it's important to preserve all copyright and license notices, to
+    avoid putting this project at legal risk. Also, just because
+    something you found somewhere doesn't have copyright or license
+    information doesn't mean it's OK. Thanks to things like the Berne
+    Convention things are copyrighted as "All Rights Reserved" by
+    default, so if it's missing copyright and licensing information
+    it's safest to assume it can't be used. When making the commit it
+    is a good idea to set the name, email, and date to match who made
+    it and when, although this part is not required.</li>
+    <li>What is required is to include enough information in the body
+    of the commit message to identify who made it, where it came
+    from, and why you believe it has an acceptable license. If
+    there's a URL to refer to, include that in the commit body too
+    and submit that URL to the Internet Archive's Wayback Machine for
+    preservation: <a href=
+    "https://archive.org/web/">https://archive.org/web/</a>. This
+    helps to document who made what and where it came from, which is
+    useful for future historians.
+    </li>
+    <li>Ensure that each nontrivial file has copyright and licensing
+    information inside of it, adding this if it is not present. This
+    helps to ensure that information is retained when a file is
+    separated from the version control system (i.e., in release
+    tarballs.)</li>
+  </ul>
+  <h1>Git Commit Messages</h1>
+  <ul>
+    <li>Limit the subject to 50 characters.</li>
+    <li>Use proper capitalization and imperative mood in the
+    subject.</li>
+    <li>Don't put a period at the end of the subject.</li>
+    <li>Small changes, like fixing a typo, can get by with only a
+    subject. Larger changes should include a body too.</li>
+    <li>Use a blank line to separate the subject and body.</li>
+    <li>Use the body to explain the what and why of the change.</li>
+    <li>Wrap the body at 70 characters.</li>
+  </ul>
+  <h1 id="coding-style">Coding Style</h1>
+  <p>We use the coding style from the GNU Coding Standards. GNU
+  Indent can be used to style your code appropriately. A summary of
+  the options corresponding to that style are:</p>
+  <pre>
+  <code>-l79    Set maximum line length for non-comment lines to 79.
+-bap    Enter a blank lines after function bodies.
+-bbo    Break long lines before boolean operators.
+-bl     Put braces on line after if, etc.
+-bli2   Indent braces by 2 spaces.
+-bls    Put braces on the line after struct declaration lines.
+-cp1    Put comments to the right of #else and #endif statements in column 1.
+-cs     Put a space after a cast operator.
+-di2    Put variables in column 2.
+-hnl    Prefer to break long lines at the position of newlines in the input.
+-i2     Set indentation level to 2 spaces.
+-ip5    Indent parameter types in old-style function definitions by n spaces.
+-lp     Leave space between '#' and preprocessor directive.
+-nbad   Do not force blank lines after declarations.
+-nbc    Do not force newlines after commas in declarations.
+-ncdb   Do not put comment delimiters on blank lines.
+-nce    Do not cuddle } and else.
+-ndj    Comments after declarations are treated the same as comments after other statements.
+-nfc1   Do not format comments in the first column as normal.
+-nfca   Do not format any comments.
+-nprs   Do not put a space after every '(' and before every ')'.
+-nsc    Do not put the '*' character at the left of comments.
+-nsob   Do not swallow optional blank lines.
+-pcs    Insert a space between the name of the procedure being called and the '('.
+-psl    Put the type of a procedure on the line before its name.
+-saf    Put a space after each for.
+-sai    Put a space after each if.
+-saw    Put a space after each while.</code></pre>
+  <p>How to style your code is not the only thing covered in the GNU
+  Coding Standards. Please consult the Standards for complete
+  details.</p>
+  <h1>Documentation Style</h1>
+  <p>Documentation should be written using Pandoc's extended version
+  of Markdown: <a href=
+  "http://pandoc.org/MANUAL.html#pandocs-markdown">http://pandoc.org/MANUAL.html#pandocs-markdown</a></p>
+  <p>Line length should be set to 70 characters. To ensure that all
+  documentation is styled consistently, run your documentation
+  through Pandoc once it is written and have it convert it to its own
+  Markdown format. Include the options <code>-f markdown -t markdown
+  --columns=70 --wrap=auto</code>.</p>
+  <p>Aside from the differences in documentation format, the
+  information in the GNU Coding Standards for documentation is still
+  relevant and should also be followed.</p>
     <!--#include virtual="../standard-footer.inc" -->

More information about the muddle mailing list