Journey of Working on an OpenMRS JIRA Ticket and Creating a Pull Request

Introduction

This wiki documents my journey of working on an OpenMRS JIRA ticket and making a pull request (PR). As a beginner, I encountered several challenges, and this guide is designed to help newcomers navigate the process smoothly. By sharing my experiences, I hope to inspire and assist others in successfully contributing to OpenMRS.

Step 1: Getting Started with JIRA

1.1 Understanding JIRA Tickets

Before starting, ensure that the issue you want to work on has an existing JIRA ticket.
If no ticket exists, create one and wait for it to be assessed before proceeding.
Tickets typically go through different statuses: "Needs Assessment" → "In Backlog" → "Ready for Work".
Once a ticket is "Ready for Work" or "Waiting for Dev", you can claim it by clicking the "Claim Issue" button.
Always reference the OpenMRS JIRA guide: OpenMRS JIRA

1.2 Challenges Faced

Issue: Claiming a ticket without assessment
- Solution: Always wait for ticket assessment; rushing may result in wasted effort.
Issue: Not knowing which files to modify
- Solution: Read through ticket comments; maintainers often provide hints.

Step 2: Setting Up the Development Environment

2.1 Cloning the Repository

# Fork OpenMRS first, then clone your fork

git clone https://github.com/YOUR_GITHUB_USERNAME/openmrs-core.git
cd openmrs-core

git remote add upstream https://github.com/openmrs/openmrs-core.git

2.2 Creating a New Branch

# Ensure you're on an updated master branch
git checkout master
git pull --rebase upstream master

# Create a new branch using the ticket ID
git checkout -b TICKET-ID

2.3 Challenges Faced

Issue: Cloning the wrong repository
- Solution: Ensure you fork OpenMRS first and then clone your fork.
Issue: Branching off an outdated master
- Solution: Always pull the latest changes using git pull --rebase upstream master.

Step 3: Writing Code and Following Conventions

3.1 Writing Code

Follow OpenMRS coding conventions: Coding Standards
Use meaningful variable names and comments.
Run formatting tools to ensure code consistency.

3.2 Running Tests

# Run Maven build to ensure all tests pass
mvn clean package

3.3 Challenges Faced

Issue: Tests failing locally
- Solution: Read error logs carefully; check if dependencies are installed.
Issue: Formatting errors
- Solution: Run mvn clean install before committing changes.

Step 4: Creating a Pull Request

4.1 Pushing Changes

# Add and commit changes
git add .
git commit -m "TICKET-ID: Brief description of fix"

git push origin TICKET-ID

4.2 Opening a Pull Request

Go to your GitHub fork.
Click New Pull Request.
Ensure the PR is against openmrs:master.
Include the ticket link in the PR description: OpenMRS JIRA
Click Create Pull Request.

4.3 Challenges Faced

Issue: PR mixed with unwanted commits
- Solution: Always create new branches from an updated master.
Issue: PR not linked to JIRA
- Solution: Mention the ticket ID in the PR title and description.

Step 5: Handling PR Reviews

5.1 Responding to Feedback

Be open to suggestions from maintainers.
Make changes in the same branch; GitHub automatically updates the PR.

5.2 Challenges Faced

Issue: Unclear review comments
- Solution: Ask maintainers for clarification in the PR discussion.
Issue: Too many commits in PR
- Solution: Squash commits before pushing (git rebase -i HEAD~n).

Step 6: Merging and Closing the Ticket

6.1 Once PR is Approved

A maintainer will merge your PR.
Close the JIRA ticket and mark it as resolved.
Update any additional documentation if required.

6.2 Challenges Faced

Issue: PR remains unmerged for long
- Solution: Politely follow up with maintainers.

Conclusion

Working on an OpenMRS JIRA ticket as a beginner can be challenging but rewarding. By following the structured approach outlined here, you can navigate the process smoothly. Remember to be patient, learn from challenges, and continuously improve. Happy coding!