New Contributors Guide (DRAFT)

• Where to do introductions (In this post, and maybe #GSoC. Don't spam the different slack channels)

• What to read up on (o3-docs, ???)

• Where / who to ask questions (???)

• Have your display name be consistent across different platforms (Slack, talk.openmrs.org, JIRA, Github).

• How to contribute:

  • Which issues to take up?

    • What part of the code base to work on:

      • preferably places with feature owners

        • areas with no feature owners will probably get less attention

    • Don't assume tickets are up to date.

      • We are a large community, and tickets sometimes get created and get stale, with information that's out of date. Sometimes the ticket is no longer relevant, or the work has already been completed, but the ticket is not updated. Talk to a feature owner before working on an issue, especially in features where you haven't worked on before, or when the ticket is old.

      • Ask clarifying questions before you start. This could save both you and your code reviewers a lot of time.

    • Start with lower stake tickets

      • Risky tickets need to meet a higher bar

        • Risky PRs can also take substantially longer to review, even if you did everything right

  • Getting your PRs accepted

    • Ultimately, you need to convince us that we should accept your PR. Things that give us pause:

      • Not reviewing your own code changes, especially AI-generated ones

        • While AI agents are getting better at producing / reviewing code, our code base is still maintained by humans. We need to read and understand your changes, and we expect you to do the same. You should understand your own changes as well as we do, if not better.

        • You PR should follow PR template and coding guidelines.

      • large code changes

        • Again, we need to read and understand your changes. While large PRs are appropriate in some cases, they will naturally take longer to review.

      • Risk of regression bugs / Insufficient tests

        • Writing unit / E2E tests gives us much higher confidence that your code works. If you're not sure how, ask the feature owner. The amount of tests should be proportional to the risk and scope of your changes.

          • If writing automated tests is not feasible, at least include what you did to manually test your code in your PR description.

        • Like most places, we have an unwritten policy of "if you break it, then you fix it" for regressions. However, we can't really enforce that for volunteers. This means we tend to be more conservative with accepting volunteer contributions.

      • Insufficient PR description

        • Your PR description should show that you thought about the feature carefully. Summarize your changes, any potential risk, and how you tested your code. If there is mismatch between your code changes and the description, then this will give us less confidence in your PR.

        • Make sure to follow the PR template of the repo you are making changes in.

      • Failing builds / tests

        • If your changes does not pass the Github Actions automated checks, investigate the failures. If you think the failures are unrelated to your changes, write a note explaining why; otherwise, fix the failures.

    • Assign the feature owner as reviewer (???)

    • If you don't get feedback after a week, DM the feature owner. Sometimes we are just busy, or your PR might get lost in our pile of work. If you still don't hear back for another week, (???)

  • Coding is not the only way to contribute. We need help in other areas too:

    • Testing / Verifying PRs

    • Finding issues and filing tickets (check with feature owners first)

    • Documenting parts of our code.

      • If you find parts of our code base confusing

    • Updating existing tickets if they are stale / lack sufficient info (check with feature owners first)

As community members, we should:

• Curate a list of tickets to do.

• Curate a list of feature owners.