Bahmni Feature Proposal & Contribution Guide

The guidelines define the mandatory process for proposing, reviewing, approving, and contributing enhancements, features, architectural changes, or new modules to Bahmni.

Objectives

The objective is to ensure:

• Alignment with Bahmni’s product strategy and roadmap

• Transparency within the community

• Architectural integrity and upgrade safety

• UX consistency across modules

• Long-term maintainability

• Avoidance of duplication

Scope

These guidelines apply to:

Contribution Flows

There are two contribution flows. Choose the flow based on the size and impact of the proposed change.

Flow 1: Minor Enhancements and Bug Fixes

Minor enhancements and bug fixes follow a simplified contribution process. They do not require a Concept Brief or community proposal unless the change significantly alters existing functionality.

Step 1: Create a JIRA Issue

Create a JIRA issue in the appropriate Bahmni project with:

https://bahmni.atlassian.net/jira/software/c/projects/BAH/boards/37

• Summary: concise title.

• Issue type: Bug, Improvement, or Task.

• Description: problem, current and expected behaviour, steps to reproduce or proposed solution, and impact.

• Supporting information: screenshots, logs, API responses, mockups, or related discussions.

• Labels: relevant tags such as bug, enhancement, UI, EMR, or Orders.

Step 2: Maintainer Review

If the issue is straightforward and the scope is clear, development may begin after maintainers review and prioritise the JIRA issue.

If the proposed change affects existing workflows, introduces new functionality, or requires design decisions, maintainers may request an OpenMRS Talk discussion before implementation.

Step 3: Development Governance

Once the issue is accepted, development must follow the common governance requirements defined in the Development Governance section.

Step 4: Pull Request and Code Review

Submit a Pull Request that:

• References the JIRA issue.

• Includes a clear description of the implemented changes.

• Provides screenshots or recordings for UI changes.

• Ensures all CI checks pass.

The Pull Request will undergo the standard Bahmni code review process before being merged.

Flow 2: Major Enhancements and New Features

Major enhancements and new features follow a formal proposal, review, and sign-off process before development begins.

Step 1: Submit Proposal on OpenMRS Talk

Every proposal for a new feature or major enhancement must start with a public discussion on OpenMRS Talk and include a Concept Brief. This is the required entry point before formal review.

Concept Brief: Required Sections

The Concept Brief should include the following sections:

1. Problem Statement

• Core problem being addressed

• Current workflow or limitation

• Relevant background information and supporting data

2. Proposed Solution

• Functional requirements

• Scope of the proposed change

• Out-of-scope items

3. Impact Assessment

• Affected product modules

• Impact on existing implementations and backward compatibility

• Upgrade and migration considerations

• Configuration changes versus code changes

4. User Experience

• Affected screens or user flows

• Figma designs, wireframes, or prototypes, where applicable

5. Architecture and Technical Design

• Structural system outcomes

• External package reliance

• Implementation methodology

• Schema or data store modifications, where applicable

Step 2: Community Assessment

Public interaction serves as the foundation for collecting input, confirming user needs, and refining the proposed solution. Official assessment begins only after an open thread containing the mandatory Concept Brief is published.

Step 3: Product Advisory Team Review

The proposal must be presented during a weekly Product Advisory Team (PAT) call.

The PAT review focuses on:

• Strategic roadmap alignment

• Overlap with existing initiatives

• Community prioritisation

Step 4: Functional Sign-Off

The proposal posted on the OpenMRS Talk thread must receive formal sign-off from:

Note: SLA will be approximately 7–15 days. Once approved, create the JIRA card after sign-off is received from the respective owners.

Step 5: Development Governance

After functional sign-off is received and the JIRA card is created, development must follow the common governance requirements defined in the Development Governance section.

Development Governance

After a contribution is approved through either Flow 1 or Flow 2, development must follow the same governance requirements below.

Git Workflow

Bahmni follows a strict branching and naming convention:

1. Fork & Clone: Fork the official repo (e.g., bahmni-apps-frontend) and clone it locally.

2. Upstream Remote: Set the original Frontend repo as your upstream to keep your fork updated.

3. Branch Name: Create a branch named after the Jira ticket ID.

4. Correct: git checkout -b BAH-1234

5. Incorrect: git checkout -b fix-login-bug

6. Atomic Commits: Squash your changes into one single commit before pushing. The commit message must follow the pattern: PROJECT-ID: Short description of fix (e.g., O3-123: Added validation to the login form).

• Update relevant documentation and Wiki pages 

• Maintain backward compatibility (unless explicitly approved otherwise)

Pull Request & Merge Requirements

Submitting & Sign-off

• Testing Evidence: Add recording/screenshot of functional testing of the feature to the JIRA card.

• Push & Open PR: Push to your fork and open a Pull Request on GitHub.

• All Pull Requests must include detailed description and  screenshots of UI change if applicable.

• Link to Jira: Paste the PR link into the Jira ticket and move the ticket status to "Under Review."Wait for Peer Review: Bahmni technical team will review your code. They may request changes if applicable.

• Merging: Once approved, a maintainer will merge your PR. You should then Close the Jira ticket.

Final merge approval requires:

• Bahmni Product Team review

• UX approval

• Technical approval

• QA validation (if applicable) 

• Signed CLA

Merge into Main Branch & Sanity Testing

Once all approvals are completed and CI checks are passed, the designated maintainer merges the contribution into the main branch and does post-merge sanity testing.

Post-Merge Sanity Testing

A basic sanity check must be performed to ensure:

• The application builds successfully

• Affected modules function as expected

• No regressions are introduced

• Critical workflows remain stable

Guideline Review

 These guidelines may be updated by the Bahmni Product Team in consultation with:

• Product Advisory Team

• UX Leadership

• Technical Steering Representatives