Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added contribution and governance documents #64

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
# Contribution Guidance

## Contents

* [Git](#git)
* [Testing](#testing)
* [Code](#code)

## Git

### Branches

All work should be done on a [feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). Feature branch names should be descriptive.

Branches get merged into a parent branch through a GitHub [pull request](https://help.github.com/en/articles/about-pull-requests). For minor features, the pull request can be made directly from the feature branch into the master branch. For major features (e.g., changes that will take several weeks, have several components, and involve multiple developers), there should be a "master feature" branch for that change, and contributions to the "master feature" branch should be done through pull requests into the "master feature" branch. When the major feature is complete, the "master feature" branch will be pulled into the master branch.

To create a branch:

```
git checkout <parent branch>
git pull
git checkout -b <new branch name>
```

### Committing and Pushing Code

There are a few key principles to committing code to the remote repository:

* You are committing working code
* You are committing what you expect to commit
* You are not committing debug code
* You are not committing junk (e.g., whitespace only changes)

These rules do not apply to local commits **as long as you squash/fixup those commits before pushing to the remote repository**.

To commit code locally, do the following:

```
git diff
git add <appropriate files>
git status
git commit -m <commit message>
```

Use the `git diff` command to ensure you are committing what you expect and are not committing debug code or whitespace code.

If you want to push to the remote repository, do the following:

```
git push
```

You may need to do a force push (`git push -f`) if you rebased your branch (see [Creating a Pull Request](#creating-a-pull-request)). **Make sure you are pushing what you expect when you do a force push!!!** You should do this regardless, but need to be especially especially careful when doing a force push. These are dangerous as they modify the remote history. Also ensure that anyone who may be using this branch is aware you are doing a force push because this can mess up their local instance of the repository.


#### Cleaning Up Your Local Commit History Before Pushing

Each commit that gets pushed remotely needs to follow the rules above. If you did some messy commits locally and need to clean them up before pushing to the remote repository, do the following steps.

* Make sure that your latest commit works, has no debug statements, and no junk (e.g., whitespace only changes)
* Squash any commits that have debug statements / extra whitespace / broken code into commits that do not have these.
* Push

This may look like the following:

```
git diff origin/<branch name>
git rebase -i HEAD~<number of commits you have added on top of the remote branch>
git push
```

`git diff origin/<branch name>` performs a diff against the remote version of the branch.

`git rebase -i` opens up an editor (VI if you haven't configured anything else) to allow you to modify the commits. **Only modify local commits**. Follow the instructions in the editor to fixup or squash the commits as appropriate.

### Pull Requests

#### Pull Requests into Master

Pull requests into master should have at least one reviewer from each organization funded by CMS to manage the repository, and should have at least two reviewers total. The reviewers from the funded organizations are expected to submit a review in a timely manner within three business days of the pull request being submitted. If a review needs to be expedited (e.g., a bug fix necessary to meet a CMS deadline), the submitter should communicate directly with the reviewers to ensure that they are aware of the expedited timeline and document this requirement within the pull request. Pull requests that don’t require an expedited review should remain open at least three business days to allow community members to perform a review.

Community members are expected to review pull requests of interest and provide comments regarding their questions or concerns. Both the pull request submitter and the commenter are expected to be responsive to one another, preferably replying within one business day to a comment or response. A reply should at a minimum signal any actions that may be taken.

Exceptions include gemfile updates and config file updates for in incrementing the version numbers. These only require a single reviewer and can be considered a "sanity check" review.

#### Pull Requests into a Feature Branch

The organization responsible for a major feature is responsible for determining how new content will be incorporated into the "master feature" branch. However, we recommend that pull requests into feature branches include at least one reviewer and that the checklist is still completely filled out (see below).

#### Pull Request Checklists

Pull requests include a [checklist](https://github.com/projecttacoma/bonnie/blob/master/.github/PULL_REQUEST_TEMPLATE.md). Each checkbox must be checked. If a checkbox is not applicable to the pull request for some reason, it should still be checked and be noted with "N/A" or a strike-through.

If your pull request is dependent on another pull request in a separate repository, put another checkbox in the checklist ensuring that the other pull request is complete and incorporated and all depedencies are appropriately updated.

#### Best Practices

* Inform the people assigned to your review that they are on point for the review.
* When you have addressed review comments, ping your reviewers for their re-review.
* If you have a PR dependent on another PR, create a new checkbox in your PR that says waiting on the other PR to be merged.

#### Creating a Pull Request

1. Make sure that you're branch is up to date with master (or whatever branch it is being merged into). There are two ways to do this:
* Merge the parent branch in (minor features and commits into "major feature" branches)

This is appropriate if you will later do a "squash merge" when integrating this branch into the parent branch. This should be the case for minor features and for commits into "major feature" branches.
```
git fetch
git merge origin/<parent branch>
```
* Rebase onto the top of the parent branch ("major feature" branches)
This is appropriate if you want to retain your commit history in a logical sequence. This puts all of the branch's commits on top of the parent branch's commits.
```
git fetch
git rebase origin/<parent branch>
```
1. Run all tests.
1. Confirm test coverage has not gone down (and has hopefully gone up), and that all new or modified code is covered by tests.
1. Commit and push the code following the instructions in [Committing and Pushing Code](#committing-and-pushing-code).
1. [Create the pull request on github](https://help.github.com/en/articles/creating-a-pull-request).
1. Fill out the pull request checklist.
1. Assign your reviewers and let them know that they are a reviewer for your pull request.
1. Be responsive to any comments.
1. After your pull request has been approved, ping the team lead to merge the request in. There are two ways to do this:
* Squash merge
This is for minor features into the master branch or for pull requests into a major feature branch.
* Merge
This is for major feature branches where the commit history should be preserved.
## Testing
All new or modified code should be covered by a test when possible. However, being covered is not sufficient. The author and reviewers are expected to ensure that the new or modified code is **actually being tested**, meaning expected and edge cases are being checked.
When the code is overly difficult to create an automated test for (which should ideally only be the case for older code that was not written to be easily tested), then a manual test can be created. The manual test should be in a traceable and repeatable formate (e.g., if JIRA is being used, using JIRA tests).
## Code
### JavaScript
We follow the [ESLint](https://eslint.org/) [AirBnB base](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base) with a few exceptions, which are noted in the .eslintrc.json file.
### Indenting
Indentations should be done using two spaces. This can be configured in your editor so when you press "TAB", two spaces are entered.
125 changes: 125 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# CQM-Execution Governance Model

<sup>*CQM-Execution is a shared library used by the [Cypress](https://cypress.healthit.gov) and [Bonnie](https://bonnie.healthit.gov/) tools.*</sup>

This governance model is based on [OSS Watch's Meritocratic Governance Model](http://oss-watch.ac.uk/resources/meritocraticgovernancemodel) and the [CQFramework Clinical Quality Language Change Management document](https://github.com/cqframework/clinical_quality_language/blob/master/CHANGE_MANAGEMENT.md). It has been heavily modified to meet the needs of a government funded open source project managed by multiple organizations.

## Overview

Centers for Medicare and Medicaid Services (CMS) fund X and Y companies to develop and maintain this repository. This repository is led by X and Y, and maintained by the community, meaning the community may actively contribute to the day-to-day maintenance of the project. The strategic direction and resolution of any disagreements regarding the repository is determined by X and Y, with CMS having the final word. The community guides the decisions of X, Y, and CMS through active engagement and contribution. This document outlines the roles and responsibilities, contribution model, and decision-making process.

## Roles and Responsibilities

### Users

Users are community members who have a need for the project. They are the most important members of the community and without them the project would have no purpose. Anyone can be a user; there are no special requirements.

The project asks its users to participate in the project and community as much as possible. User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to):
* evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising)
* informing developers of strengths and weaknesses from a user perspective
* providing moral support (a ‘thank you’ goes a long way)

Users who continue to engage with the project and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section.

### Contributors

Contributors are community members who contribute in concrete ways to the project. Anyone can become a contributor, and contributions can take many forms. There is no expectation of commitment to the project, no specific skill requirements and no selection process.

In addition to their actions as users, contributors may also find themselves doing one or more of the following:

* supporting new users (existing users are often the best people to support new users)
* reporting bugs
* identifying requirements
* providing graphics and web design
* programming
* assisting with project infrastructure
* writing documentation
* fixing bugs
* adding features

Contributors engage with the project through the issue tracker and mailing list, or by submitting pull requests from a forked repository. Pull requests will be considered for inclusion in the project by existing committers. The developer mailing list is the most appropriate place to ask for help when making that first contribution.

As contributors gain experience and familiarity with the project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for committership.

### Committers

Committers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Committership allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. That is, they have commit rights directly into the repository and do not need to work off of a forked repository.

This does not mean that a committer is free to do what they want. While committership indicates a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release.

Anyone can become a committer; there are no special requirements, other than to have shown a willingness and ability to participate in the project as a team player. Typically, a potential committer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time.

New committers can be nominated by any existing committer. Once they have been nominated, there will be a vote by the project management committee (PMC; see below). Committer voting is one of the few activities that takes place on the project’s private management list. This is to allow PMC members to freely express their opinions about a nominee without causing embarrassment. Once the vote has been held, the aggregated voting results are published on the public mailing list. The nominee is entitled to request an explanation of any ‘no’ votes against them, regardless of the outcome of the vote. This explanation will be provided by a member of the PMC and will be anonymous and constructive in nature.

Nominees may decline their appointment as a committer. However, this is unusual, as the project does not expect any specific time or resource commitment from its community members. The intention behind the role of committer is to allow people to contribute to the project more easily, not to tie them in to the project in any formal way.

It is important to recognize that committership is a privilege, not a right. That privilege must be earned and once earned it can be removed by the PMC (see next section) in extreme circumstances. However, under normal circumstances committership exists for as long as the committer wishes to continue engaging with the project.

### Project Management Committee (PMC)

The project management committee is made up of the leadership teams from X and Y. The PMC has additional responsibilities over and above those of a committer. These responsibilities ensure the smooth running of the project. PMC members are expected to manage new features and functionality, review code contributions, participate in strategic planning, approve changes to the governance model and manage the copyrights within the project outputs.

Members of the PMC make decisions when community consensus cannot be reached. In addition, the PMC has access to the project’s private mailing list and its archives. This list is used for sensitive issues, such as votes for new committers and legal matters that cannot be discussed in public. It is never used for project management or planning.

In rare instances, the PMC may decide to remove a committer’s commit rights. The PMC may choose to remove a committer’s commit rights if they do not follow the code of conduct, submit malicious code, demonstrate continued poor judgment, or other reasons at the PMC’s discretion. The PMC votes on removing commit rights over the private mailing list.

### Sponsor

The Sponsor is the CMS Government Task Lead (GTL) for the X and Y teams. It is possible that there may be multiple Sponsors. In this case, the Sponsors will work closely together in this role. The Sponsor has final say in the strategic direction of the project as well as how disagreements that could not be resolved through the PMC will be resolved.

## Decision-Making Process

Decisions about the project are made by the PMC in coordination with the Sponsor, with the Sponsor having final say. Community members may provide suggestions or ideas regarding the direction of the project for review by the PMC and the Sponsor. Discussions should occur on the public project mailing list as much as possible. However, if a discussion should be limited to input from those in the PMC, it should be done on the public PMC email list to ensure that discussions and decisions will be archived to enable future review. If a discussion must be private for legal or sensitive issues, it should be done on the project’s private mailing list.

Because multiple organizations are being funded by CMS to manage this repository, there may be disagreements between representatives of those organizations within the PMC. If disagreements cannot be resolved within the PMC, they may be escalated to the Sponsor to resolve.

## Support

All participants in the community are encouraged to provide support for new users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project outside of the work funded by CMS is voluntary and is therefore provided as and when time allows. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal.

## Code of Conduct

In support of a healthy and inclusive community, we use and enforce a code of conduct for all members of our community, including committers and PMC members. Our code of conduct is adapted from the Contributor Covenant.

If you encounter any violation of these terms, please contact the PMC Chair or a PMC committee member. All reports will be kept in strict confidence and dealt with promptly.

## Contribution Process

Anyone can contribute to the project, regardless of their skills, as there are many ways to contribute. For instance, a contributor might be active on the project mailing list and issue tracker, or might make pull requests. Decisions within the GitHub repository go through a pull request process described below.

After reviewing the available contribution documentation, the developer mailing list is the most appropriate place for a contributor to ask for help when making their first contribution.

### GitHub Repository Changes

The project uses a stable-trunk methodology, meaning that the master branch must be kept in a releasable state at all times. This is ensured through regression tests and continuous integration is used to check pull requests to the master branch.

Changes to the content of the GitHub repository must go through a pull request process. Pull requests should have at least one reviewer from each organization funded by CMS to manage the repository. The reviewers from the funded organizations are expected to submit a review in a timely manner within 3 business days of the pull request being submitted. If a review needs to be expedited (e.g., a bug fix necessary to meet a CMS deadline), the submitter should communicate directly with the reviewers to ensure that they are aware of the expedited timeline and document this requirement within the pull request. Pull requests that don’t require an expedited review should remain open at least three business days to allow community members to perform a review.

Community members are expected to review pull requests of interest and provide comments regarding their questions or concerns. Both the pull request submitter and the commenter are expected to be responsive to one another, preferably replying within one business day to a comment or response. A reply should, at a minimum, signal any actions that may be taken.

#### Permissions

The GitHub repository permissions will be aligned with the roles outlined above in the following way:
* PMC
* Admin permissions: Team members can read, clone, push, and add collaborators to this repository
* Committer
* Write permissions: Team members can read, clone, and push into this repository
* Contributor/User
* Read permissions: Team members can read and clone this repository

In addition, there are Owner permissions (people with owner roles can manage repository access with teams and have extensive permissions across all repositories in an organization). New repositories should be created in a shared GitHub organization, with ownership being shared by the X and Y team leads. For pre-existing repositories, the leaders of the team that originally created the repository retain Owner permissions as the repository resides in their company’s GitHub organization. The PMC or Sponsor can decide to move the repository to the shared GitHub organization and consequently change the owners; however, this change of location may cause confusion within the contribution community.

## Communication Channels

Communication should be done in an open and public manner. The project uses many different channels for open communication, including:

* Public Mailing List: <mailing list>
* PMC Mailing List: <mailing list>
* Private Mailing List: <mailing list>
* GitHub Issues

Sometimes, communication occurs outside of these public channels, and that is okay; however, committers must summarize any private discussions that impact the tooling project in a public channel. Additionally, there are times when a topic may not be suitable for a public channel or mailing list. An example is a security vulnerability, as advertising this before it is fixed may pose a security risk to the system. For these situations, private communications with a public summary after the issue has been addressed is expected.

## Releases

All packages within the project shall use semantic versioning. Any stakeholder can propose a release, but the PMC must review and approve the contents and timing of any release. Specifically, releases must be coordinated with impacted stakeholders and timed with availability of published versions of the specifications involved. A member of the PMC is responsible for announcing releases to the community via the mailing list.