Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (112 loc) · 7.03 KB

CONTRIBUTING.md

File metadata and controls

143 lines (112 loc) · 7.03 KB

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.

AI Policy

Code

Reviewing, testing and triaging pull requests takes a large amount of maintainers' time. Any use of generative AI tools used for any pull request must be explictly mentioned in pull request descriptions to help in triaging.

Please include any prompts, the model used, and a summary of what you've done to validate that the change is correct, complies with LORIS standards, and that the changes are not a hallucination of the model.

Translations

If translation software is used for submitting language translations to LORIS, the policy is roughly the same as for code. In the pull request description, include what software was used to perform the translation. If you are a new contributor to LORIS, mention your level of familiarity with the target language and what you've done to ensure it is correct if it is not your native tongue.

Discussions

Any use of large language models or generative AI tools in areas intended for human communications or feedback can be highly disruptive to collaborative interaction with the community and is strongly discouraged.

Examples include but are not limited to: comments on GitHub issues, replies to feedback on pull requests, or GitHub Discussion forum contributions.

Governance and Confidentiality

Contributors must ensure that confidential data, credentials, protected health information (PHI), or unpublished datasets do not get entered into third-party AI systems or training sets.

This includes data accessed by agentic AI systems.

Licensing

When contributing content to LORIS, you give us permission to use it as-is and you must make sure you are allowed to distribute it to us. By submitting a change to us, you agree that the changes can and should be adopted by LORIS and get redistributed under the GPLv3 license. Authors should be explicitly aware that the burden is on them to ensure no unlicensed code is submitted to the project.