Contributing

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Guidelines for contributors
+
+Thank you for your interest in contributing to the CBRAIN project.
+
+We ask you to respect the following basic rules:
+
+## All contributions must be written by a human.
+
+We do *NOT* accept any code or comments generated by *AI* (Artificial Intelligence) systems.
+
+That means you must be able to vouch for the meaning of every letter, digit and special character in your Ruby, Javascript or HTML code, and in their associated comment blocks.
+
+This rule is true even if you feel you have poor skills in English or French; we will be very forgiving, and even welcoming, because we like to talk to humans a lot more than to talk to machines.
+
+## Keep your communications to simple sentences.
+
+We only want the core information that will help us evaluate your contribution, as written by you, the author of the changes.
+
+When communicating with us via the discussion panels of [Pull Requests](https://github.com/aces/cbrain/pulls) and [Issues](https://github.com/aces/cbrain/issues), avoid long bullet point lists, sections with long paragraphs, and overly general justifications.
+
+When providing a *Pull Request*, do not repeat the description of a problem if it's already described in an associated *Issue*.
+
+Here are examples of straightforward, practical descriptions:
+
+* [Pull Request 1581](https://github.com/aces/cbrain/pull/1581).
+* [Issue 1568](https://github.com/aces/cbrain/issues/1568) which also has an associated [Pull Request 1573](https://github.com/aces/cbrain/pull/1573).
+
+## Start your modifications at the HEAD of one of the two branches.
+
+Work on your own fork of CBRAIN. This is the standard business process with GitHub.
+
+We have two main branches, `master` and `dev`. Small bug fixes and adjustments can be made against the `master` branch. We're fine with that. Larger changes should be made on the `dev` branch, but you can contact us if it's not convenient or if the `dev` branch is too far behind.
+
+## Pull Requests should contain the minimal amount of changes.
+
+Make changes only on the lines of code that require them for the feature or bug you are working on.
+
+Review carefully all your changed lines before you push them to your fork. That includes adding
+or suppresing blank lines around them, as needed, and adjusting comment blocks.
+
+## Don't include pictures and screenshots.
+
+We don't want screenshots of your terminal or console commands. The only times that
+screenshots are justified is when you are working on the web user interface.
+
+Use proper mark down when you need to quote Ruby code or shell commands.
+See the Pull Request 1581 link above for and example of a comment with a Ruby code block.
+
+## Add comments that explain the flow of the logic of your code.
+
+Explain *WHAT* your code is doing, and not *HOW* it's doing it.
+
+Do not write comments that repeat the code. For method headers, provide a
+programmer-centric description of the role of the method. Within code, only
+one or two lines of explanations are needed every so often.
+
+An example of such comments can be seen in the method `retry_setup!` here: [CBRAIN file background_activity.rb line 668](https://github.com/aces/cbrain/blob/f14340b6327b933d610ad0e3011f8353efb8866d/BrainPortal/app/models/background_activity.rb#L668)
+
+## Follow the general style of CBRAIN.
+
+The codebase is not all that consistent, but look around.
+
+We also have a [programming style guide](https://github.com/aces/cbrain/wiki/Programming-Style).
+
+Your code *MUST* be written in plain UTF-8 text with only the _linefeed_ character (ASCII 10, as in `\n`) as your line terminator. We do no accept Windows-style line terminators (carriage return + linefeed, `\r\n`), because we're UNIX developers. And the last line of a file, if not blank, must also end with a _linefeed_ .
+
+## Be nice.
+
+Consider reading our [Code of Conduct](./CODE_OF_CONDUCT.md) for further information.
+