Skip to content

Latest commit

 

History

History
102 lines (79 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

102 lines (79 loc) · 5.12 KB
Raw

Contributing to Loris

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.

Your next step before issuing a pull request is to review our Coding Standards. If you are doing front-end development you should also check out our React guidelines.

You can also learn about our code review process by perusing our Code Review Checklist in the LORIS Wiki. These will be some of the factors we'll consider when reviewing your code.

Development branches

For the most part, changes to the codebase should be sent to the main branch, which is the default.

Small bug fixes for a given version of LORIS should be sent to the branch named for that version. For example, fixing a bug in LORIS version 22 should be sent to the 22.0-release branch.

Pull Request Title and Description

To make it easier for reviewers to locate pull requests with which they have expertise, we request that new pull requests follow a few conventions.

Title

The title should begin with square brackets enclosing the name of the module that you are changing followed by a brief description.

e.g. This is a well-formed title.

[Imaging Uploader / Server Process Manager] Fix invalid upload state

If you are instead editing the Core libraries or the tools directory, etc., you can supply these values in place of a module name.

There should be plenty of other examples in the list of pull requests in the main code repository.

Description

When opening a pull request on GitHub you will see a pull request template. Please fill out each heading with detailed information on your code changes, suggested testing instructions, and links to open GitHub issues and/or Redmine tickets (if applicable).

Some Things To Keep In Mind

  • If your changes require any table modifications:
    1. Review our SQL standard.
    2. Modify the SQL/0000*.sql file(s) with your changes. These patches are applied during the LORIS install.
    3. Include a patch to be used by existing projects. These should go in the SQL/New_patches/ directory.
    4. For SQL patches that are optional (e.g. those that perform some cleanup), place them in SQL/Cleanup_patches/.
    5. The files for our test database (Raisinbread) must be updated if they were modified. Detailed instructions for this step can be found in the Raisin Bread README.md.
  • 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.
  • Before sending any pull request, make sure you run our static analysis tools locally. More information can be found in the testing guide.
  • 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 Caveat for Existing Projects. This helps us to document our release notes.
  • You can run the command make checklanguage to ensure that documentation you've contributed contains language that is friendly and accessible.
  • Be sure to modify the CHANGELOG.md file.

If you're unsure about any of the above, feel free to ask us for clarification via the mailing list.

Git Best Practices

  • Any changes should be done on a branch based on the current development branch and contain only the changes which are applicable for that branch. (ie don't merge the main branch back into your branch, and don't include commits that are unrelated) so that if someone merges the branch into their repository, they only get that branch's changes.
  • Commits should be atomic (self contained) and contain only the changes described by the commit message. The commit message should be a sentence that describes the goal of the change as a whole.
  • Avoid changing unrelated code in the same commit, even if it is an improvement. We prefer that you create two separate pull requests A and B rather than add a 'quick bonus fix' to pull request A.
  • ALWAYS do a diff before committing (after doing "git add file1 file2" when you're planning on doing git commit, you can use git diff --staged to see a diff of what will be committed). Ensure that nothing unexpected is included.

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. Issues tagged with Beginner Friendly are good ones to tackle if you are new to LORIS development.
  • You can help improve our documentation if you find any parts of it confusing or lacking.
  • You can track down bugs by browsing the application and reviewing the PHP error log.