diff --git a/CODEOWNERS b/.github/CODEOWNERS similarity index 100% rename from CODEOWNERS rename to .github/CODEOWNERS diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f167e9e705..c9444f9d96a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,3 +82,76 @@ To quickly fix typos, use ```bash make misspell-correction ``` + +## Pull Requests + +### How to create a PR + +Everyone is welcome to contribute to the OpenTelemetry specification via GitHub +pull requests (PRs). + +To [create a new +PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request), +fork the project in GitHub and clone the upstream repo: + +```sh +git clone https://github.com/open-telemetry/opentelemetry-specification.git +``` + +Add your fork as a remote: + +```sh +git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-specification.git +``` + +Check out a new branch, make modifications and push the branch to your fork: + +```sh +$ git checkout -b feature +# edit files +$ git commit +$ git push fork feature +``` + +Open a pull request against the main `opentelemetry-specification` repo. + +If the PR is not ready for review, please mark it as +[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/). + +Please make sure CLA is signed and CI is clear. We don't expect people to review +and comment on a PR that doesn't have CLA signed. + +### How to get your PR merged + +A PR is considered to be **ready to merge** when: + +* It has received more than two approvals from the [code + owners](./.github/CODEOWNERS) (if approvals are from only one company, they + won't count). +* There is no `request changes` from the [code owners](./.github/CODEOWNERS). +* It has been at least two working days since the last modification (except for + the trivial updates, such like typo, cosmetic, rebase, etc.). This gives + people reasonable time to review. +* Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to + wait for two days. + +Any [spec +maintainer](https://github.com/open-telemetry/community/blob/master/community-members.md#specifications-and-proto) can +merge the PR once it is **ready to merge**. + +If a PR has been stuck (e.g. there are lots of debates and people couldn't agree +on each other), the owner should try to get people aligned by: + +* Consolidating the perspectives and putting a summary in the PR. It is + recommended to add a link into the PR description, which points to a comment + with a summary in the PR conversation. +* Tagging subdomain experts (by looking at the change history) in the PR asking + for suggestion. +* Reaching out to more people on the [gitter + channel](https://gitter.im/open-telemetry/opentelemetry-specification). +* Stepping back to see if it makes sense to narrow down the scope of the PR or + split it up. + +If none of the above worked and the PR has been stuck for more than 2 weeks, the +owner should bring it to the [OpenTelemetry Specification SIG +meeting](https://github.com/open-telemetry/community#cross-language-specification). diff --git a/docfx.json b/docfx.json index 8215dda72a2..76932e61e80 100644 --- a/docfx.json +++ b/docfx.json @@ -11,6 +11,7 @@ "resource": [ { "files": [ + ".github/CODEOWNERS", ".markdownlint.yaml", ".vscode/settings.json", "**.png"