Getting your code and documentation into PETSc¶
PETSc uses git, GitLab, and its testing system, for its source code management. All new code in PETSc is accepted via merge requests (MRs).
By submitting code, the contributor gives irretrievable consent to the redistribution and/or modification of the contributed source code as described in the PETSc open source license.
Integration branches¶
release
¶
The release
branch contains the latest PETSc release including bug-fixes.
Bug-fix branches for the release should start from release
, along
with most documentation fixes.
$ git fetch
$ git checkout -b yourname/fix-component-name origin/release
Bug-fix updates, about every month or so, (e.g. 3.14.1) are tagged on release
(e.g. v3.14.1).
main
¶
The main
branch contains all features and bug-fixes that are believed to be
stable and will be in the next release (e.g. version 3.15). Users developing software based
on recently-added features in PETSc should follow main
.
New feature branches and bug-fixes for main
should start from main
.
$ git fetch
$ git checkout -b yourname/fix-component-name origin/main
Before filing an MR¶
Read the PETSc Style and Usage Guide.
Start a new feature branch and make your changes.
If your contribution can be logically decomposed into 2 or more separate contributions, submit them in sequence with different branches and merge requests instead of all at once.
Include tests which cover any changes to the source code.
Run the full test suite on your machine.
$ make alltests TIMEOUT=600
Run the source checkers on your machine.
$ make checkbadSource $ make lint
Create a clean commit history, ensuring that the commits on your branch present a logical picture of your new development.
Submitting an MR¶
git push
prints a URL that directly starts a merge request.
Alternatively, use GitLab’s web interface.
The default target branch is
main
; if your branch started fromrelease
, select that as the target branch.If the merge request resolves an outstanding issue, include a closing pattern such as
Closes #123
in the MR’s description to close the issue once the MR is merged 1 .
For MRs from forks:
Select the correct target repository
petsc/petsc
along with the target branch.
If you have developer access:
Select appropriate labels including a workflow label.
If you do not have developer access:
Once submitted, if needbe, @-mention one of the developers in a comment so that they can assign someone to the MR. This person is responsible for adding labels, running pipelines, and generally assisting with the MR.
Docs-only MRs¶
For changes only to documentation, add the docs-only
label, which will
trigger a modified pipeline to automatically build a preview of the documentation.
Any warnings from Sphinx will cause the pipeline to fail. Once completed, click “View App”.
Documentation changes should be made to the release branch in the typical case that they apply to the release version of PETSc (including changes for the website). Changes related only to new features in the main branch should be applied there.
Testing¶
The PETSc continuous integration (CI) pipeline runs the entire test suite on around 60 configurations of compilers, options, and machines, and takes about 3 hours. Pipelines can be started and controlled from the “Pipelines” tab on the MR page. This requires developer access, so if needbe, @-mention the assigned developer to remind them.
Since the full pipeline requires many resources, when a merge request is created, a pipeline is triggered but you must manually un-pause it for the tests to run. For detailed instructions and help diagnosing failures, see Working with Pipelines.
MR reviewing¶
Once the MR has passed the pipeline, it is ready for review.
The submitter (or assignee for MRs from forks) must change the workflow label to workflow::Review
.
It is the submitter’s responsibility to track the progress of the MR and ensure it gets merged.
If the pipeline detect problems it is the submitter’s responsibility to fix the errors.
Reviewers will comment on the MR, either in the overview or by clicking next to specific lines in the changes for a commit or the overall MR 2 3. Often, the submitter will need to update their branch in response to these comments, and re-run the pipeline.
Gitlab MRs use “threads” to track these discussions. When responding to a thread make sure to use “Reply” box for that thread; do not introduce a new thread or a comment.
The submitter must mark threads as resolved as they fix the related problem.
If the submitter feels the MR is not getting reviewed in a timely manner they may assign potential reviewers to the MR and request in the discussion these same people to review by @-mentioning them.
When reviewers believe an MR is ready to be merged, they approve it. You can determine who must approve your MR by clicking on the “Viewer eligible reviewers” towards the top of the “Overview” page.
When the merge has been approved by a sufficient number of reviewers, the pipeline passes, new commits have been properly rearranged if needbe, and all threads have been resolved, the submitter (or assignee for MRs from forks) must set the label to workflow::Ready-For-Merge. An integrator will then merge the MR.
Workflow labels¶
The MR process, including testing and reviewing, is managed by the workflow labels that indicate the state of the MR. Every MR should have exactly one of these labels.
The standard workflow has three steps.
workflow::Pipeline-Testing
The user is testing their branch. Generally, unless asked, no one else has a reason to look at such an MR.workflow::Review
The user would like their branch reviewed.workflow::Ready-For-Merge
The MR has passed all tests, passed the review, has no outstanding threads, and has a clean commit history.
For MRs within the PETSc repository, the submitter of the MR is responsible for changing the workflow
label appropriately during the MR process.
For MRs from forks, the assignee is responsible.
Some MRs may begin with either of the following workflow
states.
workflow::Request-For-Comment
The branch is not being requested to be merged but the user would like feedback on the branch. You do not need to test the code in this state.workflow::In-Development
The developer is working on the branch. Other developers not involved in the branch have generally no reason to look at these MRs.
Both of these should also be marked as “Draft” on the MR page.
These two states are usually eventually converted by the developer to workflow::Review
.
You can run the pipelines on an MR in any workflow state.
Merge request management¶
At any given time, at least one of the Current Core Developers is an “MR Shepherd” and ensures that open merge requests progress through the review process, examining open merge requests and taking appropriate action.
MR State |
Action |
---|---|
Missing a workflow label |
Add an appropriate label, or label |
From an external person without an assignee |
Assign an appropriate developer or ask the submitter to choose someone |
From an external person who seems stuck |
Remind the assignee |
If MRs are inactive for too long, remind the submitter, assignee(s), reviewer(s), or integrator(s) of actions to take.
If the submitter must take action, change the label to workflow::Waiting-on-Submitter
.
MR state |
Inactivity threshold |
---|---|
|
One week |
|
One week |
|
One week |
|
One month |
|
One month |
|
One month |
All others |
One year |
If a submitter has been unresponsive for a year,
close the MR, label workflow::Inactive-closed
,
and let the submitter know that they may reopen if desired.
Footnotes
- 1
Unfortunately, these closing patterns only work for MRs to a single default branch (
main
), so you must manually close related issues for MRs torelease
.- 2
When introducing a new topic (thread) in reviewing an MR, one should submit with “Start Review” and not “Comment”.
- 3
A particularly useful feature is the “insert suggestion” button in the comment box, to suggest an exact replacement on a line.