SubmittingPullRequests

In the Open MPI project, we track three main things:

1. Bugs and enhancement requests: These are tracked in the Github Issues tracker in the ompi repository.
2. Requests to get code into the release branches: These are tracked in the Pull Requests to release branches in ompi repository.
3. RFCs (i.e., "hey, I've got an idea -- what do people think about this?"): These are typically tracked in the Pull Requests in the ompi repository.

You must have a Github account to submit bugs or pull requests.

Submitting a Pull Request

Pull Requests for the Open MPI release branches are filed via developer's personal Github repositories, against one or more release branches in the ompi repository.

Generally, an Open MPI developer writes new code and pushes it to the main branch on the main ompi repo. To get that code into a release branch, the developer must submit a Pull Request against a particular release branch to get it pulled in to that release branch.

---

NOTE: Pull requests on a release branch must include a hash reference in the body/comments corresponding to the commit(s) on ompi:main from which it is derived, OR indicate that this is solely a release branch bug (i.e., there's no corresponding commit on ompi:main because the bug doesn't/didn't exist on ompi:main). Specifically: the intent is that code only goes in to a release branch after it has been committed to the ompi:main development branch.

NOTE: In general, pull requests to a release branch must reference an open issue tracking the bug / feature that is being added to the release branch. This rule is generally loosely enforced early in a branch lifespan, but is likely to be a requirement as the first release nears.

---

General scheme

The general scheme of how this works is:

1. If it's a bug, Developer opens an issue and assign it herself. If there is already an issue open, Developer assigns it to herself.
2. Developer adds labels to issue to track where change needs to be made (Target: main, Target: 3.0.x, etc.). If the bug should block releases, please also add the Blocker label.
3. Developer creates a local fork (the little fork button in the upper right hand corner of the ompi repo
4. Developer creates a topic branch in their local fork based off the target branch (likely starting with main)
5. Developer posts a PR to main, referencing the issue (ie Refs: #1234, it's also ok to use Closes: #1234 here). If the bug is only on a release branch, this step is skipped.
6. Developer signs the git commit (via -s option to git commit to indicate that they have read and understand the Contributor's Declaration -- see Administrative-rules )
7. Iterate on comments / etc.
8. After the PR is pushed to main, Developer cherry-picks the changes from main to new local topic branches based off the target release branch. Please use git cherry-pick -x when creating PRs to release branches so that we can map commits on release branches to commits on main (even if there are some merge conflicts that need to be resolved).
9. Developer files a Pull Request to bring the code to the relevant release branch in the ompi repo. The PR should have a label for the target branch, a milestone for the next release in that series, and (if needed) the Blocker label.
10. Developer / Release manager should remove the target labels on the issue when the change is pushed to the given release branch (ie, remove Target: 3.0.x when merged into the v3.0.x release branch).
11. When changes have been merged to all the target branches, the issue can be closed (PRs will autoclose when merged).

Once the Pull Request against the main branch is filed, there can be discussion on the PR. It is critical that any changes resulting from the discussion be first committed to the main branch in the ompi repo on Github so they can be tested by the community prior to merging the corresponding changes into a release branch.

An example of this developer process -- and its associated git commands -- is shown on this wiki page.