...
4: Pull against master. Always create pull requests on OpenMRS's master branch, unless the ticket description or comments specifically say otherwise. The reviewer of the pull request will always take care of backporting your changes to other branches, whenever necessary. In theory below the title of your pull request in Github, there should be a line saying something like 'XYZ wants to merge 1 commit into openmrs:master from XYZ:master'
5: Update first. Pull the latest changes from upstream and resolve conflicts if any. Use this command: git pull --rebase upstream master
Although you may have run this command as you started working on the ticket, you need to run it again immediately before creating the pull request. The reason for this is that there could be changes committed upstream during the time when you were working on the ticket. If you find yourself taking more than a day to complete a ticket, ensure that at the beginning of each day you work on the ticket, you pull the latest changes by running this same command.
...
7: Follow our coding conventions. Make sure you have read and followed our Coding Conventions. Please read them carefully and check the diff of your commit. Make sure your IDE is properly configured as explained. This helps reduce the time we need to review your code.
8: Avoid a noisy pull request. When committing, you may at times see files to be committed, which you did not intentionally change. Some could simply have formatting changes as a result of running mvn clean install. Please ensure that you do not include any such files in your commit.
9: Squash! The best practice is to commit at the level of an idea (feature/fix). While you may have made 10+ commits while you worked, before you submit a pull request, make yourself look even smarter as if you knew how to do it all at once by "squashing" your changes into one that addresses the ticket. For example: git rebase -i HEAD~3, where the "3" in HEAD~3 is refers to the number of prior commits you want to squash and then git commit.[ref]
Large features may be done across a handful of commits, but most bug fixes and small features can be squashed into a single commit, making the commit history easier to follow.
Consider squashing when creating a pull request; don't worry about squashing subsequent commits performed in response to the reviewer(s) comments. Ultimately, the person merging the pull request will perform a "squash on merge" via GitHub to make the final result appear as a single, clean commit.
109: Help us help you. Use a meaningful message for the pull request. This message should tell us what the pull request is all about, and include the ticket number. If you are not sure of what this message should be, at least use the ticket summary, as it appears in JIRA.
1110: JIRA workflow. Click the "Request Code Review" or "Ready for Testing" button in JIRA for the ticket to notify us that it is ready for review. Remember to include the pull request URL on the ticket, as a comment. Please do not put the ticket state in "CODE REVIEW (POST-COMMIT). This will be done after merging your changes by whoever will have reviewed them. If it is a reference application project, you will instead click the "Ready for Testing" button.
1211: Use JIRA. If your changes have anything to do with the user interface, do not attach the screenshot to the pull request. Instead, attach it to the JIRA ticket. When adding the attachment, include a comment to state the name of the attached file, just in case the ticket gets more than one. If these are changes for an Open Web App, remember to attach the compiled app, on the ticket.
1312: Avoid multiple pull requests for the same ticket. In most cases, you don't need to create more than one pull request for the same ticket unless there is something wrong you did while creating it that you can't change. But if you are just making code changes to the original pull request you submitted, all you have to do is commit to the same branch linked to the pull request, once you push the code to your remote branch, GitHub will automatically pick up the new changes and update the pull request. The only time you don't have to continue with the same pull request is when it has been merged or closed.
1413: Replacing a pull request. If you decided to create a new pull request for the same ticket, please close the old pull request add a comment for why you are closing it, and point to the new pull request in your comment.
1514: Abandoning a ticket. If you decide not to do any more work on a ticket, either because of lack of time, or any other reason, remember to unassign yourself from it such that it becomes available to someone else to take it over from where you left. If during the course of working on it, you discover something that may be useful to whoever takes it up, share that as comments on the ticket. If you had attempted to open any pull request, remember to also close it with a comment stating why.
1615: GitHub Actions build failures. After creating a pull request, check to ensure that GitHub Actions builds successfully. If the build fails, click the "Details" link next to it for details regarding the failure. This mostly happens if you forget to run "mvn clean install" to ensure that all tests pass before committing.
Lastly, please make sure that you have the Using Git page, especially the "Submit the code" section.