CONTRIBUTING.md

   1 Introduction
   2 ============
   3
   4 First off, thank you for your interest in Muddle! We, your fellow
   5 contributors, welcome contributions of all kinds and types from anyone
   6 anywhere.
   7
   8 Contributing to Muddle
   9 ======================
  10
  11 In addition to this document please read and follow the Code Of
  12 Conduct and Attestation, found elsewhere in this repository. If you
  13 will submit contributions of code or documentation please also read
  14 GNU Coding Standards: <https://www.gnu.org/prep/standards/>. Reading
  15 through this information helps to set basic ground rules, both social
  16 and technical, and make sure that everyone is on the same page.
  17
  18 Where to go for help
  19 ====================
  20
  21 We can be found in `#muddle` on `irc.freenode.net`.
  22
  23 Discussion
  24 ==========
  25
  26 It's important to keep communication lines open. Please discuss major
  27 changes and enhancements that you wish to make in advance with your
  28 fellow contributors.
  29
  30 Submitting Patches
  31 ==================
  32
  33 First you will need to set up the git version control system. Your
  34 GNU/Linux distro has probably already packaged it for easy
  35 installation.
  36
  37 Read through the Attestation document, found elsewhere in this
  38 repository, and run the commands mentioned in there to set up your
  39 name and email address.
  40
  41 Be sure to review the information in the rest of this file, then make
  42 your changes and commit locally, using `git commit --signoff` to add
  43 your `Signed-off-by` to *each* commit.
  44
  45 Once ready, use `git format-patch origin/master` to generate patches
  46 for your commits. Email those to <j@jxself.org> for review.
  47
  48 Basic Information
  49 =================
  50
  51 -   A commit should address one, and only one, concern. For example, a
  52     bug fix.
  53
  54 -   Make commits against the master branch. All development happens on
  55     the master branch. Releases are branched out from master in git.
  56
  57 -   Add or update documentation in the commit, as appropriate.
  58
  59 -   Write or update tests in the commit, as appropriate.
  60
  61 -   Individual commits should consist of atomic changes. A single
  62     commit should neither be in a partial state, nor should it contain
  63     multiple unrelated changes that could be split into separate
  64     commits.
  65
  66 -   The software should be reproducible. See
  67     <https://reproducible-builds.org> for more information.
  68
  69 -   When adding stuff that you did not directly make yourself it's
  70     important to preserve all copyright and license notices, to avoid
  71     putting this project at legal risk. Also, just because something
  72     you found somewhere doesn't have copyright or license information
  73     doesn't mean it's OK. Thanks to things like the Berne Convention
  74     things are copyrighted as "All Rights Reserved" by default, so if
  75     it's missing copyright and licensing information it's safest to
  76     assume it can't be used. When making the commit it is a good idea
  77     to set the name, email, and date to match who made it and when,
  78     although this part is not required.
  79
  80 -   What is required is to include enough information in the body of
  81     the commit message to identify who made it, where it came from,
  82     and why you believe it has an acceptable license. If there's a URL
  83     to refer to, include that in the commit body too and submit that
  84     URL to the Internet Archive's Wayback Machine for preservation:
  85     <https://archive.org/web/>. This helps to document who made what
  86     and where it came from, which is useful for future historians.
  87
  88 -   Ensure that each nontrivial file has copyright and licensing
  89     information inside of it, adding this if it is not present. This
  90     helps to ensure that information is retained when a file is
  91     separated from the version control system (i.e., in release
  92     tarballs.)
  93
  94 Git Commit Messages
  95 ===================
  96
  97 -   Limit the subject to 50 characters.
  98 -   Use proper capitalization and imperative mood in the subject.
  99 -   Don't put a period at the end of the subject.
 100 -   Small changes, like fixing a typo, can get by with only a subject.
 101     Larger changes should include a body too.
 102 -   Use a blank line to separate the subject and body.
 103 -   Use the body to explain the what and why of the change.
 104 -   Wrap the body at 70 characters.
 105
 106 Coding Style
 107 ============
 108
 109 We use the coding style from the GNU Coding Standards. GNU Indent can
 110 be used to style your code appropriately. A summary of the options
 111 corresponding to that style are:
 112
 113     -l79    Set maximum line length for non-comment lines to 79.
 114     -bap    Enter a blank lines after function bodies.
 115     -bbo    Break long lines before boolean operators.
 116     -bl     Put braces on line after if, etc.
 117     -bli2   Indent braces by 2 spaces.
 118     -bls    Put braces on the line after struct declaration lines.
 119     -cp1    Put comments to the right of #else and #endif statements in column 1.
 120     -cs     Put a space after a cast operator.
 121     -di2    Put variables in column 2.
 122     -hnl    Prefer to break long lines at the position of newlines in the input.
 123     -i2     Set indentation level to 2 spaces.
 124     -ip5    Indent parameter types in old-style function definitions by n spaces.
 125     -lp     Leave space between ‘#’ and preprocessor directive.
 126     -nbad   Do not force blank lines after declarations.
 127     -nbc    Do not force newlines after commas in declarations.
 128     -ncdb   Do not put comment delimiters on blank lines.
 129     -nce    Do not cuddle } and else.
 130     -ndj    Comments after declarations are treated the same as comments after other statements.
 131     -nfc1   Do not format comments in the first column as normal.
 132     -nfca   Do not format any comments.
 133     -nprs   Do not put a space after every '(' and before every ')'.
 134     -nsc    Do not put the ‘*’ character at the left of comments.
 135     -nsob   Do not swallow optional blank lines.
 136     -pcs    Insert a space between the name of the procedure being called and the ‘(’.
 137     -psl    Put the type of a procedure on the line before its name.
 138     -saf    Put a space after each for.
 139     -sai    Put a space after each if.
 140     -saw    Put a space after each while.
 141
 142 How to style your code is not the only thing covered in the GNU Coding
 143 Standards. Please consult the Standards for complete details.
 144
 145 Documentation Style
 146 ===================
 147
 148 Documentation should be written using Pandoc's extended version of
 149 Markdown: <http://pandoc.org/MANUAL.html#pandocs-markdown>
 150
 151 Line length should be set to 70 characters. To ensure that all
 152 documentation is styled consistently, run your documentation through
 153 Pandoc once it is written and have it convert it to its own Markdown
 154 format. Include the options
 155 `-f markdown -t markdown --columns=70 --wrap=auto`.
 156
 157 Aside from the differences in documentation format, the information in
 158 the GNU Coding Standards for documentation is still relevant and
 159 should also be followed.
 160
 161 License
 162 =======
 163
 164 Copyright (C) 2017 The Muddle Project Developers
 165
 166 You can redistribute and/or modify this file under the terms of the
 167 GNU Affero General Public License as published by the Free Software
 168 Foundation, either version 3 of the License, or (at your option) any
 169 later version.
 170
 171 This file is distributed in the hope that it will be useful, but
 172 WITHOUT ANY WARRANTY; without even the implied warranty of
 173 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 174 Affero General Public License for more details.
 175
 176 You should have received a copy of the GNU Affero General Public
 177 License along with this file. If not, see
 178 <http://www.gnu.org/licenses/>.