Guidance for contributors

UCX uses Git for source code management, Jenkins for continuous integration, and Google’s C++ test framework for unit testing.

General guidelines

1. Follow the code style and logging style

2. Format the commit message as follows:
   MODULE/UNIT1/UNIT2/..: Summary
   for example:
   UCT/SHM: Fix shared memory deadlock.

3. Everything should be submitted as a pull request ("PR") from a branch.
   NO DIRECT PUSH TO MASTER!

4. No PRs over 500 lines of added code.
   3rd party code can be larger, but has to be in a separate PR

5. API changes have to be in a separate PR, which includes only the minimal set of changes required for making the code compile and tests pass. The implementation of new functionality should be a stub.
   API changes have to be approved by bbenton.

6. When both renaming and changing a file, first have a PR to rename the file, and then another PR to make the changes.

7. If you need to fix your PR, there are 2 options: amend (replace) your commit, or add new commit with fixes.

• Before anyone has posted comments on the PR, it's allowed to amend.
  Example: Fixing bugs found in automatic tests.
• If some comments have been posted, the fixes should be in a new commit.
  Reason: Tracking fixes of code review.

Git Workflow to Submit a Feature or Bug Fix

1. [Fork the project] (https://help.github.com/articles/fork-a-repo/) from openucx/ucx to create your copy gituser/ucx

2. Clone the code from gituser/ucx: git clone <XXXX>

3. Create a new branch for your bugfix, feature, or enhancement: git branch topic/bugfix_123

4. Switch your workspace to a newly created branch: git checkout topic/bugfix_123

5. Commit your changes: git commit .

6. Push the changes in your branch (topic/bugfix_123) to your copy gituser/ucx : git push origin topic/bugfix_123 . If the default upstream for the branch is not defined, add -u flag to the push command. The flag sets default upstream for the branch.

7. Submit your change to the openucx/ucx by [opening a pull request] (https://help.github.com/articles/using-pull-requests/). After submitting the PR, the code is reviewed by the reviewers/maintainers. Once the reviewers and authors reach an agreement, the author requests the maintainer to merge the changes.

8. Delete the branch: git push origin :topic/bugfix_123

More details here:

• http://scottchacon.com/2011/08/31/github-flow.html
• https://github.com/blog/1124-how-we-use-pull-requests-to-build-github

Code reviews

1. One or more of UCX maintainers has to approve (:+1:) the PR in order to merge it.

2. Before requesting a review, please make sure the automatic tests pass.
   See the UCX Testing Procedure

3. PRs which are waiting for review should be marked with the label "Ready for review". It's also advisable to tag the relevant reviewer.

4. PRs which were reviewed and currently waiting for a fix and/or response, are marked with "Waiting for Author Response".

Reviewers

Everybody are welcome to post comments on every PR. However a final approval should be given by the maintainers. Also, changes which affect API (especially UCP API) should be coordinated with UCX users.

List of maintainers:

• shamisp - Pavel Shamis, ARM
• yosefe - Yossi Itigin, Mellanox
• bbenton - Brad Benton, AMD (API gatekeeper)
• alex-mikheev - Alex Mikheev, Mellanox
• alinask - Alina Sklarevich, Mellanox
• manjugv - Manjunath Gorentla Venkata, ORNL
• MattBBaker - Mathew Baker, ORNL
• hppritcha - Howard Pritchard, LANL

Primary maintainers per component:

• UCP: yosefe, shamisp.
  Note changes in UCP require an approval from both maintainers.
  Note API changes require an approval from bbenton
• UCS, UCT: yosefe, shamisp
• UCT/ib: yosefe, alex-mikheev
• UCT/shm: alinask, shamisp, manjugv
• UCT/uGNI: hppritcha, manjugv, MattBBaker