Contributing to RAJA¶
Since RAJA is a collaborative open source software project, we embrace contributions from anyone who wants to add features or improve its existing capabilities. This section describes basic processes to follow for individuals outside of the core RAJA team to contribute new features or bugfixes to RAJA. It assumes you are familiar with Git, which we use for source code version control, and GitHub, which is where our project is hosted.
This section describes development processes, such as:
- Making a fork of the RAJA repository
- Creating a branch for development
- Creating a pull request (PR)
- Tests that your PR must pass before it can be merged into RAJA
Forking RAJA¶
If you are not a member of the LLNL organization on GitHub and of the core RAJA team of developers, then you do not have permission to create a branch in the RAJA repository. This is due to the policy adopted by the LLNL organization on GitHub in which the RAJA project resides. Fortunately, you may still contribute to RAJA by forking the RAJA repo. Forking creates a copy of the RAJA repository that you own. You can push code changes on that copy to GitHub and create a pull request in the RAJA project.
Note
A contributor who is not a member of the LLNL GitHub organization and the core team of RAJA developers cannot create a branch in the RAJA repo. However, anyone can create a fork of the RAJA project and create a pull request in the RAJA project.
Developing RAJA Code¶
New features, bugfixes, and other changes are developed on a feature branch.
Each such branch should be based on the RAJA develop
branch. For more
information on the branch development model used in RAJA, please see
RAJA Branch Development. When you want to make a contribution, first ensure
you have an up-to-date copy of the develop
branch locally:
$ git checkout develop
$ git pull origin develop
Developing a Feature¶
Assuming you are on the develop branch in your local copy of the RAJA repo, and the branch is up-to-date, the first step toward developing a RAJA feature is to create a new branch on which to perform your development. For example:
$ git checkout -b feature/<name-of-feature>
Proceed to modify your branch by committing changes with reasonably-sized
work portions (i.e., atomic commits), and add tests that will exercise your
new code. If you are creating new functionality, please add documentation to
the appropriate section of the RAJA User Guide. The source files for the RAJA documentation are maintained in
the RAJA/docs
directory.
After your new code is complete, you’ve tested it, and developed appropriate documentation, you can push your branch to GitHub and create a PR in the RAJA project. It will be reviewed by members of the RAJA team, who will provide comments, suggestions, etc. After it is approved and all CI checks pass, your contribution will be merged into the RAJA repository.
Important
When creating a branch that you intend to be merged into the RAJA repo, please give it a succinct name that clearly describes the contribution. For example, feature/<name-of-feature> for a new feature, bugfix/<fixed-issue> for a bugfix, etc.
Developing a Bug Fix¶
Contributing a bugfix follows the same process as described above. Be sure to indicate in the name of your branch that it is for a bugfix; for example:
$ git checkout -b bugfix/<fixed-issue>
We recommend that you add a test that reproduces the issue you have found
and demonstrates that the issue is resolved. To verify that you have done
this properly, build the code for your branch and then run make test
to
ensure that your new test passes.
When you are done, push your branch to GitHub, then create a PR in the RAJA project.
Creating a Pull Request¶
You can create a pull request (PR)
here. GitHub has a good
PR guide on
PR basics if you want more information. Ensure that the base branch for your
PR is the develop
branch of RAJA.
When you create a RAJA PR, you must enter a description of the contents of the PR. We have a PR template for this purpose for you to fill in. Be sure to add a descriptive title explaining the bug you fixed or the feature you have added and any other relevant details that will assist the RAJA team in reviewing your contribution.
When a PR is created in RAJA, it will be run through our automated testing processes and be reviewed by RAJA team members. When the PR passes all tests and it is approved, a member of the RAJA team will merge it.
Note
Before a PR can be merged into RAJA, all CI checks must pass and the PR must be approved by a member of the core team.
Tests¶
RAJA uses multiple continuous integration (CI) tools to test every pull request. See Continuous Integration (CI) Testing for more information.
All RAJA tests are in the RAJA/test
directory and are split into
unit tests and functional tests. Unit tests are intended to test basic
interfaces and features of individual classes, methods, etc. Functional tests
are used to test combinations of RAJA features. We have organized our
tests to make it easy to see what is being tested and easy to add new tests.
For example, tests for each programming model back-end are exercised using
the same common, parameterized test code to ensure back-end support is
consistent.
Important
Please follow the sub-directory structure and code implementation
pattern for existing tests in the RAJA/test
directory when
adding or modifying tests.
Testing Pull Requests from Branches in Forked Repositories¶
Due to LLNL security policies and RAJA project policies, only a PR created by someone on the RAJA core development team will be run automatically through all RAJA CI tools. In particular, a PR made from branch on a forked repository will not trigger Gitlab CI checks. Gitlab CI on internal LLNL platforms will only be run on PRs that are made from branches in the GitHub RAJA repository. This may change in the future to make it easier to work with PRs from contributors that are not members of the LLNL organization on GitHub.
Note
RAJA core team members:
To facilitate testing contributions in PRs from forked repositories, we maintain a script to pull a PR branch from a forked repo into the RAJA repo. First, identify the number of the PR. Then, run the script from the top-level RAJA directory:
$ ./scripts/make_local_branch_from_fork_pr -b <PR #>
If successful, this will create a branch in your local copy of the
RAJA repo labeled pr-from-fork/<PR #>
and you will be on that
local branch in your checkout space. To verify this, you can run
the following command after you run the script:
$ git branch
You will see the new branch in the listing of branches and the branch you are on will be starred.
You can push the new branch to the RAJA repo on GitHub:
$ git push origin <branch-name>
and make a PR for the new branch. It is good practice to reference the original PR in the description of the new PR to track the original PR discussion and reviews.
All CI checks will be triggered to run on the new PR made in the RAJA repo. When everything passes and the PR is approved, it may be merged. When it is merged, the original PR from the forked repo will be closed and marked as merged unless it is referenced elsewhere, such as in a GitHub issue. If this is the case, then the original PR (from the forked repo) must be closed manually.