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
61 changes: 35 additions & 26 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,45 +3,54 @@
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: _[branch] bugfix_
- 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: _[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


- **Major Changes**, **Non Backwards-Compatible Changes** and **Large Features**
- Branch: `major`
- Label: _[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.

Your current version number can be found in the VERSION file under the LORIS root.
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).

## Code Contributions

If you'd like to contribute code, here are some things to keep in mind.
## 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
`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/
should be placed in the corresponding `SQL/VERSIONNUMBER/` directory.
Copy link
Collaborator

Choose a reason for hiding this comment

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

this is now SQL/New_patches/

Copy link
Collaborator

Choose a reason for hiding this comment

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

and clean-up or optional patches 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
* 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
Copy link
Collaborator

Choose a reason for hiding this comment

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

not necessarily non-backwards compatible only. anything that might affect the data and/or code of the project should be flagged (try to formulate that in good english)

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)
tag it with ![](https://via.placeholder.com/15/d4c5f9/000000?text=+) **Caveat for Existing Projects** so that we know that the change needs to be mentioned in release notes.

## Ways To Get Started
## Getting 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:
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)
* 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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

missing the ![] after tagged with

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