-
Notifications
You must be signed in to change notification settings - Fork 173
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Docs] Update and rework CONTRIBUTING.md #3859
Changes from 6 commits
554e935
da4b8fa
010dc7f
22a2d03
4002c66
a161cee
358d524
e25550c
079d772
186370d
c84b26a
d4582ed
3be5eb7
d26e28c
1b9256e
a5c70d6
3a9f466
5c91bff
544834c
64f0c72
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||
---|---|---|---|---|
|
@@ -3,45 +3,55 @@ | |||
We'd love to have you contribute to Loris. The first thing you should do | ||||
before contributing is probably sign up for the [LORIS developers' mailing list](http://www.bic.mni.mcgill.ca/mailman/listinfo/loris-dev). | ||||
|
||||
Your next step before issuing a pull request is to review our [Coding Standards](https://github.com/aces/Loris/blob/minor/docs/CodingStandards). If you are doing front-end development you should also check out our [React guidelines](https://github.com/johnsaigle/Loris/blob/180631-Contributing/LORIS_react.README.md). | ||||
|
||||
You can also learn about our code review process by perusing our [Code Review Checklist](https://github.com/aces/Loris/wiki/Code-Review-Checklist) in the [LORIS Wiki](https://github.com/aces/Loris/wiki). These will be some of the factors we'll consider when reviewing your code. | ||||
|
||||
## Development branches | ||||
|
||||
Pull requests should be based on and sent to the VERSIONNUMBER-dev branch of the version that you are targeting. The master branch is reserved for stable releases. | ||||
You should base your pull requests on one of the following branches depending on the kind of change you are making: | ||||
|
||||
#### Bug Fixes | ||||
- Branch: `bugfix` | ||||
- Label: ![](https://via.placeholder.com/15/cc9966/000000?text=+) **[branch] bugfix** | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If you look at the rendered Markdown it displays a little colourful box the same colour as our labels. I just copied this part from the Wiki cause it looks good. Not sure what this site it for. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I had added these to the wiki, thats the only way I found to put colourful boxes to match the label colours |
||||
- Content: Generally these changes do not require SQL scripts and are concise with the sole objective to correct on single problem in the code. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. minor typo - should read 'one single problem' |
||||
|
||||
#### Minor Changes and Small Features | ||||
- Branch: `minor` | ||||
- Label: ![](https://via.placeholder.com/15/996633/000000?text=+) **[branch] minor** | ||||
- Content: Features affecting self-contained components such as modules. Additions to Libraries, API or modules that do not change and function signatures. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. is function a noun or a verb here? should it maybe be "..that do not change, and function signatures" so it's read the right way? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @johnsaigle all yours !! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it's just a typo for "do not change any function signatures"? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I just copied this from the Wiki -- agreed it could be reworded. Will do so this afternoon. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. i think dave is right |
||||
|
||||
Your current version number can be found in the VERSION file under the LORIS root. | ||||
#### Major Changes, Non Backwards-Compatible Changes and Large Features | ||||
- Branch: `major` | ||||
- Label: ![](https://via.placeholder.com/15/4d3319/000000?text=+) **[branch] major** | ||||
- Content: Any change modifying a function signature in a library class. Features require extensive LORIS-wide testing. New complex systems and features spanning across multiple modules and libraries. Deprecated functions clean-up. | ||||
|
||||
## Code Contributions | ||||
For more information about making well-organized pull requests, please read our in-depth Wiki page, ["Contributing to the Code"](https://github.com/aces/Loris/wiki/Contributing-to-the-Code). | ||||
|
||||
If you'd like to contribute code, here are some things to keep in mind. | ||||
|
||||
* If your changes require any table modifications, don't forget to modify the | ||||
SQL/0000*.sql file(s) with your changes for new installs, and also | ||||
include a patch for existing projects to apply to get your changes of which | ||||
should be placed in the corresponding SQL/VERSIONNUMBER/ directory. | ||||
* Include a test for any new module in the modules/MODULENAME/test/ | ||||
## Some Things To Keep In Mind | ||||
|
||||
* If your changes require any table modifications: | ||||
1. Modify the `SQL/0000*.sql` file(s) with your changes. These patches are applied during the LORIS install. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would add "review our [SQL Standard]https://github.com/aces/Loris/blob/minor/docs/SQLModelingStandard.md" as item 1 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ^ i agree! |
||||
2. Include a patch to be used by existing projects. These should go in the `SQL/New_patches/` directory. | ||||
3. For SQL patches that are _optional_ (e.g. those that perform some cleanup), place them in `SQL/Cleanup_patches/`. | ||||
* Include a test for any new module in the `modules/MODULENAME/test/` | ||||
directory. You can look at other modules for examples of how to write tests. | ||||
If you have questions, feel free to mail the mailing list. | ||||
* Add your new tests to get auto-run by Travis in the .travis.yml to make sure that | ||||
other people don't accidentally break your module. | ||||
* Check out our Coding Standards in the [docs/ directory](https://github.com/aces/Loris/tree/master/docs) and also our [Code Review Checklist](https://github.com/aces/Loris/wiki/Code-Review-Checklist) in the [GitHub Wiki](https://github.com/aces/Loris/wiki) and the Pull Request guidelines Readme in this directory. | ||||
* Try and make sure you run PHP codesniffer using the standards file in | ||||
docs/LorisCS.xml before sending any pull request, otherwise the Loris tests may | ||||
fail and we won't be able to merge your pull request. | ||||
* Keep in mind that people are currently using Loris so try and make any changes | ||||
backwards-compatible with existing installations. If you must change something | ||||
in a non-backwards-compatible way, document it in your pull request description and | ||||
tag it with "Caveat For Existing Projects" so that we know that the change needs | ||||
to be mentioned in release notes. Non-backwards-compatible changes should be sent | ||||
to the next major release (e.g. 17.X -> 18.0) while backwards-compatible changes should | ||||
be sent to the next minor release (e.g. 17.1.0 -> 17.2.0) and backwards-compatible bug | ||||
fixes should be sent to the next minor release update (e.g. 17.1.0 -> 17.1.1) | ||||
|
||||
## Ways To Get Started | ||||
|
||||
If you're looking for ideas for a way to contribute but don't know where to get | ||||
started, some ideas to get you started: | ||||
|
||||
* You can browse some of our public [Issues](https://github.com/aces/Loris/issues) | ||||
* Add your new automated tests to TravisCI in the `.travis.yml`. | ||||
* Make sure you run PHP codesniffer using the standards file in | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. should it be changed to incorporate the command to run phpcs? eg.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. or atleast a reference to Line 21 in 12135e9
|
||||
`docs/LorisCS.xml` before sending any pull request, otherwise the automated tests will fail. | ||||
* Try and make all changes backwards-compatible with existing installations. | ||||
* If you must change something in a non-backwards-compatible way - or if it would affect the data or custom code of a study - document this in your pull request description and | ||||
tag it with ![](https://via.placeholder.com/15/d4c5f9/000000?text=+) **Caveat for Existing Projects**. This helps us to document our release notes. | ||||
|
||||
If you're unsure about any of the above, feel free to ask us for clarification via the mailing list. | ||||
|
||||
## Getting Started | ||||
|
||||
If you're looking for ideas for a way to contribute but don't know where to begin, here are some ideas to get you started: | ||||
|
||||
* You can browse some of our public [Issues](https://github.com/aces/Loris/issues). Issues tagged with ![](https://via.placeholder.com/15/0e8a16/000000?text=+) **Beginner Friendly** are good ones to tackle if you are new to LORIS development. | ||||
* You can run PHP CodeSniffer on modules that haven't had it run yet. | ||||
* You can help improve our documentation if you find any parts of it confusing or | ||||
lacking | ||||
* You can try and track down any bugs | ||||
lacking. | ||||
* You can track down bugs by browsing the application and reviewing the PHP error log. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@johnsaigle I think github supports relative links and in this case you would want to link to the coding standards on your own branch, not minor
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oops accident