Skip to content
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

Merged
merged 20 commits into from
Sep 17, 2018
76 changes: 43 additions & 33 deletions CONTRIBUTING.md
Expand Up @@ -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).
Copy link
Collaborator

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops accident


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**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Collaborator

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@johnsaigle all yours !!
I dont talk england very best

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

modules that do not change and function signatures. maybe ... do not change functionality or function signatures ...

Copy link
Collaborator

Choose a reason for hiding this comment

The 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"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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

Copy link
Contributor

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should it be changed to incorporate the command to run phpcs? eg.

Make sure you run PHP codesniffer using the standards file in docs/LorisCS.xml by running vendor/bin/phpcs --standard=docs/LorisCS.xml <path_to_changed_files> before sending any pull request, otherwise the automated tests will fail.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or atleast a reference to

with the command `vendor/bin/phpcs --standard=docs/LorisCS.xml [file]` for any

`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.