CONTRIBUTING.md

Contributing to OpenCoarrays

Download this file as a PDF document here.

• Reporting Defects
• Requesting Enhancements
• Helping Out
  • Outside Contributors
• OpenCoarrays Branches
  • Master

Reporting Defects

If you encounter problems during the course of Installing OpenCoarrays or using OpenCoarrays, please take the following actions:

1. Search the issues page (including closed issues) to see if anyone has encountered the same problem. If so add your experience to that thread.
2. Search the mailing list to see if the issue has been discussed there.
3. If unable to resolve the problem, please file a new issue and be sure to include the following information:
   • Fortran compiler used with OpenCoarrays, including version number
   • C compiler used to build OpenCoarrays
   • Communication library being used e.g., MPICH, OpenMPI, MVAPICH or GASNet and the version number
   • Open Coarrays version number, or if building from master, commit SHA (caf --version should give you the most detailed version information, whether built from the git repository or a release tarball.)
   • Conditions required to reproduce the problem:
     • OS, name and version
     • Architecture of machine/hardware the code is running on
     • Number of MPI ranks/processing elements/coarray images being run on
     • How the code was compiled, including all flags and commands
     • Minimal reproducer code (a few lines) required to trigger the bug
4. Any help you can provide diagnosing, isolating and fixing the problem is appreciated! Please see the helping out section for more information.

An issue template is in the .github folder to help ensure compliance, and adequate information is provided.

Requesting Enhancements

If you would like OpenCoarrays to support a new communication library, OS, or have any other suggestions for its improvement, please take the following action:

1. Search the issues page and mailing list to see if the feature or enhancement has already been requested.
2. If not, please file a new issue, and clearly explain your proposed enhancement.
3. If you are able to help out in the implementation or testing of the proposed feature, please see the helping out section of this document.

Helping Out

Thank you for your interest in contributing to OpenCoarrays! Your help is very appreciated! Below are some tips and guidelines to get started.

Outside Contributors

Here is a checklist to help you get started contributing to OpenCoarrays and walk you through the process:

• Take a look at the issues page. Make sure that you're not about to duplicate someone else's work.
• Post a new issue discussing the changes you're proposing to implement; whether bug fix(es) or enhancement(s)/feature request(s)--or give us a heads up that you are going to start work on an open issue.
• Please fork the OpenCoarrays repo to your private repository.
• Sign the Contributor License Agreement (CLA) by clicking the "details" link to the right of the license/cla check and following the directions on the CLA assistant web page
• Follow the guidelines for [all contributors], listed below

All Contributors

• Next Create a branch and make sure to include the issue number(s) in the branch name, for example: issue-53-fix-install-dir-logic or fix-typo-#23
• Configure your local repository with the white space settings (and git hooks to enforce these) by running ./developer-scripts/setup-git.sh. (Add the --global flag to this script to use these settings across all your new repositories, or newly cloned repositories.) Pull requests introducing errant spaces and non-printing characters will not be accepted until these problems are addressed.
• Make your changes and commit them to your local repository, following these guidelines:
  • Each commit should be a logically atomic, self-consistent, cohesive set of changes.
  • The code should compile and pass all tests after each commit.
  • The code should be legible and any non-obvious features commented appropriately.
  • All unit tests should be run locally and pass. (Run ctest in the build directory.)
  • Tests should be added for new features and significant new code, steps should be taken to ensure that the total coverage remains the same or increases.
  • The commit message should follow these guidelines:
    • First line is directive phrase, starting with a capitalized imperative verb, and is no longer than 50 characters summarizing your commit
    • Next line, if necessary is blank
    • Following lines are all wrapped at 72 characters and can include additional paragraphs, bulleted lists, etc.
    • Use Github keywords where appropriate, to indicate the commit resolves an open issue.
    • Please do your best to keep a clean and coherent history. git add -p ..., git commit --amend and git rebase --interactive <root-ref> can be helpful to rework your commits into a cleaner, clearer state.
• Next, open up a pull request against the appropriate base branch, master of sourceryinstitute/OpenCoarrays
  • In the title, please include the text issue-<#>, where <#> is replaced by the issue number of the feature request or bug report corresponding to this PR.
  • If the PR is a work in progress, please add WIP: ... to the title, and rename it deleting that text once the PR is ready to be merged.
  • If the PR is problematic for any reason please add DO NOT MERGE to the title, until it is either abandoned or fixed.
• Please be patient and responsive to requests and comments from SourceryInstitute (SI) team members. You may be asked to amend or otherwise alter commits, or push new commits to your branch.

Contributors with Write Access

SI team members and collaborators with push access must wait 24 hours before self-approving pull requests via pullapprove comment or Github code review so that someone else has the chance to review the proposed changes, and provide a formal code review. Due to the small size of the development team, it is unrealistic to require a code review under all circumstances. This policy ensures that there is at least an opportunity for a formal code review by another developer.

OpenCoarrays Branches

OpenCoarrays uses the Github flow workflow. There are a number of resources available to learn about the Github flow workflow, including a video. The gist of it is that the master branch is always deploy-able and deployed. The means at anytime, a new tagged release could be shipped using the master branch.

Master

The master branch should remain in pristine, stable condition all of the time. Any changes are applied atomically via pull requests. It should be assumed that users are using the code on this branch, and great care should be taken to ensure its stability. Most bug fixes and incremental improvements will get merged into the master branch as soon as they are deemed ready for production.

Through put

Coverage

---