From 72da1c80aab0eb26a2867f11c61a33fa16ea9238 Mon Sep 17 00:00:00 2001 From: Lizzie Charbonneau Date: Thu, 18 Jul 2019 13:59:41 -0400 Subject: [PATCH] added contribution and governance documents --- CONTRIBUTING.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++ GOVERNANCE.md | 125 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c5fddbc0 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 +git pull +git checkout -b +``` + +### 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 +git status +git commit -m +``` + +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/ +git rebase -i HEAD~ +git push +``` + +`git diff origin/` 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/ + ``` + * 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/ + ``` + +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. \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..01588be5 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,125 @@ +# CQM-Execution Governance Model + +*CQM-Execution is a shared library used by the [Cypress](https://cypress.healthit.gov) and [Bonnie](https://bonnie.healthit.gov/) tools.* + +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: +* PMC Mailing List: +* Private 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.