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 master 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:master from which it is derived, OR indicate that this is solely a release branch bug (i.e., there's no corresponding commit on ompi:master because the bug doesn't/didn't exist on ompi:master). Specifically: the intent is that code only goes in to a release branch after it has been committed to the ompi:master 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: master, 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 master)
5. Developer posts a PR to master, 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. Iterate on comments / etc.
7. After the PR is pushed to master, Developer cherry-picks the changes from master to new local topic branches based off the target release branch.
8. 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.
9. 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).
10. 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 master 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 master 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.

We are working on a GitHub bot to automate checking many of the rules in this wiki, but it has not yet been deployed. It will also automate removing target labels from issues and prompting to close tickets when there are no more target labels. Yay automation?