Contributing

If you’re interested in contributing to O3, you’ll need to take the following steps.

• Get access to OpenMRS Jira (opens in a new tab). If you don’t have access, raise a request at the Help Desk (opens in a new tab). Wait at least 24 hours for the request to get approved; you will receive an email upon approval. Once approved, take a look at all the frontend module-related issues (opens in a new tab). Good first issues are filed under the intro (opens in a new tab) label.
• Join our Slack Channel (opens in a new tab) and introduce yourself. You will first need to create an OpenMRS Slack account (opens in a new tab) if you don’t have one.

Contributing guidelines

• Pull requests (PRs) of type "feature", "fix", "refactor", "perf", and "BREAKING" (see "type of change" section below) are required to correspond to a ticket - The ticket related to the PR should be clearly named and linked in the PR.

• Push additional commits - Pull requests are allowed (and encouraged) to contain more than one commit. Those commits are squashed when your PR gets merged into main.

• Do not close a PR and recreate a new one with the same code - If you have opened a PR for some work and a reviewer has requested some changes, do not open a new PR with the updates and close the old one. This makes things very hard for reviewers.

• Read and fill out the PR template when filing a PR - The PR template exists to help you give us all the information we need in a format we can quickly review. Filling it out correctly will make everyone’s work faster and easier.

• Work incrementally - Smaller PRs are easier to read and validate. Opening multiple PRs for the same ticket is excellent if those PRs represent different pieces or stages of work relating to that ticket.

• Do not increase the scope of a PR after it has been reviewed - If your code has been reviewed, don’t push a bunch more code that isn’t related to the review. Fixups are fine, but new features should have their own PRs. Remember—small PRs are easier to review anyway!

• Your first PR to a codebase should be small - Get a feel for what the reviewer expects before submitting a PR with a large amount of code in it.

• Your PR title should indicate the type of change it is - We use PR titles to determine version bumps when releasing frontend modules. PR titles should begin with the conventional commit (opens in a new tab) type that relates to your PR. Examples of good PR titles:

  • “(docs) Add to contributing docs”
  • “(fix) Console error when visiting allergies page”
  • “(feat) Add search bar to medications widget”
  • “(refactor) Tidy the dashboard implementation”
  • “BREAKING: New left nav system”

  Common prefixes include the above, and chore, style, perf, and test. Read more about conventional commit types here (opens in a new tab).

  The changelogs we put out alongside each release are generated from the PR titles, so it’s important to follow this convention. Don’t worry if you aren’t sure which one you should use! Your reviewer should make sure your PR has an appropriate one.

Guidelines for reviewing code

• Encourage feedback as both an author and reviewer.
• Encourage as many contributors to engage in deep and meaningful contribution.
• Be sensitive to the varying experience levels of OpenMRS contributors.
• Avoid gatekeeping, which includes over-emphasizing to contributors how they’re failing to follow the correct process.
• Encourage code ownership, including reviewing changes to the code and projects you’ve contributed to.
• Provide detailed and helpful feedback to contributors, including using GitHub’s suggestion feature (opens in a new tab) to help the contributor know how to make the needed changes.

The above guidelines were established in RFC-20 (opens in a new tab).

Coding conventions

Read our coding conventions guide to learn about the conventions we encourage in O3.