diff --git a/DCO.md b/DCO.md new file mode 100644 index 0000000..d1b9180 --- /dev/null +++ b/DCO.md @@ -0,0 +1,55 @@ +# Developer Certificate of Origin + +All Chef Software Inc. projects utilize a Developer Certificate of Origin (DCO) to ensure that each commit was written by the +author or that the author has the appropriate rights necessary to contribute the change. Specifically we +utilize [Developer Certificate of Origin, Version 1.1](http://developercertificate.org/) + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +Each commit must include a DCO which looks like this + +`Signed-off-by: Joe Smith ` + +The project requires that the name used is your real name. Neither anonymous contributors nor those +utilizing pseudonyms will be accepted. + +Git makes it easy to add this line to your commit messages. Make sure the `user.name` and +`user.email` are set in your git configs. Use `-s` or `--signoff` to add the Signed-off-by line to +the end of the commit message. diff --git a/README.md b/README.md index 55b456b..99d789f 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,13 @@ Welcome to the Chef Software OSS communities! This is a starting point for contributing to all of Chef's software and a wonderful spot for information on how to join in on the fun. -To learn more about each of our project's structure and organization, please refer to [Project Governance](to be added later) information. +To learn more about each of our project's structure and organization, please refer to [Project Governance](/governance.md) information. ## How We're Organized -Chef Software (the company) produces many products such as Chef, InSpec, and Habitat. Each of these products is fully open source and comprised of one or more open source projects. For instance the Chef product is comprised of chef, ohai, various mixlib projects, and more. +Chef Software (the company) produces many products such as Chef, InSpec, and Habitat. Each of these products is fully open source and comprised of one or more open source projects. For instance the Chef product is comprised of chef, ohai, various mixlib projects, and other interdependent libraries. The project and/or sub-project scope is defined in each GitHub repository in the README.md file. -Many of our projects include sub-projects, which are repositories of code that are tightly coupled to another project. For example the InSpec project has a sub-project of `kitchen-inspec` as changes to the InSpec codebase more than often require updates to `kitchen-inspec`. The project and sub-project scope is defined in each GitHub repository in the README.md file. - -All governance of Chef projects operates within the requirements set by the Chef OSS Practices committee, all of which are documented under [Governance](governance.md), however *Teams* can have their own policy for contribution, described in their `CONTRIBUTING.md` file in their project repo (e.g. habitat/CONTRIBUTING.md), communication standards, etc. so long as those policies meet the base Chef Software policy. +All Chef projects operate under governance determined by the Chef OSS Practices Committee. These policies are documented under [Governance](/governance.md), however *Teams* can have their own [policy for contribution](/repo-management/project-required-setup.md#CONTRIBUTING.md), communication standards, etc. so long as those policies meet the base governance policy. ## Communicating With Us @@ -24,11 +22,11 @@ For more specific topics, check out an individual project. A first step towards contributing is to pick from the [list of Chef Software Projects](added later). Read the team's contribution policy (CONTRIBUTING.md), start attending team meetings, join the chat channel, subscribe to the mailing list. Teams will have a set of "Help Wanted" issues that can help new contributors get involved. -The [Contributor Guide] provides detailed instructions on how to get your code accepted into core including: +The [Contributor Guide](/contributors/guide) provides detailed instructions on how to get your code accepted into core including: - 1. Doing a thing! - 2. Doing some other thing! - 3. Perhaps doing a final thing!? + 1. How to [file an issue](/contributors/guide/README.md#File-an-issue) + 2. How to [find something to work on](/contributors/guide/README.md#Find-something-to-work-on) + 3. How to [open a pull request](/contributors/guide/README.md#Open-a-pull-request) ## Project Membership diff --git a/communication/communication_faq.md b/communication/communication-faq.md similarity index 100% rename from communication/communication_faq.md rename to communication/communication-faq.md diff --git a/contributors/guide/README.md b/contributors/guide/README.md index d7c5859..b3925f9 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -7,28 +7,33 @@ Feel free to browse the [open issues](https://github.com/chef/chef-oss-practices Welcome to the Chef Software Inc. OSS Community! -- [Before you get started](#before-you-get-started) - - [Signing the DCO](#signing-the-dco) - - [Code of Conduct](#code-of-conduct) - - [Community Expectations and Roles](#community-expectations-and-roles) - - [Thanks](#thanks) -- [Your First Contribution](#your-first-contribution) - - [Find something to work on](#find-something-to-work-on) - - [Find a good first topic](#find-a-good-first-topic) - - [Learn about teams](#learn-about-team) - - [File an Issue](#file-an-issue) -- [Contributing](#contributing) - - [Communication](#communication) - - [GitHub workflow](#github-workflow) - - [Open a Pull Request](#open-a-pull-request) - - [Code Review](#code-review) - - [Testing](#testing) - - [Security](#security) - - [Issues Management or Triage](#issues-management-or-triage) -- [Community](#community) - - [Communication](#communication-1) - - [Events](#events) - - [Mentorship](#mentorship) +- [Chef Software Inc. Contributor Guide](#chef-software-inc-contributor-guide) +- [Welcome](#welcome) +- [Before you get started](#before-you-get-started) + - [Signing the DCO](#signing-the-dco) + - [Code of Conduct](#code-of-conduct) + - [Community Expectations and Roles](#community-expectations-and-roles) +- [Your First Contribution](#your-first-contribution) + - [Find something to work on](#find-something-to-work-on) + - [Find a good first topic](#find-a-good-first-topic) + - [Issue Assignment in Github](#issue-assignment-in-github) + - [Learn about Teams](#learn-about-teams) + - [Team structure](#team-structure) + - [Find a team that is related to your contribution](#find-a-team-that-is-related-to-your-contribution) + - [File an Issue](#file-an-issue) +- [Contributing](#contributing) + - [Communication](#communication) + - [GitHub workflow](#github-workflow) + - [Open a Pull Request](#open-a-pull-request) + - [Code Review](#code-review) + - [Testing](#testing) + - [Security](#security) + - [Issues Management or Triage](#issues-management-or-triage) +- [Community](#community) + - [Communication](#communication-1) + - [Events](#events) + - [Mentorship](#mentorship) +- [Advanced Topics](#advanced-topics) # Before you get started @@ -178,7 +183,7 @@ To make it easier for your PR to receive reviews, consider the reviewers will ne * follow the project [coding conventions](coding-conventions.md) (which may be defined by a language specific guild) * write [good commit messages](https://chris.beams.io/posts/git-commit/) * break large changes into a logical series of smaller commits which individually make easily understandable changes, and in aggregate solve a broader issue -* label PRs with appropriately: check out our section on [github labels](/github_labels.md) +* label PRs with appropriately: check out our section on [github labels](/github-labels.md) Reviewers, the people giving the review, are highly encouraged to revisit the [Code of Conduct](/CODE_OF_CONDUCT.md) and must go above and beyond to promote a collaborative, respectful community. When reviewing PRs from others [The Gentle Art of Patch Review](http://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) suggests an iterative series of focuses which is designed to lead new contributors to positive collaboration without inundating them initially with nuances: diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md new file mode 100644 index 0000000..c8838e4 --- /dev/null +++ b/contributors/guide/pull-requests.md @@ -0,0 +1,302 @@ +# Pull Request Process +This doc explains the process and best practices for submitting a pull request to any of the Chef Software Inc. projects and their associated subrepositories. It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters. + +- [Before You Submit a Pull Request](#before-you-submit-a-pull-request) + * [Run Local Verifications](#run-local-verifications) +- [The Pull Request Submit Process](#the-pull-request-submit-process) + * [The Testing and Merge Workflow](#the-testing-and-merge-workflow) + * [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests) + * [Comment Commands Reference](#comment-commands-reference) + * [Automation](#automation) + * [How the e2e Tests Work](#how-the-e2e-tests-work) +- [Why was my Pull Request closed?](#why-was-my-pull-request-closed) +- [Why is my Pull Request not getting reviewed?](#why-is-my-pull-request-not-getting-reviewed) +- [Best Practices for Faster Reviews](#best-practices-for-faster-reviews) + * [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions) + * [1. Is the feature wanted? File a Kubernetes Enhancement Proposal](#1-is-the-feature-wanted-file-a-kubernetes-enhancement-proposal) + * [2. Smaller Is Better: Small Commits, Small Pull Requests](#2-smaller-is-better-small-commits-small-pull-requests) + * [3. Open a Different Pull Request for Fixes and Generic Features](#3-open-a-different-pull-request-for-fixes-and-generic-features) + * [4. Comments Matter](#4-comments-matter) + * [5. Test](#5-test) + * [6. Squashing and Commit Titles](#6-squashing-and-commit-titles) + * [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc) + * [8. It's OK to Push Back](#8-its-ok-to-push-back) + * [9. Common Sense and Courtesy](#9-common-sense-and-courtesy) + * [10. Trivial Edits](#10-trivial-edits) + +# Before You Submit a Pull Request + +This guide is for contributors who already have a pull request to submit or community members looking for suggestions on how we interact with the larger community. If you're looking for information on setting up your developer environment and creating code to contribute to a specific project, we would suggest viewing that projects CONTRIBUTING.md file (which should be standard across all Chef Software Inc. repositories). + +First time contributors should head to the [Contributor Guide](/contributors/guide/README.md) to get started. + +**Make sure your pull request adheres to our best practices. These include following project conventions, making small pull requests, and commenting thoroughly. Please read the more detailed section on [Best Practices for Faster Reviews](#best-practices-for-faster-reviews) at the end of this doc.** + +## Run Local Verifications + +If a project's CONTRIBUTING.md covers local verifications you should _absolutely_ run them before you submit your pull request. Often these verifications help predict the pass or fail of automated continuous integration which will be a requirement for merge in 99.9% of cases. + +# The Pull Request Submit Process + +Merging a pull request requires the following steps to be completed before the pull request will be merged + +- [Sign your commits with a DCO](/DCO.md) (prerequisite) +- [Open a pull request](https://help.github.com/articles/about-pull-requests/) +- Pass all e2e tests +- Get all necessary approvals from reviewers and code owners + +## The Testing and Merge Workflow + +The Chef Software Inc. merge workflow uses labels, applied by [commands](https://prow.k8s.io/command-help) via comments. These will trigger actions on your pull request. Different repositories may require different labels on the path to approval. A generic explanation of how labels are used in pull requests can be found [here](/contributors/guide/owners.md#code-review-using-owners-files). The pull request bot will also automatically apply and/or suggest labels. + +_Example:_ To apply a BugFix label, you would type in a comment: +``` +@expeditor label bugfix +``` + +*NOTE: For pull requests that are in progress but not ready for review, +prefix the pull request title with `WIP` or `[WIP]` and track any remaining TODOs +in a checklist in the pull request description.* + +**************************************************************************************** +Here's the process the pull request goes through on its way from submission to merging: + +1. Make the pull request +1. `@expeditor` assigns reviewers + +1. If you're **not** a member of the project's organization, a Reviewer/Member checks that the pull request is safe to test. If so, they comment `@expeditor ok-to-test`. Pull requests by organization [members](/community-membership.md) do not need this step. Now the pull request is considered to be trusted, and the pre-submit tests will run: + + 1. Automatic tests run. + 1. If tests fail, resolve issues by pushing edits to your pull request branch + 1. If the failure is a flake, anyone on trusted pull requests can comment `@ expeditor retest` to rerun failed tests + +1. Reviewer suggests edits +1. Push edits to your pull request branch +1. Repeat the prior two steps as needed until reviewer(s) add `/lgtm` label. The `/lgtm` label, when applied by someone listed as an `reviewer` in the corresponding project `OWNERS` file, is a signal that the code has passed review from one or more trusted reviewers for that project +1. (Optional) Some reviewers prefer that you squash commits at this step +1. Follow the bot suggestions to assign an OWNER who will add the `/approve` label to the pull request. The `/approve` label, when applied by someone listed as an `approver` in the corresponding project `OWNERS`, is a signal that the code has passed final review and is ready to be automatically merged + +The behavior of Prow is configurable across projects. You should be aware of the following configurable behaviors. + +* If you are listed as an `/approver` in the `OWNERS` file, an implicit `/approve` can be applied to your pull request. This can result in a merge being triggered by a `/lgtm` label. This is the configured behavior in many projects, including `kubernetes/kubernetes`. You can remove the implicit `/approve` with `/approve cancel` +* `/lgtm` can be configured so that from someone listed as both a `reviewer` and an `approver` will cause both labels to be applied. For `kubernetes/kuebernetes` and many other projects this is _not_ the default behavior, and `/lgtm` is decoupled from `/approve` + +Once the tests pass and the reviewer adds the `lgtm` and `approved` labels, the pull request enters the final merge pool. The merge pool is needed to make sure no incompatible changes have been introduced by other pull requests since the tests were last run on your pull request. + +*************************************************************************************** + +[Tide](https://git.k8s.io/test-infra/prow/cmd/tide) will manage the merge pool +automatically. It uses GitHub queries to select PRs into “tide pools”, +runs as many in a batch as it can (“tide comes in”), and merges them (“tide goes out”). + +1. The pull request enters the [merge pool](https://prow.k8s.io/tide) +if the merge criteria are met. The [PR dashboard](https://prow.k8s.io/pr) shows +the difference between your PR's state and the merge criteria so that you can +easily see all criteria that are not being met and address them. +1. If tests fail, resolve issues by pushing edits to your pull request branch +1. If the failure is a flake, anyone can comment `/retest` if the pull request is trusted +1. If tests pass, Tide automatically merges the pull request + +That's the last step. Your pull request is now merged. + +## Marking Unfinished Pull Requests + +If you want to solicit reviews before the implementation of your pull request is complete, you should hold your pull request to ensure that Tide does not pick it up and attempt to merge it. There are two methods to achieve this: + +1. You may add the `/hold` or `/hold cancel` comment commands +2. You may add or remove a `WIP` or `[WIP]` prefix to your pull request title + +The GitHub robots will add and remove the `do-not-merge/hold` label as you use the comment commands and the `do-not-merge/work-in-progress` label as you edit your title. While either label is present, your pull request will not be considered for merging. + +## Pull Requests and the Release Cycle + +If a pull request has been reviewed, but held or not approved, it might be due to the current phase in the [Release Cycle](/contributors/devel/release.md). Occasionally, a SIG may freeze their own code base when working towards a specific feature or goal that could impact other development. During this time, your pull request could remain unmerged while their release work is completed. + +If you feel your pull request is in this state, contact the appropriate [SIG](https://git.k8s.io/community/sig-list.md) or [SIG-Release](https://git.k8s.io/sig-release) for clarification. + +## Comment Commands Reference + +[The commands doc](https://go.k8s.io/bot-commands) contains a reference for all comment commands. + +## Automation + +The Kubernetes developer community uses a variety of automation to manage pull requests. This automation is described in detail [in the automation doc](/contributors/devel/automation.md). + +## How the e2e Tests Work + +The end-to-end tests will post the status results to the pull request. If an e2e test fails, +`@k8s-ci-robot` will comment on the pull request with the test history and the +comment-command to re-run that test. e.g. + +> The following tests failed, say /retest to rerun them all. + +# Why was my pull request closed? + +Pull requests older than 90 days will be closed. Exceptions can be made for pull requests that have active review comments, or that are awaiting other dependent pull requests. Closed pull requests are easy to recreate, and little work is lost by closing a pull request that subsequently needs to be reopened. We want to limit the total number of pull requests in flight to: +* Maintain a clean project +* Remove old pull requests that would be difficult to rebase as the underlying code has changed over time +* Encourage code velocity + +# Why is my pull request not getting reviewed? + +A few factors affect how long your pull request might wait for review. + +If it's the last few weeks of a milestone, we need to reduce churn and stabilize. + +Or, it could be related to best practices. One common issue is that the pull request is too big to review. Let's say you've touched 39 files and have 8657 insertions. When your would-be reviewers pull up the diffs, they run away - this pull request is going to take 4 hours to review and they don't have 4 hours right now. They'll get to it later, just as soon as they have more free time (ha!). + +There is a detailed rundown of best practices, including how to avoid too-lengthy pull requests, in the next section. + +But, if you've already followed the best practices and you still aren't getting any pull request love, here are some +things you can do to move the process along: + + * Make sure that your pull request has an assigned reviewer (assignee in GitHub). If not, reply to the pull request comment stream asking for a reviewer to be assigned. This is done via a [bot command](https://prow.k8s.io/command-help) (the bot may have suggestions for this) and looks like this: `/assign @username`. + + * Ping the assignee (@username) on the pull request comment stream, and ask for an estimate of when they can get to the review. + + * Ping the assignee on [Slack](http://slack.kubernetes.io). Remember that a person's GitHub username might not be the same as their Slack username. + + * Ping the assignee by email (many of us have publicly available email addresses). + + * If you're a member of the organization ping the [team](https://github.com/orgs/kubernetes/teams) (via @team-name) that works in the area you're submitting code. + + * If you have fixed all the issues from a review, and you haven't heard back, you should ping the assignee on the comment stream with a "please take another look" (`PTAL`) or similar comment indicating that you are ready for another review. + +Read on to learn more about how to get faster reviews by following best practices. + +# Best Practices for Faster Reviews + +Most of this section is not specific to Kubernetes, but it's good to keep these best practices in mind when you're making a pull request. + +You've just had a brilliant idea on how to make Kubernetes better. Let's call that idea Feature-X. Feature-X is not even that complicated. You have a pretty good idea of how to implement it. You jump in and implement it, fixing a bunch of stuff along the way. You send your pull request - this is awesome! And it sits. And sits. A week goes by and nobody reviews it. Finally, someone offers a few comments, which you fix up and wait for more review. And you wait. Another week or two go by. This is horrible. + +Let's talk about best practices so your pull request gets reviewed quickly. + +## 0. Familiarize yourself with project conventions + +* [Development guide](/contributors/devel/development.md) +* [Coding conventions](../guide/coding-conventions.md) +* [API conventions](/contributors/devel/api-conventions.md) +* [Kubectl conventions](/contributors/devel/kubectl-conventions.md) + +## 1. Is the feature wanted? File a Kubernetes Enhancement Proposal +Are you sure Feature-X is something the Kubernetes team wants or will accept? Is it implemented to fit with other changes in flight? Are you willing to bet a few days or weeks of work on it? + +It's better to get confirmation beforehand. + +When you want to make a large or otherwise significant change, you should follow the [Kubernetes Enhancement Proposal process](/keps/0001-kubernetes-enhancement-proposal-process.md). + +Even for small changes, it is often a good idea to gather feedback on an issue you filed, or even simply ask in the appropriate SIG's Slack channel to invite discussion and feedback from code owners. Here's a [list of SIGs](/sig-list.md). + + +## 2. Smaller Is Better: Small Commits, Small Pull Requests + +Small commits and small pull requests get reviewed faster and are more likely to be correct than big ones. + +Attention is a scarce resource. If your pull request takes 60 minutes to review, the reviewer's eye for detail is not as keen in the last 30 minutes as it was in the first. It might not get reviewed at all if it requires a large continuous block of time from the reviewer. + +**Breaking up commits** + +Break up your pull request into multiple commits, at logical break points. + +Making a series of discrete commits is a powerful way to express the evolution of an idea or the +different ideas that make up a single feature. Strive to group logically distinct ideas into separate commits. + +For example, if you found that Feature-X needed some prefactoring to fit in, make a commit that JUST does that prefactoring. Then make a new commit for Feature-X. + +Strike a balance with the number of commits. A pull request with 25 commits is still very cumbersome to review, so use +judgment. + +**Breaking up Pull Requests** + +Or, going back to our prefactoring example, you could also fork a new branch, do the prefactoring there and send a pull request for that. If you can extract whole ideas from your pull request and send those as pull requests of their own, you can avoid the painful problem of continually rebasing. + +Kubernetes is a fast-moving codebase - lock in your changes ASAP with your small pull request, and make merges be someone else's problem. + +Multiple small pull requests are often better than multiple commits. Don't worry about flooding us with pull requests. We'd rather have 100 small, obvious pull requests than 10 unreviewable monoliths. + +We want every pull request to be useful on its own, so use your best judgment on what should be a pull request vs. a commit. + +As a rule of thumb, if your pull request is directly related to Feature-X and nothing else, it should probably be part of the Feature-X pull request. If you can explain why you are doing seemingly no-op work ("it makes the Feature-X change easier, I promise") we'll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a pull request. (Do not link pull requests by `#` in a commit description, because GitHub creates lots of spam. Instead, reference other pull requests via the pull request your commit is in.) + +## 3. Open a Different pull request for Fixes and Generic Features + +**Put changes that are unrelated to your feature into a different pull request.** + +Often, as you are implementing Feature-X, you will find bad comments, poorly named functions, bad structure, weak type-safety, etc. + +You absolutely should fix those things (or at least file issues, please) - but not in the same pull request as your feature. Otherwise, your diff will have way too many changes, and your reviewer won't see the forest for the trees. + +**Look for opportunities to pull out generic features.** + +For example, if you find yourself touching a lot of modules, think about the dependencies you are introducing between packages. Can some of what you're doing be made more generic and moved up and out of the Feature-X package? Do you need to use a function or type from an otherwise unrelated package? If so, promote! We have places for hosting more generic code. + +Likewise, if Feature-X is similar in form to Feature-W which was checked in last month, and you're duplicating some tricky stuff from Feature-W, consider prefactoring the core logic out and using it in both Feature-W and +Feature-X. (Do that in its own commit or pull request, please.) + +## 4. Comments Matter + +In your code, if someone might not understand why you did something (or you won't remember why later), comment it. Many code-review comments are about this exact issue. + +If you think there's something pretty obvious that we could follow up on, add a TODO. + +Read up on [GoDoc](https://blog.golang.org/godoc-documenting-go-code) - follow those general rules for comments. + +## 5. Test + +Nothing is more frustrating than starting a review, only to find that the tests are inadequate or absent. Very few pull requests can touch code and NOT touch tests. + +If you don't know how to test Feature-X, please ask! We'll be happy to help you design things for easy testing or to suggest appropriate test cases. + +## 6. Squashing and Commit Titles + +Your reviewer has finally sent you feedback on Feature-X. + +Make the fixups, and don't squash yet. Put them in a new commit, and re-push. That way your reviewer can look at the new commit on its own, which is much faster than starting over. + +We might still ask you to clean up your commits at the very end for the sake of a more readable history, but don't do this until asked: typically at the point where the pull request would otherwise be tagged `LGTM`. + +Each commit should have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended. + +**General squashing guidelines:** + +* Sausage => squash + + Do squash when there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state and commit message for the whole pull request. + +* Layers => don't squash + + Don't squash when there are independent changes layered to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate pull requests, but there's really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn't immediately get out of date. + +A commit, as much as possible, should be a single logical change. + +## 7. KISS, YAGNI, MVP, etc. + +Sometimes we need to remind each other of core tenets of software design - Keep It Simple, You Aren't Gonna Need It, Minimum Viable Product, and so on. Adding a feature "because we might need it later" is antithetical to software that ships. Add the things you need NOW and (ideally) leave room for things you might need later - but don't implement them now. + +## 8. It's OK to Push Back + +Sometimes reviewers make mistakes. It's OK to push back on changes your reviewer requested. If you have a good reason for doing something a certain way, you are absolutely allowed to debate the merits of a requested change. Both the reviewer and reviewee should strive to discuss these issues in a polite and respectful manner. + +You might be overruled, but you might also prevail. We're pretty reasonable people. Mostly. + +Another phenomenon of open-source projects (where anyone can comment on any issue) is the dog-pile - your pull request gets so many comments from so many people it becomes hard to follow. In this situation, you can ask the primary reviewer (assignee) whether they want you to fork a new pull request to clear out all the comments. You don't HAVE to fix every issue raised by every person who feels like commenting, but you should answer reasonable comments with an explanation. + +## 9. Common Sense and Courtesy + +No document can take the place of common sense and good taste. Use your best judgment, while you put +a bit of thought into how your work can be made easier to review. If you do these things your pull requests will get merged with less friction. + +## 10. Trivial Edits + +Each incoming Pull Request needs to be reviewed, checked, and then merged. + +While automation helps with this, each contribution also has an engineering cost. Therefore it is appreciated if you do NOT make trivial edits and fixes, but instead focus on giving the entire file a review. + +If you find one grammatical or spelling error, it is likely there are more in that file, you can really make your Pull Request count by checking formatting, checking for broken links, and fixing errors and then submitting all the fixes at once to that file. + +**Some questions to consider:** + +* Can the file be improved further? +* Does the trivial edit greatly improve the quality of the content? +! diff --git a/definitions.md b/definitions.md index 8c6b7c1..83d4a02 100644 --- a/definitions.md +++ b/definitions.md @@ -2,7 +2,7 @@ ### Project -A Project is one GitHub repo that contains code. +A Project is one or more GitHub repos that contain interdependent code. ### Product diff --git a/governance.md b/governance.md index 458ad3f..c549c9c 100644 --- a/governance.md +++ b/governance.md @@ -11,15 +11,15 @@ The Chef OSS communities adhere to the following principles: ## Code of Conduct -All members of the Chef community, including employees, must abide by the Chef Code of Conduct. For the complete text see the [Chef Code of Conduct](code-of-conduct.md) +All members of the Chef community, including employees, must abide by the Chef Code of Conduct. For the complete text see the [Chef Code of Conduct](/CODE_OF_CONDUCT.md) -## Community membership +## Project membership -Here is some placeholder information with links to information on community membership +See [project membership](/project-membership.md) ## Community Groups -The Chef OSS Communities have 4 main types of groups: +The Chef OSS Communities have 3 main types of groups: - Teams - Guilds @@ -35,58 +35,15 @@ Guilds are a cross-cutting group of individuals with shared interests on a speci ### Committees -Committees are named sets of people that are chartered to take on sensitive or specific topics. This group is encouraged to be as open as possible while achieving its mission but, because of the potential nature of the topics discussed, private communications are allowed. +Committees are named sets of people that are chartered to take on sensitive or specific topics. This group is encouraged to be as open as possible while achieving its mission, but some private communication is expected because of the potential sensitive nature of the topics discussed. ## Repository Guidelines -All new repositories under the Chef, Habitat, or Inspec github orgs should follow the process outlined in the [chef oss repository guidelines](to be added later). -## DCO -This project utilizes a Developer Certificate of Origin (DCO) to ensure that each commit was written by the author or that the author has the appropriate rights necessary to contribute the change. The project utilizes Developer Certificate of Origin, Version 1.1 -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: +All new repositories under the Chef, Habitat, or Inspec github orgs should follow the processes outlined in the [Chef OSS repository guidelines](/repo-management). -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` -Each commit must include a DCO which looks like this - -Signed-off-by: Joe Smith - -The project requires that the name used is your real name. Neither anonymous contributors nor those utilizing pseudonyms will be accepted. +## DCO -Git makes it easy to add this line to your commit messages. Make sure the user.name and user.email are set in your git configs. Use -s or --signoff to add the Signed-off-by line to the end of the commit message. +This project uses a [Developer Certificate of Origin (DCO)](/DCO.md) to ensure that each commit was written by the author or that the author has the appropriate rights necessary to contribute the change. ## End of Life for a Project diff --git a/maintainership.md b/maintainership.md deleted file mode 100644 index c9eb248..0000000 --- a/maintainership.md +++ /dev/null @@ -1,29 +0,0 @@ -# Maintainership of Projects - -## Definition -* Projects have **maintainers**, not authors -* The maintainers are responsible for merging pull requests, triaging issues, and more. - -## Rules and Responsibilities -* At least two maintainers must be current Chef employees -* Roadmaps are planned by Product Management, Engineering Leadership, and maintainers (including external maintainers - who have input, but not veto power) -* Maintainers are responsible for **communicating** overall project planning and roadmap of their project. -* Maintainer reviews are required on all code and maintainers are the only ones that can merge code into a project. If you need to merge code, then you are a maintainer. -* All maintainer team discussion outside of security issues should be done in a public forum. -* The maintainer team is added as a codeowner on their repository so that they are automatically set up via Github for code reviews -* All contributions must include Developer Certificate of Origin (DCO) signoff. Code repositories must integrate a tool checking for a DCO sign-off present on every commit (see below for examples) -* A tool is setup to automatically ping maintainers for reviews / triage (see below for examples) - -## Tool Examples - -### Developer Certificate of Origin - -We recommend integrating Chef's DCO bot tool (which is in the progress of being added to Expeditor) - -### Pull Request Reminders - -Teams are welcome to choose whatever tool they wish, but there are two that we recommend. - -* GitHub webhooks with Slack - this will update a Slack channel when a new pull request is open (and is highly configurable) - -* [Pull Reminders](https://pullreminders.com/) - this will routinely ping reviewers assigned to a pull request until that pull request is either merged or closed. Chef does have a current subscription to this tool diff --git a/project-membership.md b/project-membership.md index 45ebb53..ed14a9d 100644 --- a/project-membership.md +++ b/project-membership.md @@ -11,11 +11,11 @@ Established project members are expected to demonstrate their adherence to the p **Note:** This document is in progress, it outlines the various responsibilities of project roles in the Chef Software Inc. OSS Communities. Chef's software organized as projects under teams. Responsibilities/Privileges for most roles are scoped to a project or subproject. | Project Role | Responsibilities | Requirements | Defined by | -| -----| ---------------- | ------------ | -------| +| ----- | ---------------- | ------------ | ------- | | contributor | you become a contributor to the project by opening a PR or an Issue | No requirements | Having your GitHub handle recognized in the Changelog | -| reviewer | review contributions from other members | history of review and authorship in a subproject | [CODEOWNERS] file reviewer entry. | -| approver | final approval and acceptance of contributions | highly experienced and active reviewer + contributor to a subproject | [CODEOWNERS] file approver entry| -| subproject owner | set direction and priorities for a subproject | demonstrated responsibility and excellent technical judgement for the subproject | [teams.yaml] subproject [CODEOWNERS] file *owners* entry | +| reviewer | review contributions from other members | history of review and authorship in a project | project [CODEOWNERS] entry, Chef OSS [TEAMS] file *reviewer* entry. | +| approver | final approval and acceptance of contributions | highly experienced and active reviewer + contributor to a project | Chef OSS [TEAMS] file *approver* entry, project [CODEOWNERS] entry| +| project owner | set direction and priorities for a project | demonstrated responsibility and excellent technical judgement for the project | project [CODEOWNERS] entry, Chef OSS [TEAMS] file *owners* entry | ## Reviewer @@ -26,8 +26,9 @@ Reviewers are able to review code for quality and correctness on some part of a *Note*: All Chef Software lives in open repos, and we welcome contribution and code reviews from anyone! The reviewer project role specifically refers to the following outlined responsibilities and privileges. Acceptance of code contributions requires at least one approver in addition to the assigned reviewers. -* -**Defined by:** An entry in a CODEOWNERS file in a repo owned by the specific Chef Software Inc. Project. +**Defined by:** An entry in a CODEOWNERS file in a repo owned by the specific Chef Software Inc. Project. A *reviewer* entry in the Chef OSS [TEAMS] file. + +Reviewer status is scoped to a project. ### Requirements @@ -35,7 +36,7 @@ Reviewers are able to review code for quality and correctness on some part of a - Have made multiple contributions to the project. Contributions may include, but are not limited to: - Authoring or reviewing PRs on GitHub - Filing or commenting on issues on GitHub -- Have read the [contributor guide](/contributors/guide/README.md) +- Have read the [contributor guide] - Subscribed to the project's core-development mailing list and/or chat channel - Actively contributing to 1 or more projects. - Sponsored by 2 reviewers (or approvers). **Note the following requirements for sponsors**: @@ -46,7 +47,7 @@ Reviewers are able to review code for quality and correctness on some part of a - Complete every item on [the checklist](/.github/ISSUE_TEMPLATE/membership.md) in the issue template - Make sure that the list of contributions included is representative of your work on the project. - Have your sponsoring reviewers reply confirmation of sponsorship: `+1` or PR GitHub approvals -- Once your sponsors have responded, your request will be reviewed by the project's approvers, in accordance with their PR SLA. Any missing information will be requested. +- Once your sponsors have responded, your request will be reviewed by the project's approvers, in accordance with their PR [SLA]. Any missing information will be requested. ### Chef Software Ecosystem @@ -56,10 +57,10 @@ There are many interrelated [Chef Software GitHub organizations], such as [habit The following applies to the codebases for which one is listed as a reviewer in a [CODEOWNERS] file. -- Responsible for project quality control via [code reviews](/contributors/guide#code-review) +- Responsible for project quality control via [code reviews] - Focus on code quality and correctness, including [testing](/contributors/guide#testing) - Encouraged to review for more holistic issues, but not a requirement -- Expected to be responsive to review requests, issues, and mentions and as per [community expectations](/contributors/guide/community-expectations.md) +- Expected to be responsive to review requests, issues, and mentions and as per [community expectations] - Assigned PRs to review related to a reviewer's areas of interest or experience - Assigned test bugs related to a reviewer's areas of interest or experience - Granted "read access" to appropriate project repos @@ -68,110 +69,94 @@ The following applies to the codebases for which one is listed as a reviewer in ## Approver -Code approvers are able to both review and approve code contributions. While -code review is focused on code quality and correctness, approval is focused on -holistic acceptance of a contribution including: backwards / forwards -compatibility, adhering to API and flag conventions, subtle performance and -correctness issues, interactions with other parts of the system, etc. +Code approvers are able to both review and approve code contributions. While code review is focused on code quality and correctness, approval is focused on holistic acceptance of a contribution including: backwards / forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, etc. -**Defined by:** an entry in a CODEOWNERS file in a repo owned by the -Chef Software Inc. project AND merge rights to a project's trunk. +**Defined by:** an entry in a CODEOWNERS file in a repo owned by the Chef Software Inc. project AND merge rights to a project's trunk. An *approver* entry in the Chef OSS [TEAMS] file. Approver status is scoped to a project. ### Requirements -The following apply to the part of codebase for which one would be an approver -in an [OWNERS] file (for repos using the bot). +The following requirements apply to the portions of a project for which one would be an approver. -- Reviewer of the codebase for at least 3 months -- Primary reviewer for at least 10 substantial PRs to the codebase -- Reviewed or merged some large (relative to the project) number of substantial PRs to the codebase. A larger number than the requirement for a reviewer. In the case of a high activity project like Chef, or Habitat we suggest that number be around 30 PRs. -- Nominated by a subproject owner - - With no objections from other subproject owners - - Done through PR to update the top-level OWNERS file +- Must already be a reviewer of the codebase (each project may define a minimum reviewer tenure requirement to qualify) +- Primary reviewer for several substantial PRs to the codebase (each project may define a minimum to qualify) +- Nominated by an approver _and_ seconded by a project owner + - With no objections from other project owners or approvers + - Done through PR to update the CODEOWNERS + - On Merge project owner grants merge privileges to project trunk ### Responsibilities and privileges -The following apply to the part of codebase for which one would be an approver -in an [OWNERS] file (for repos using the bot). +The following apply to the portions of a project for which one would be an approver. -- Approver status may be a precondition to accepting large code contributions - Demonstrate sound technical judgement - Responsible for project quality control via [code reviews] - - Focus on holistic acceptance of contribution such as dependencies with other features, backwards / forwards - compatibility, API and flag definitions, etc + - Focus on holistic acceptance of contribution such as dependencies with other features, backwards / forwards compatibility, API and flag definitions, etc - Expected to be responsive to review requests as per [community expectations] - Mentor contributors and reviewers -- May approve code contributions for acceptance +- May approve and merge code contributions +- Approver status may be a precondition to accepting large code contributions -## Subproject Owner +## Project Owner -**Note:** This is a generalized high-level description of the role, and the -specifics of the subproject owner role's responsibilities and related -processes *MUST* be defined for individual teams or subprojects. +**Note:** This is a generalized high-level description of the role, and the specifics of the project owner role's responsibilities and related processes *MUST* be defined for individual teams or projects. -Subproject Owners are the technical authority for a subproject in Chef Software -Inc. projects. They *MUST* have demonstrated both good judgement and responsibility -towards the health of that subproject. Subproject Owners *MUST* set technical -direction and make or approve design decisions for their subproject - either -directly or through delegation of these responsibilities. +Project Owners are the technical authority for all Chef Software Inc. OSS projects. They *MUST* have demonstrated both good judgement and responsibility towards the health of that project. Project Owners *MUST* set _technical_ direction and make or approve _technical_ design decisions for their project - either directly or through delegation of these responsibilities. -**Defined by:** *owners* entry in subproject [CODEOWNERS] files as defined by [teams.yaml] *subproject.owners* +**Defined by:** *owners* entry in project [CODEOWNERS] files. An *owner* entry in the Chef OSS [TEAMS] file *project.owners* ### Requirements -The process for becoming an subproject Owner should be defined in the team -charter of the team owning the subproject. Unlike the roles outlined above, the -Owners of a subproject are typically limited to a relatively small group of -decision makers and updated as fits the needs of the subproject. +The process for becoming a project Owner should be defined in the team charter of the team owning the project. Unlike the roles outlined above, the Owners of a project are typically limited to a relatively small group of decision makers and updated as fits the needs of the project. More often than not these individuals are Principal Engineers @ Chef Software Inc. and have a connection to an internal product owner with whom they are closely collaborating. -The following apply to the subproject for which one would be an owner. +The following apply to the project for which one would be an owner. -- Deep understanding of the technical goals and direction of the subproject -- Deep understanding of the technical domain of the subproject +- Deep understanding of the technical goals and direction of the project +- Deep understanding of the technical domain of the project - Sustained contributions to design and direction by doing all of: - Authoring and reviewing proposals - Initiating, contributing and resolving discussions (emails, GitHub issues, meetings) - Identifying subtle or complex issues in designs and implementation PRs -- Directly contributed to the subproject through implementation and / or review +- Directly contributed to the project through implementation and / or review ### Responsibilities and privileges -The following apply to the subproject for which one would be an owner. +The following apply to the project for which one would be an owner. -- Make and approve technical design decisions for the subproject. -- Set technical direction and priorities for the subproject. +- Make and approve technical design decisions for the project. +- Set technical direction and priorities for the project. - Define milestones and releases. -- Mentor and guide approvers, reviewers, and contributors to the subproject. -- Ensure continued health of subproject +- Mentor and guide approvers, reviewers, and contributors to the project. +- Ensure continued health of project - Adequate test coverage to confidently release - - Tests are passing reliably (i.e. not flaky) and are fixed when they fail -- Ensure a healthy process for discussion and decision making is in place. -- Work with other subproject owners to maintain the project's overall health and success holistically + - Tests pass reliably (i.e. not flaky) and are fixed when they fail +- Ensure a healthy process for open discussion and public decision making is in place. +- Work with other project owners to holistically maintain the project's health and success -## Alumni +## Alums -An alumni to the Chef Inc OSS Projects is an individual who was formerly a member and has for any reason dropped their activity below the accepted threshold. This covers all cases of dropped activity and any case in which the individual has stated their decision to terminate their involvement in a project. Alumni no longer have responsibilities or priviliges to the project they were formerly a member of. Their rights to project repos and tooling is revoked and they are added to an Alumni list in thanks of their previous contributions. +Alums to the Chef Inc OSS Projects is an individual who was formerly a member and has for any reason dropped their activity below a project's accepted threshold. This covers all cases of dropped activity and any case in which the individual has stated their decision to terminate their involvement in a project. Alums no longer have responsibilities or privileges to the project of which they were formerly a member. Their rights to project repos and tooling are revoked and they are added to an Alums list in thanks of their previous contributions. -Alumni status is straightforward - Thank you for being involved in the capacity you were for the time period you were. Should an alumni decide to re-engage the project for membership they will of course be accepted back however it is up to the discretion of the team whether to reinstate an alumni directly to the role they were at before they entered alumni status. +Alum status is straightforward - Thank you for being involved. An alum is welcome to re-engage a project for membership, however it is at the discretion of the team as to whether the returning alum will directly resume their previous role. ## ~~Maintainer~~ **Status:** Removed -The Maintainer role has been removed and replaced with a greater focus on [CODEOWNERS]. +The Maintainer role has been removed and replaced with a greater focus on explicit roles as defined in the [TEAMS] file. -[code reviews]: /contributors/devel/collab.md -[community expectations]: /contributors/guide/community-expectations.md +[New contributors]: /CONTRIBUTING.md [contributor guide]: /contributors/guide/README.md -[Chef GitHub organizations]: /github-management#actively-used-github-organizations +[community expectations]: /contributors/guide/community-expectations.md +[membership request]: /issues/new?template=membership.md&title=REQUEST%3A%20New%20membership%20for%20%3Cyour-GH-handle%3E + +[code reviews]: /contributors/? +[Chef GitHub organizations]: /? [Chef org]: https://github.com/chef -[chef-oss-teams]: https://github.com/chef-oss-teams -[membership request]: https://github.com/chef/org/issues/new?template=membership.md&title=REQUEST%3A%20New%20membership%20for%20%3Cyour-GH-handle%3E -[New contributors]: /CONTRIBUTING.md -[OWNERS]: /contributors/guide/owners.md -[teams.yaml]: /teams.yaml -[SLO]: /github-management/org-owners-guide.md#slos + +[CODEOWNERS]: /contributors/guide/owners.md +[TEAMS]: /teams/ +[SLA]: /github-management/org-owners-guide.md#slas [two-factor authentication]: https://help.github.com/articles/about-two-factor-authentication diff --git a/project-required-setup.md b/project-required-setup.md deleted file mode 100644 index 4aeac50..0000000 --- a/project-required-setup.md +++ /dev/null @@ -1,93 +0,0 @@ -# Required Project Files / Configuration - -In order to provide community members with everything necessary to succeed in a project we require a minimum set of files and configuration for each project repository. This provide potential users and contributors with information they will need to interact with the project and increases the likelihood of successful project contributions. - -## Repo Configuration - -### Repository Description - -A project should include a useful description that acts as elevator pitch for potential users that may find the project in search engines. - -### Repository Topics - -GitHub uses repository topics to aid their search engine. Appropriate topics (keywords) for the project should be added to help users find a repository. - -### Disable Unused Features - -New GitHub repositories ship with the Projects and Wiki features enabled by default. If these are not being used by a project they should be disabled. - -## Repo Files - -## README.md - -A project readme is the first thing a new user or contributor sees when interacting with a Chef Software project. We want to make sure this file is detailed and up to date. It should cover the following things: - - - What the project is itended to be used for. - - Any system or runtime requirements. - - Example uses. - - Known issues or incompatibilies. - - The project license and copyrights. - -## LICENSE - -The LICENSE file is an important legal requirement for open source code, and it is also parsed by Github for use in various places. Adding a license file allows users to search for projects with a specific license and also adds licensing badges to GitHub repository pages. - -## CONTRIBUTING.md - -GitHub prompts new contributors to read a project's CONTRIBUTING.md file if present. Each project should include a file that details the contribution process. Example files will be provided in the future in this repository. - -## CODE_OF_CONDUCT.md - -GitHub displays the code of conduct file when a user opens a new PR or Issue. We want to make sure everyone reads and understands our code of conduct so this needs to be included in every project repository. - -Include the following in the projects CODE_OF_CONDUCT.md (Remember to substitute Example Persons) - -``` -# Code of Conduct - -Please refer to this [Code of Conduct](CODE_OF_CONDUCT.md). - -[CODE_OF_CONDUCT_URL](CODE_OF_CONDUCT_URL) - -If you need to contact someone in regards to this project and the Code of -Conduct please contact the individuals listed in the [Roles](#Roles) section -below. - -## Roles - -The following are the various roles of our Community Organizers and the -person(s) assigned to each role: - - The Deciders have final say on - community guidelines and final authority on correct actions and appeals. - - The Community Advocates may be assigned for each area where the - community convenes online (Slack, email list, GitHub, etc.). Community - Advocates are volunteers who have the best interests of our community in - mind. They act in good faith to help enforce our community guidelines and - respond to incidents when they occur. - - The Project Maintainers are likewise expected to conduct their - behavior in line with the Code of Conduct and are individually responsible - for both escalating to a Community Advocate in case of witnessing an - incident and helping to foster the community and it's members - - A Community Member is anyone who participates with the community - whether in-person or via online channels. Community members are responsible - for following the community guidelines, suggesting updates to the guidelines - when warranted, and helping enforce community guidelines - -| Role | Name | Contact Info | -| ------------------- | ------------------------ | ---------------------- | -| Decider | Example Person | example.person@chef.io | -| Community Advocate | Example Person | example.person@chef.io | -| Community Advocate | Example Person | example.person@chef.io | -| Community Advocate | Example Person | example.person@chef.io | - -``` - -## .github/CODEOWNERS - -The GitHub codeowners file is used to auto assign reviewers to a project. Properly routing new pull requests to the approach team decreases the time it takes to get code reviewed and merged. It also reduces the number of lost pull requests, which helps us engage new contributors and retain them for the future. CODEOWNERS can be setup to assign ownership of certain directories or files to particular teams. This is useful for assigning files like .expeditor to JEX or readme/docs files to the docs team. - -# Other Requirements - -## Detecting Outages - -When a project runs as a service (i.e. hosted Chef or the Builder SaaS service) it must have either monitoring tooling in place or another process for detecting and responding to outages. \ No newline at end of file diff --git a/repo-management/README.md b/repo-management/README.md new file mode 100644 index 0000000..e69de29 diff --git a/github_labels.md b/repo-management/github-labels.md similarity index 100% rename from github_labels.md rename to repo-management/github-labels.md diff --git a/repo-management/project-required-setup.md b/repo-management/project-required-setup.md new file mode 100644 index 0000000..4bbd0ea --- /dev/null +++ b/repo-management/project-required-setup.md @@ -0,0 +1,79 @@ +# Required Project Files / Configuration + +In order to provide community members with everything necessary to succeed in a project we require a minimum set of files and configuration for each project repository. This provide potential users and contributors with information they will need to interact with the project and increases the likelihood of successful project contributions. + +## Configuration + +### Repository Description + +A project should include a useful description that acts as elevator pitch for potential users that may find the project in search engines. + +### Repository Topics + +GitHub uses repository topics to aid their search engine. Appropriate topics (keywords) for the project should be added to help users find a repository. + +### Repository Labels + +A project should include [the standard set of labels](github-labels.md) for issues and PRs. + +### Disable Unused Features + +New GitHub repositories ship with the Projects and Wiki features enabled by default. If these are not being used by a project they should be disabled. + +### PR Status Check: Developer Certificate of Origin + +All Chef Software Inc. OSS projects use the [developer certificate of origin](/DCO.md) for contributed changes. Commits in a pull request must be signed off by the author(s) to be eligible for merging. You COULD spend the time manually confirming that the developers have signed off on their commits, but it's probably a good idea to automate this with Expeditor or another tool of your choosing. + +## Files + +### README.md + +A project readme is the first thing a new user or contributor sees when interacting with a Chef Software project. We want to make sure this file is detailed and up to date. It should cover the following things: + + - What the project is itended to be used for. + - Any system or runtime requirements. + - Example uses. + - Known issues or incompatibilies. + - The project license and copyrights. + +### LICENSE + +The LICENSE file is an important legal requirement for open source code, and it is also parsed by Github for use in various places. Adding a license file allows users to search for projects with a specific license and also adds licensing badges to GitHub repository pages. + +### CONTRIBUTING.md + +GitHub prompts new contributors to read a project's CONTRIBUTING.md file if present. Each project should include a file that details the contribution process. Example files will be provided in the future in this repository. + +### CODE_OF_CONDUCT.md + +GitHub displays the code of conduct file when a user opens a new PR or Issue. We want to make sure everyone reads and understands our code of conduct so this needs to be included in every project repository. + +Include the following in the project's `CODE_OF_CONDUCT.md`. + +``` +# Code of Conduct + +This project follows the [Chef Contributor Covenant Code of Conduct](https://github.com/chef/chef-oss-practices/CODE_OF_CONDUCT.md). +``` + +### TEAMS.md + +The TEAMS file in a repo is commonly seen in other projects as MAINTAINERS.md. Most TEAMS definitions are managed in a [central teams directory](https://github.com/chef/chef-oss-practices/teams). Teams are encouraged to include a `TEAMS.md` in the root of their project repos with links back to the centrally located teams directory. + +### .github/CODEOWNERS + +The GitHub codeowners file is used to auto assign reviewers to a project. Properly routing new pull requests to the appropriate humans decreases the time it takes to get code reviewed and merged. It also reduces the number of lost pull requests, which helps us engage new contributors and retain them for the future. CODEOWNERS can be setup to assign ownership of certain directories or files to particular teams or individuals. For example, changes to files under `readme/docs` can automatically assign the docs team for review. + +## Other Recommendations + +### Monitoring + +When a project runs as a service (i.e. Hosted Chef or the Builder SaaS service) it should definitely have monitoring tooling in place or another process for detecting and responding to outages. + +### Pull Request Reminders + +We find pull request reminders to be a practical mechanism for reminding project members they have open PRs in need of review. Teams should feel free to choose whichever tool for this that they like, but there are two that we recommend. + +* GitHub webhooks with Slack - this will update a Slack channel when a new pull request is open (and is highly configurable) + +* [Pull Reminders](https://pullreminders.com/) - this will routinely ping reviewers assigned to a pull request until that pull request is either merged or closed. Chef does have a current subscription to this tool