From 3f5e9e13cd1f698c54ccacd11c6ba61b767abc79 Mon Sep 17 00:00:00 2001 From: Brandon Barker Date: Fri, 27 Sep 2024 13:57:39 -0400 Subject: [PATCH] contributing --- CONTRIBUTING.md | 101 +++++++++++++++++++++----------- doc/sphinx/src/contributing.rst | 17 ++++-- 2 files changed, 79 insertions(+), 39 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1fea1219..329e38bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,44 +1,82 @@ -# `Phoebus` Development Model +# Contributing +--- ----- -For the purpose of our development model, we label _Contributors_ or _Maintainers_ of `Phoebus`. -Below we describe these labels and the process for contributing to `Phoebus`. +To contribute to `Phoebus`, feel free to submit a pull request or open +an issue. -## Becoming a Contributor -We welcome contributions from scientists from a large variety of relativistic astrophysics. -New users are welcome to contributions to `Phoebus` via the *Contributors* process. -Contributors with 6 merged pull requests into the `main` branch (over a minimum of 6 months) -will be eligible to join as a *Maintainer* of `Phoebus` with additional repository access and roles. -However, final approval of *Maintainer* status will require a unanimous approval by vote by existing *Maintainers*, -a necessary step to ensure the safety and integrity of the code base for all users of `Phoebus`. +1. Create a new fork of `main` where your changes can be made. +2. After completing, create a pull request, describe the final approach + and ensure the branch has no conflicts with current Regression Tests + and Formatting Checks. +3. Assign external reviewers (a minimum of 1, one of which should be a + Maintainer, and which cannot be the contributor). Provide concise + description of changes. +4. Once comments/feedback is addressed, the PR will be merged into the + main branch and changes will be added to list of changes in the next + release. +5. At present, Releases (with a git version tag) for the `main` branch + of `Phoebus` will occur at a 6 to 12 month cadence or following + implementation of a major enhancement or capability to the code + base. -The _Maintainers_ of `Phoebus` consist of the original developers of the code and those that -have a demonstrated history in the development of `Phoebus` prior to the implementation of -the _Development Model_ described here. Maintainers hold admin access, serve consistently as -reviewers for pull requests, and are in charge of the maintaining, deployment, and improvement of efforts -towards: regression testing, documentation, science test cases (gold standards), and continuous integration. +*Maintainers* of `Phoebus` will follow the same process for +contributions as above except for the following differences: they may +create branches directly within `Phoebus`, they will hold repository +admin privileges, and actively participate in the technical review of +contributions to `Phoebus`. -To maintain their active status as Maintainer, all members will agree to adhere to our -Community Code of Conduct and adhere to a Memorandum of Understanding described [here](GOVERNANCE.md). +## Pull request protocol -# Contributing to `Phoebus` +When submitting a pull request, there is a default template that is +automatically populated. The pull request should sufficiently summarize +all changes. As necessary, tests should be added for new features of +bugs fixed. -***Contributors***: (process for most users of `Phoebus`) ---- +Before a pull request will be merged, the code should be formatted. We +use clang-format for this, pinned to version 12. The script +`scripts/bash/format.sh` will apply `clang-format` to C++ source files +in the repository as well as `black` to python files, if available. The +script takes two CLI arguments that may be useful, `CFM`, which can be +set to the path for your clang-format binary, and `VERBOSE`, which if +set to `1` adds useful output. For example: + +``` bash +CFM=clang-format-12 VERBOSE=1 ./scripts/bash/format.sh +``` -1. Create a new fork of `main` where your changes can be made. -2. After completing, create a pull request, describe the final approach and ensure the branch has no conflicts with current Regression Tests and Formatting Checks. -3. Assign external reviewers (a minimum of 1, one of which should be a Maintainer, and which cannot be the contributor). Provide concise description of changes. -4. Once comments/feedback is addressed, the PR will be merged into the main branch and changes will be added to list of changes in the next release. -5. At present, Releases (with a git version tag) for the `main` branch of `Phoebus` will occur at a 6 to 12 month cadence or following implementation of a major enhancement or capability to the code base. +## Test Suite -*Maintainers* of `Phoebus` will follow the same process for contributions as above except for the following differences: -they may create branches directly within `Phoebus`, they will hold repository admin privileges, -and actively participate in the technical review of contributions to `Phoebus`. +Several sets of tests are triggered on a pull request: a static format +check, a docs buld, and a suite of unit and regression tests. These are +run through github's CPU infrastructure. These tests help ensure that +modifications to the code do not break existing capabilities and ensure +a consistent code style. +## Becoming a Maintainer +For the purpose of our development model, we label *Contributors* or +*Maintainers* of `Phoebus`. Below we describe these labels and the +process for contributing to `Phoebus`. -### List of Current Maintainers of `Phoebus` +We welcome contributions from scientists from a large variety of +relativistic astrophysics. New users are welcome to contributions to +`Phoebus` via the process above. Contributors with 6 merged +pull requests into the main branch (over a minimum of 6 months) will be +eligible to join as a *Maintainer* of `Phoebus` with additional +repository access and roles. However, final approval of *Maintainer* +status will require a approval by vote by existing +*Maintainers*, a necessary step to ensure the safety and integrity of +the code base for all users of `Phoebus`. + +The *Maintainers* of `Phoebus` consist of the original developers of the +code and those that have a demonstrated history in the development of +`Phoebus` prior to the implementation of the *Development Model* +described here. Maintainers hold admin access, serve as reviewers for +pull requests, and are in charge of the maintaining, deployment, and +improvement of efforts towards: regression testing, documentation, +science test cases (gold standards), and continuous integration. + +## List of Current Maintainers of Phoebus --- | Name | Handle | Team | |----------|--------------|------------| @@ -49,6 +87,3 @@ and actively participate in the technical review of contributions to `Phoebus`. | Jonah Miller | [@Yurlungur](https://www.github.com/Yurlungur) | Los Alamos National Lab | | Jeremiah Murphy | [@curiousmiah](https://www.github.com/curiousmiah) | Florida State University | | Ben Ryan | [@brryan](https://www.github.com/brryan) | Los Alamos National Lab | - -* * * -This article is cleared for unlimited release, LA-UR-24-25222. diff --git a/doc/sphinx/src/contributing.rst b/doc/sphinx/src/contributing.rst index f02c530c..beaeb94e 100644 --- a/doc/sphinx/src/contributing.rst +++ b/doc/sphinx/src/contributing.rst @@ -64,6 +64,12 @@ There are two primary categories of tests written in ``Phoebus``: * Unit tests * Regression tests +Unit +^^^^ + +Regression +^^^^ + .. todo:: This section is incomplete. @@ -169,23 +175,22 @@ relativistic astrophysics. New users are welcome to contributions to pull requests into the main branch (over a minimum of 6 months) will be eligible to join as a *Maintainer* of ``Phoebus`` with additional repository access and roles. However, final approval of *Maintainer* -status will require a unanimous approval by vote by existing +status will require a approval by vote by existing *Maintainers*, a necessary step to ensure the safety and integrity of the code base for all users of ``Phoebus``. The *Maintainers* of ``Phoebus`` consist of the original developers of the code and those that have a demonstrated history in the development of ``Phoebus`` prior to the implementation of the *Development Model* -described here. Maintainers hold admin access, serve consistently as +described here. Maintainers hold admin access, serve as reviewers for pull requests, and are in charge of the maintaining, deployment, and improvement of efforts towards: regression testing, documentation, science test cases (gold standards), and continuous integration. -To maintain their active status as Maintainer, all members will agree to -adhere to our Community Code of Conduct and adhere to a Memorandum of -Understanding described :ref:`here `. - +Maintainers are excepted to make a good faith effort to adhere to +:ref:`these suggestions ` in order to maintain a supportive and +productive environment. List of Current Maintainers of Phoebus ------------------------------------------