docs/CONTRIBUTING.md

   1 SwashRL Guidelines for Contributors
   2 ===================================
   3
   4 Version 1.0.3.  Last updated 2020-03-07 21:14 CST
   5
   6 ---
   7
   8 Thank you for considering contributing to the SwashRL project.  In this file
   9 you will find some brief guidelines for contributing to the project.  Don't
  10 panic; this is a very small project, so for the most part we don't expect much
  11 from contributors at this stage.
  12
  13 If you're reading this Markdown file in a text editor or other program that
  14 doesn't display hyperlinks, links to files or web pages referenced in this
  15 document can be found at the bottom.
  16
  17 ## Table of Contents
  18
  19 * [Where to Get Started](#where-to-get-started)
  20
  21 * [Before Submitting](#before-submitting)
  22
  23 * [Compiling Your Changes](#compiling-your-changes)
  24
  25 * [Submitting Changes](#submitting-changes)
  26
  27   * [Attribution](#attribution)
  28
  29   * [Professionalism](#professionalism)
  30
  31 * [Style Guide](#style-guide)
  32
  33 ## Where to Get Started
  34
  35 If you'd like to contribute, but you don't know where to get started, check
  36 the [Readme] and the [docs folder].  In the docs folder you'll find a
  37 [to-do list] which lists all of the things that we're currently working on in
  38 order from highest priority to lowest priority, as well as a [list of known
  39 bugs].
  40
  41 You should also check the [Issues page] on [our GitHub], where you will find
  42 open Issues that you can take a stab at fixing yourself, and the
  43 [Projects page], where you can find things that we're currently working on.
  44
  45 ## Before Submitting
  46
  47 **Be aware of [the SwashRL license] before submitting anything that's been
  48 licensed**.  If you're submitting anything that contains content you haven't
  49 written yourself, triple-check that it hasn't been released under a license
  50 that is incompatible with our license.  We take licenses for third-party
  51 content very seriously and carefully consider including anything that might
  52 conflict with our license.  **If you submit something to us, and we learn
  53 later that you do not have permission to license it to us under the terms of
  54 the SwashRL license, your contributions will be scrubbed from the project and
  55 you will be permanently banned from ever contributing again.**
  56
  57 If anything that you submit is licensed, please be courteous and copy the
  58 license into the [docs/license] directory with a filename like "project.txt"
  59 and add a notice to [the third-party licenses file].  You should have one file
  60 and one attribution notice for each license individually.
  61
  62 If you've written everything in your submission yourself, and you don't place
  63 it under any particular license, we will take your submission as permission to
  64 release your changes under [the SwashRL license] in exchange for attribution
  65 (usually in the form of a comment line in the source code and a mention in
  66 [thanks.txt]).  _If you don't want to be attributed for your changes in the
  67 distributed source code or documentation, please let us know in your commit
  68 message or Pull Request._
  69
  70 ## Compiling Your Changes
  71
  72 You can find instructions for compiling SwashRL in the [Readme].
  73
  74 ## Submitting Changes
  75
  76 The best way to contribute to the SwashRL project is to submit a
  77 [Pull Request] on [our GitHub].  We have a Pull Request Template available
  78 that you can use to let us know what you've changed and why, to make things
  79 extra convenient.
  80
  81 If you don't know how to use git or have no experience with the GitHub
  82 website, you can get started with [the guide on their website].
  83
  84 _Do not e-mail any of the contributors with your changes, as your e-mail will
  85 be discarded._
  86
  87 When you commit your changes, be sure to enclose a detailed commit message so
  88 that third-party users can see what you're doing.
  89
  90 ### Attribution
  91
  92 As a professional courtesy, we ask that you acknowledge anyone else that
  93 helped you with your changes, unless they asked to be anonymous.  As such, if
  94 your git branch doesn't already attribute other contributors automatically, we
  95 ask that your commit message do so.  If you don't know how to do this,
  96 [GitHub offers a helpful guide].
  97
  98 ### Professionalism
  99
 100 Some of the people who work on SwashRL are professionals or are seeking
 101 employment in a professional field, so please try to keep your submissions,
 102 including Pull Requests and commit messages, safe for work and politically
 103 correct.  We do have a sense of humor, but keep in mind that our employers
 104 might see what you submit, and any contributions that we accept will reflect
 105 on us, and on you, as a result.
 106
 107 ## Style Guide
 108
 109 SwashRL's code is written to be readable by the average user.  Because
 110 SwashRL is written in D, a relatively new language, this is particularly
 111 important.  As such, we have a few perhaps unconventional rules about the
 112 aesthetics of the source code that you should keep in mind while writing your
 113 changes:
 114
 115 * The code is indented using two spaces, not tab characters, with function
 116 parameters padded with a space on either side to make relevant parenthesis
 117 more visible.
 118
 119 * Where possible, the length of each line of code is limited to 78 characters,
 120 to keep it and diff files related to it readable on your average command
 121 line terminal.  There are some exceptions to this rule, because not every
 122 line of code can easily be broken up into 78-character lines, but in general
 123 we work hard to ensure that this is the case.
 124
 125 * Conditional statements, such as `static if` or `version` statements, are
 126 _not_ indented, but their contents are.  This convention is a holdover from
 127 when the source code was written in C, and is done to make these conditional
 128 programming blocks more visible.
 129
 130 * Class and object names are always Capitalized\_Like\_This, global variables
 131 always have the first letter of their name Capitalized\_like\_this, constants
 132 and enums are always named IN\_ALL\_CAPS, and words in all variable, function,
 133 class, enum, &c names are always separated\_by\_underscores.
 134
 135 * Two different conventions are used for comment lines:
 136
 137   1. Most comment lines use a `//`double-slash format, so that users can
 138 accidentally delete a line without breaking anything.
 139
 140   2. Comment blocks which are considered important, such as copyright notices,
 141 attribution notices, or otherwise important notices, use the more modern
 142 `/*`slash-asterisk format`*/` with an asterisk preceding each new line.
 143
 144   3. In the case of section headers, a box is drawn around the comment using
 145 asterisks or slashes to grab the user's attention.
 146
 147 * Curly brackets `{}` should always be placed on their own line, like this:
 148 `if( this )`
 149 `{`
 150 `..that();`
 151 `..the( other );`
 152 `}`
 153 The exception to this rule is code blocks which contain only one line.  In a
 154 lot of conventions, curly brackets aren't used at all, but in our case we
 155 choose a less ambiguous compromise:
 156 `if( this )`
 157 `{ that();`
 158 `}`
 159
 160 * The end of a long ``if`` block, function, or other programming block that
 161 ends with a curly bracket ``}`` should include a ``//`` comment that lets the
 162 user know which block that curly bracket marks the end of.  This will also
 163 make it easier for you to keep track of your own code.
 164
 165 As a rule of thumb, just try to make your code look like our code for the sake
 166 of consistency and you'll be fine.
 167
 168 [the SwashRL license]: ../LICENSE.txt
 169 [the third-party licenses file]: ../3rdparty.txt
 170 [Readme]: ../README.md
 171 [docs folder]: ../docs
 172 [to-do list]: ../docs/to-do.txt
 173 [list of known bugs]: ../docs/bugs.txt
 174 [docs/license]: ../docs/license
 175 [thanks.txt]: ../thanks.txt
 176 [our GitHub]: https://github.com/swashdev/SwashRL
 177 [Issues page]: https://github.com/swashdev/SwashRL/issues
 178 [Projects page]: https://github.com/swashdev/SwashRL/projects
 179 [Pull Request]: https://github.com/swashdev/SwashRL/pulls
 180 [the guide on their website]: https://guides.github.com/activities/hello-world/
 181 [GitHub offers a helpful guide]: https://help.github.com/articles/creating-a-commit-with-multiple-authors/