Thank you for your interest in contributing to the CBRAIN project.
We ask you to respect the following basic rules:
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.
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 and 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.
- Issue 1568 which also has an associated Pull Request 1573.
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.
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.
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.
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
The codebase is not all that consistent, but look around.
We also have a programming style guide.
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 .
Consider reading our Code of Conduct for further information.