diff --git a/.textlintrc.yml b/.textlintrc.yml index b08a0a8af780..b4220053d365 100644 --- a/.textlintrc.yml +++ b/.textlintrc.yml @@ -36,6 +36,7 @@ rules: - Erlang - GCP - GitHub + - Gitpod - GraphQL - gRPC - Haskell @@ -60,6 +61,7 @@ rules: - MongoDB - MySQL - NDJSON + - Netlify - NGINX - OCaml - OK diff --git a/.vscode/cspell.json b/.vscode/cspell.json index ec2e045391e2..f096bed562c2 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -44,6 +44,7 @@ "frauddetectionservice", "frontendproxy", "github", + "gitpod", "grafana", "gzipped", "Hausenblas", @@ -74,6 +75,7 @@ "mongodb", "mysql", "ndjson", + "netlify", "Neumann", "nginx", "ocaml", @@ -139,6 +141,7 @@ "traefik", "Trask", "uids", + "unshallow", "upstreamed", "Villela", "wordpress", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b842b1a6d1..ee6cbf54c21a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,122 @@ # Contributing to OpenTelemetry.io -## Quick fixes +Thanks for your interest in contributing to +[OpenTelemetry.io](https://opentelemetry.io/)! Here are a few general guidelines +on contributing and reporting bugs that we ask you to review. Following these +guidelines helps to communicate that you respect the time of the contributors +managing and developing this open source project. In return, they should +reciprocate that respect in addressing your issue, assessing changes, and +helping you finalize your pull requests. In that spirit of mutual respect, we +endeavor to review incoming issues and pull requests, and will close any +lingering issues or pull requests after long times of inactivity. + +Note that all of your interactions in the project are subject to our +[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). +This includes creation of issues or pull requests, commenting on issues or pull +requests, and extends to all interactions in any real-time space e.g., Slack, +Discord, etc. + +Also review the general +[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md), +that will provide additional details, especially that you need to sign a +Contributor License Agreement (CLA) before you can contribute. + +## Found a security issue? + +If you discover a security issue, **do not** report it through GitHub. Instead, +follow the steps in our +[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy). + +## Found a problem? + +If you find a problem with the content of this repository, or you would like to +request an enhancement, [create an issue][new-issue]. + +Before reporting a new issue, please ensure that the issue was not already +reported or fixed by searching through our +[issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). + +When creating a new issue, include a short meaningful title and clear a +description, as much relevant information as possible, and, if possible, a test +case. + +## Want to work on an existing issue? + +This is the best way how you can help us to make our documentation better! Take +a look at issues tagged with +[help wanted](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) +and +[good first issue](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) +to find an opportunity to contribute and help us. The good first issue label +indicates that members have committed to providing extra assistance for new +contributors. + +After picking an issue, read through the existing discussion, ask the +maintainers if this issue is still relevant and ask all questions you need for +clarification. Afterwards you can state in a comment that you intend to work on +this issue and it will be assumed to be yours. We will **not** assign issues to +non-community members who have already made contributions to the [OpenTelemetry +organization][org]. After confirmation through a maintainer, plan to provide a +PR shortly or let maintainers now if you run into any blockers. + +## Sending Pull Requests + +Enhancements and fixes to the website are most welcome! + +Before sending a new [pull request][pr] (PR), take a look at existing +[pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) +and +[issues](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) +to see if the proposed change or fix has been discussed in the past, or if the +change was already implemented but not yet released. + +### Quick fixes For small changes to a single file, you can edit directly in GitHub by clicking -**Edit this file** button and then following the instructions in [Editing -files][]. +**Edit this file** button. After forking the repository, follow the instructions +in [Editing files][]. + +For everything else, follow the +[instructions to setup a development environment](#development) below. -## Dev setup +### PR Guidelines -### Cloud-IDE setup +Before a PR gets merged, it will sometimes require a few iterations of +review-and-edit. To help us and yourself make this process as easy as possible, +we ask that adhere to the following: + +- If your PR isn't a [quick fix](#quick-fixes), then **work from a fork**: Click + the [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at + the top of the repository and clone the fork locally. When you are ready, + raise a PR with the upstream repository. +- **Do not work from the `main`** branch of your fork, but create a PR-specific + branch. +- Ensure that maintainers are + [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). + +### Merge requirements + +- No “changes requested” reviews by approvers, maintainers, technical committee + members, or subject matter experts +- No unresolved conversations +- Approved by at least one approver +- No failing PR checks +- PR branch is up-to-date with the base branch + +> **Important** +> +> Do not worry too much about failing PR checks! Community members will help you +> to get them fixed, by either providing you with instructions how to fix them +> or by fixing them on your behave. + +## Development + +The following instructions will help you to setup a development environment of +the website. + +### Setup + +#### Cloud-IDE setup These instructions are for [Gitpod.io][], adjust as needed for your favorite cloud IDE: @@ -27,7 +135,7 @@ Gitpod will automatically install the repo-specific packages for you. You're now ready to [build](#build), [serve](#serve) and/or make updates to the website files. -### Local setup +#### Local setup 1. [Fork][] and then [clone][] this repository. 2. **Change** to the repository directory. @@ -55,7 +163,7 @@ files. You're now ready to [build](#build), [serve](#serve) and/or make updates to the website files. -## Build +### Build To **build** the site run: @@ -65,7 +173,7 @@ npm run build You'll find the generated site files under `public`. -## Serve +### Serve To **serve** the site run: @@ -88,7 +196,7 @@ npm run serve:netlify > macOS? You may need to increase the file descriptor limit. See > [Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109). -## Content and submodules +### Content and submodules The website is built from the following content: @@ -102,19 +210,10 @@ The website is built from the following content: [content-modules]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules -## Found a problem? - -If you find a problem with the content of this repository, or you would like to -request an enhancement, [create an issue][new-issue]. - -> **NOTE**: As a general policy, we only _assign_ issues to community members -> who have already made contributions to the [OpenTelemetry organization][org]. - -## Submitting a change +### Submitting a change -Enhancements and fixes to the website are most welcome! Before submitting a -[pull request][pr] (PR) to the repository, run the following command and address -any reported issues. Also commit any files changed by the `fix` script: +Before submitting a to the repository, run the following command and address any +reported issues. Also commit any files changed by the `fix` script: ```sh npm run test-and-fix @@ -147,7 +246,7 @@ submodule itself. > You'll also need to `git fetch --unshallow` the submodule before you can > submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules. -## Site deploys and PR previews +### Site deploys and PR previews If you submit a PR, Netlify will create a [deploy preview][] so that you can review your changes. Once your PR is merged, Netlify deploys the updated site to