diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67979d4ccf84..7ec7a39a8dae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,243 +3,6 @@ **Thanks for your interest in contributing to [OpenTelemetry.io](https://opentelemetry.io/)!** -Follow these guidelines helps to communicate that you respect the time of the -contributors managing and developing this open source project. In return, -maintainers and approvers 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. - -## Before you get started - -### Code of Conduct - -All of your interactions in this project are subject to our -[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). -This includes the creation of issues or pull requests, commenting on issues or -pull requests, and extends to all interactions in any real-time space, for -example Slack, Discord, and so on. - -### Contributor License Agreement - -Review the general -[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md), -as it provides 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, read the -[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) -before opening an issue. - -### Found a problem? - -If you find a bug or 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, make sure 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 a clear -description. Add as much relevant information as you can, 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. - -## Contributor's guide - -To learn how to contribute fixes and new content to this project, read the -[Contributor's guide](https://opentelemetry.io/docs/contributing/), which -includes a style guide and useful information on the review process. - -## 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: - -1. Fork this repository. For help, see [Fork a repository][fork]. -2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or - open an existing workspace over your fork. You can also visit a link of the - form: - . - - > **Note**: If you have the necessary permissions to work from this - > repository, or just want to look around, open - > . - -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 - -1. [Fork][] and then [clone][] this repository. -2. **Change** to the repository directory. -3. **Install or upgrade** to the [**active LTS** release][nodejs-rel] of - **Node.js**. We recommend using **[nvm][]** to manage your Node - installation. Under Linux, run the following command (which will - install/upgrade to the version specified in [.nvmrc][]): - - ```sh - nvm install - ``` - - To [install under Windows][nodejs-win], use [nvm-windows][]: - - ```cmd - > nvm install lts && nvm use lts - ``` - -4. Get npm packages and other prerequisites: - - ```sh - npm install - ``` - -You're now ready to [build](#build), [serve](#serve) and/or make updates to the -website files. - -### Build - -To **build** the site run: - -```sh -npm run build -``` - -You'll find the generated site files under `public`. - -### Serve - -To **serve** the site run: - -```sh -npm run serve -``` - -The site will be served at [localhost:1313][]. - -If you need to test [Netlify] redirects, use the following command, and visit -the site at [localhost:8888][]: - -```sh -npm run serve:netlify -``` - -> **Note 1**: The serve command serves files from memory, not from disk. -> -> **Note 2**: See an error like `too many open files` or `pipe failed` under -> macOS? You may need to increase the file descriptor limit. See -> [Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109). - -### Content and submodules - -The website is built from the following content: - -- Files under `content/`, `static/`, etc. per [Hugo][] defaults. -- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either - directly from git submodules under [content-modules][], or preprocessed - content from `content-modules` (placed under `tmp/`), and no where else. - -[hugo.yaml]: - https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml -[content-modules]: - https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules - -### Submodule changes - -If you change any content inside of a [content-modules][] submodule, then you'll -need to **_first_** submit a PR (containing the submodule changes) to the -submodule's repository. Only after the submodule PR has been accepted, can you -update the submodule and have the changes appear in this website. - -It is easiest to manage your `content-modules` changes by working with the -repository that the corresponding submodule is linked to, rather than inside the -submodule itself. - -> **For expert contributors**, you can work directly in the submodule. You'll -> then be able to directly build and serve your (submodule) changes. By default, -> the CI scripts get submodules on every invocation. To prevent this behavior -> while you work within a submodule, set the environment variable `GET=no`. -> You'll also need to `git fetch --unshallow` the submodule before you can -> submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules. - -## Approver and Maintainer practices - -This last section includes guidelines and some common practices used by -approvers and maintainers while doing code reviews: - -- PRs with changes to documentation co-owned by a SIG (collector, demo, - language-specific...) should aim for two approvals: one by a docs approver and - one by a SIG approver: - - Doc approver label such PRs with `sig:` and tag the SIG `-approvers` - group on that PR - - If no SIG approval is given within a certain grace period (two weeks in - general, but may be less in urgent cases), docs maintainer may use their own - judgement to merge that PR -- If the PR branch is `out-of-date with the base branch`, they do not need to be - updated continuously: every update triggers all the PR CI checks to be run! - It's often enough to update them before merging. -- A PR by non-maintainers should **never** update git sub modules. This happens - by accident from time to time. Let the PR author know that they should not - worry about it, we will fix this before merging, but in the future they should - make sure that they work from an up-to-date fork. -- If the contributor is having trouble signing the CLA or used the wrong email - by mistake in one of their commits, ask them to fix the issue or rebase the - pull request. Worst case scenario, close and re-open the PR to trigger a new - CLA check. -- Words unknown to cspell should be added to the cspell ignore list per page by - PR authors. Only approvers and maintainers will add commonly used terms to the - global list. -- When an approver or maintainer won't be available to contribute for an - extended period of time (more than a few days or a week) or won't be available - in that period of time, they should communicate this using the - [#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and - updating the GitHub status. - -[.nvmrc]: .nvmrc -[clone]: - https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo -[gitpod.io]: https://gitpod.io -[gitpod.io/workspaces]: https://gitpod.io/workspaces -[hugo]: https://gohugo.io -[localhost:1313]: http://localhost:1313 -[localhost:8888]: http://localhost:8888 -[netlify]: https://netlify.com -[new-issue]: - https://github.com/open-telemetry/opentelemetry.io/issues/new/choose -[nodejs-rel]: https://nodejs.org/en/about/previous-releases -[nodejs-win]: - https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows -[nvm]: - https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating -[nvm-windows]: https://github.com/coreybutler/nvm-windows -[org]: https://github.com/open-telemetry +To learn how to contribute new content and fixes to this project, see +[Contributing](https://opentelemetry.io/docs/contributing/), which includes a +style guide and useful information on the review process. diff --git a/README.md b/README.md index cb27b13cb7c9..72df364c4e56 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,16 @@ to the registry][]. ## Contributing -We have curated some issues with the tags [help wanted][] and [good first -issue][]. This should allow you to quickly find a place to contribute. See [CONTRIBUTING.md][] -for more information. +See the [Contributing](https://opentelemetry.io/docs/contributing) page on our +docs. + +## Found a security issue? + +If you discover a security issue, read the +[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) +before opening an issue. + +## Meetings We, the OTel Communications SIG, meet every two weeks on Monday at 10:00 PT. Check out the [OpenTelemetry community calendar][] for the Zoom link and any @@ -38,6 +45,8 @@ updates to this schedule. Meeting notes are available as a public [Google doc][]. If you have trouble accessing the doc, get in touch in the `#otel-comms` channel on [Slack][]. +## Roles + Here is a list of community roles with current and previous members: - Approvers: [@open-telemetry/docs-approvers][] @@ -82,16 +91,12 @@ contributed][contributors]! [contributing.md]: CONTRIBUTING.md [contributors]: https://github.com/open-telemetry/opentelemetry.io/graphs/contributors -[hugo]: https://gohugo.io -[netlify]: https://netlify.com [opentelemetry]: https://opentelemetry.io [registry]: https://opentelemetry.io/ecosystem/registry/ [opentelemetry community calendar]: https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com -[help wanted]: - https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 -[good first issue]: - https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 [google doc]: https://docs.google.com/document/d/1wW0jLldwXN8Nptq2xmgETGbGn9eWP8fitvD5njM-xZY/edit?usp=sharing [slack]: https://slack.cncf.io/ +[hugo]: https://gohugo.io +[netlify]: https://netlify.com diff --git a/content/en/docs/contributing/_index.md b/content/en/docs/contributing/_index.md index 5a16627ed0fa..5057845e9788 100644 --- a/content/en/docs/contributing/_index.md +++ b/content/en/docs/contributing/_index.md @@ -3,22 +3,8 @@ title: Contributing description: Learn how to contribute to OpenTelemetry documentation. aliases: [/docs/contribution-guidelines] weight: 980 -cSpell:ignore: prepopulated spacewhite --- -The following guide describes how to contribute to OpenTelemetry documentation. -For guidance on how to contribute to the OpenTelemetry project in general, see -the -[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) -, which provides details on the Contributor License Agreement and the Code of -Conduct. In extent, every language implementation, collector, and conventions -[repository](https://github.com/open-telemetry/) has their own specific -contributing guides. - -For documentation, you can open an issue about OpenTelemetry, or contribute a -change with a pull request (PR) to the -[`opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). - OpenTelemetry documentation contributors: - Improve existing content. @@ -26,658 +12,18 @@ OpenTelemetry documentation contributors: - Update the OpenTelemetry Registry. - Improve the code that builds the site. -## Requirements - -To contribute, you need to be familiar with the following techs and tools: - -- [git](https://git-scm.com/) -- [GitHub](https://github.com/) -- Markdown ([CommonMark](https://commonmark.org/)) -- YAML - -For technical details concerning how the documentation is built and tested -locally, see the -[CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md) -file. - -### Sign the CNCF CLA {#sign-the-cla} - -All OpenTelemetry contributors must read the -[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) -and -[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors) -. - -Pull requests from contributors who haven't signed the CLA fail the automated -tests. The name and email you provide must match those found in your -`git config`, and your git name and email must match those used for the CNCF -CLA. - -## Contribute new content - -```mermaid -flowchart LR - subgraph first[How to contribute] - direction TB - T[ ] -.- - B[Fork the repo in GitHub] --- C[Write docs in markdown
and build site with Hugo] - C --- D[Push source to the fork] - D --- E[Open a pull request] - E --- F[Sign the CNCF CLA] - end - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class A,B,C,D,E,F,G,H grey -class S,T spacewhite -class first,second white -``` - -_Figure 1. Contributing new content._ - -The previous figure illustrates how to contribute new documentation. - -To contribute new content pages or improve existing content pages, open a pull -request (PR): - -- If your change is small, or you're unfamiliar with Git, read - [Changes using GitHub](#changes-using-github) to learn how to edit a page. -- If your changes are large, read [Work from a local fork](#fork-the-repo) to - learn how to make changes locally on your computer. - -{{% alert title="Tip" %}} - -Turn your pull request into a draft to signal that the content still isn't ready -for review. Maintainers may still comment or do high-level reviews, though they -won't review the content in full until you remove the draft status. - -{{% /alert %}} - -### Changes using GitHub {#changes-using-github} - -If you're less experienced with Git workflows, here's an easier method of -opening a pull request. Figure 2 outlines the steps and the details follow. - -```mermaid -flowchart LR -A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] -subgraph tasks[Changes using GitHub] -direction TB - 0[ ] -.- - 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] - 2 --> 3[3. fill in Propose file change] - -end -subgraph tasks2[ ] -direction TB -4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] -6 --> 7[7. select Create pull request] -end - -id1 --> tasks --> tasks2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class A,1,2,3,4,5,6,7 grey -class 0 spacewhite -class tasks,tasks2 white -class id1 k8s -``` - -_Figure 2. Steps for opening a PR using GitHub._ - -1. On the page where you see the issue, select the **Edit this page** option in - the right-hand side navigation panel. - -1. If you're not a member of the project, GitHub offers to create a fork of the - repository. Select **Fork this repository**. - -1. Make your changes in the GitHub editor. - -1. Fill in the **Propose file change** form. - -1. Select **Propose file change**. - -1. Select **Create pull request**. - -1. The **Open a pull request** screen appears. Your description helps reviewers - understand your change. - -1. Select **Create pull request**. - -Before merging a pull request, OpenTelemetry community members review and -approve it. - -If a reviewer asks you to make changes: - -1. Go to the **Files changed** tab. -1. Select the pencil (edit) icon on any files changed by the pull request. -1. Make the changes requested. If there's a code suggestion, apply it. -1. Commit the changes. - -When your review is complete, a reviewer merges your PR and your changes goes -live a few minutes later. - -{{% alert title="Tip" %}} - -Comment `/fix:format` on your pull request to trigger an automated check for -formatting issues. - -{{% /alert %}} - -### Work from a local fork {#fork-the-repo} - -If you're more experienced with Git, or if your changes are larger than a few -lines, work from a local fork. - -Make sure you have -[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed -on your computer. You can also use a user interface for Git. - -Figure 3 shows the steps to follow when you work from a local fork. The details -for each step follow. - -```mermaid -flowchart LR -1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] -subgraph changes[Your changes] -direction TB -S[ ] -.- -3[Create a branch
example: my_new_branch] --> 3a[Make changes using
a text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)"] -end -subgraph changes2[Commit / Push] -direction TB -T[ ] -.- -5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] -end - -2 --> changes --> changes2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class 1,2,3,3a,4,5,6 grey -class S,T spacewhite -class changes,changes2 white -``` - -_Figure 3. Working from a local fork to make your changes._ - -#### Fork the opentelemetry.io repository - -1. Navigate to the - [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) - repository. -1. Select **Fork**. - -#### Create a local clone and set the upstream - -1. In a terminal window, clone your fork and install the requirements: - - ```shell - git clone git@github.com:/opentelemetry.io.git - cd opentelemetry.io - npm install - ``` - -1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` - remote: - - ```shell - git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git - ``` - -1. Confirm your `origin` and `upstream` repositories: - - ```shell - git remote -v - ``` - - Output is similar to: - - ```none - origin git@github.com:/opentelemetry.io.git (fetch) - origin git@github.com:/opentelemetry.io.git (push) - upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch) - upstream https://github.com/open-telemetry/opentelemetry.io.git (push) - ``` - -1. Fetch commits from your fork's `origin/main` and - `open-telemetry/opentelemetry.io`'s `upstream/main`: - - ```shell - git fetch origin - git fetch upstream - ``` - - This makes sure your local repository is up to date before you start making - changes. Push changes from upstream to origin regularly to keep your fork in - sync with upstream. - -#### Create a branch - -1. Create a new branch. This example assumes the base branch is `upstream/main`: - - ```shell - git checkout -b upstream/main - ``` - -1. Make your changes using a code or text editor. - -At any time, use the `git status` command to see what files you've changed. - -#### Commit your changes - -When you are ready to submit a pull request, commit your changes. - -1. In your local repository, check which files you need to commit: - - ```shell - git status - ``` - - Output is similar to: - - ```none - On branch - Your branch is up to date with 'origin/'. - - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) - - modified: content/en/docs/file-you-are-editing.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Add the files listed under **Changes not staged for commit** to the commit: - - ```shell - git add - ``` - - Repeat this for each file. - -1. After adding all the files, create a commit: - - ```shell - git commit -m "Your commit message" - ``` - -1. Push your local branch and its new commit to your remote fork: - - ```shell - git push origin - ``` - -1. Once the changes are pushed, GitHub lets you know that you can create a PR. - -#### Open a pull request from your fork {#open-a-pr} - -Figure 4 shows the steps to open a PR from your fork to -[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). - -```mermaid -flowchart LR -subgraph first[ ] -direction TB -1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request] -2 --> 3[3. Select compare across forks] -3 --> 4[4. Select your fork from
head repository drop-down menu] -end -subgraph second [ ] -direction TB -5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] -6 --> 7[7. Add a description
to your PR] -7 --> 8[8. Select Create pull request] -end - -first --> second - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -class 1,2,3,4,5,6,7,8 grey -class first,second white -``` - -_Figure 4. Steps to open a PR from your fork to_ -[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). - -1. In a web browser, go to the - [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) - repository. -1. Select **New Pull Request**. -1. Select **compare across forks**. -1. From the **head repository** drop-down menu, select your fork. -1. From the **compare** drop-down menu, select your branch. -1. Select **Create Pull Request**. -1. Add a description for your pull request: - - - **Title** (50 characters or less): Summarize the intent of the change. - - **Description**: Describe the change in more detail. - - - If there is a related GitHub issue, include `Fixes #12345` or - `Closes #12345` in the description so that GitHub's automation closes the - mentioned issue after merging the PR. If there are other related PRs, - link those as well. - - If you want advice on something specific, include any questions you'd - like reviewers to think about in your description. +The following guides describe how to contribute to OpenTelemetry documentation. -1. Select the **Create pull request** button. - -Your pull request is available in -[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). - -After opening a PR, GitHub runs automated tests and tries to deploy a preview -using [Netlify](https://www.netlify.com/). - -- If the Netlify build fails, select **Details** for more information. -- If the Netlify build succeeds, select **Details** to open a staged version of - the OpenTelemetry website with your changes applied. This is how reviewers - check your changes. - -Other checks might also fail. See the -[list of all PR checks](/docs/contributing/pr-checks). - -#### Fix content issues automatically - -Before submitting a change to the repository, run the following command and (i) -address any reported issues, (ii) commit any files changed by the script: - -```sh -npm run test-and-fix -``` - -To separately test and fix all issues with your files, run: - -```sh -npm run test # Checks but does not update any files -npm run fix:all # May update files -``` - -To list available NPM scripts, run `npm run`. - -#### Preview your changes locally {#preview-locally} - -Preview your changes locally before pushing them or opening a pull request. A -preview lets you catch build errors or markdown formatting problems. - -To build and serve the site locally with Hugo, run the following command: - -```shell -npm run serve -``` - -Navigate to `http://localhost:1313` in your web browser to see the local -preview. Hugo watches for changes and rebuilds the site as needed. - -To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or -close the terminal window. - -#### Site deploys and PR previews - -If you submit a PR, Netlify creates a [deploy preview][] so that you can review your -changes. Once your PR is merged, Netlify deploys the updated site to the production -server. - -> **Note**: PR previews include _draft pages_, but production builds do not. - -To see deploy logs and more, visit the project's [dashboard][] -- Netlify login -required. - -#### PR guidelines - -Before a PR gets merged, it sometimes requires a few iterations of -review-and-edit. To help us and yourself make this process as easy as possible, -we ask that you adhere to the following: - -- If your PR isn't a quick fix, 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). - -#### Changes from reviewers - -Sometimes reviewers commit to your pull request. Before making any other -changes, fetch those commits. - -1. Fetch commits from your remote fork and rebase your working branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - -1. After rebasing, force-push new changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -You can also solve merge conflicts from the GitHub UI. - -#### Merge conflicts and rebasing - -If another contributor commits changes to the same file in another PR, it can -create a merge conflict. You must resolve all merge conflicts in your PR. - -1. Update your fork and rebase your local branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - - Then force-push the changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and - rebase your branch: - - ```shell - git fetch upstream - git rebase upstream/main - ``` - -1. Inspect the results of the rebase: - - ```shell - git status - ``` - - This results in a number of files marked as conflicted. - -1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, - and `===`. Resolve the conflict and delete the conflict marker. - - For more information, see - [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). - -1. Add the files to the changeset: - - ```shell - git add - ``` - -1. Continue the rebase: - - ```shell - git rebase --continue - ``` - -1. Repeat steps 2 to 5 as needed. - - After applying all commits, the `git status` command shows that the rebase is - complete. - -1. Force-push the branch to your fork: - - ```shell - git push --force-with-lease origin - ``` - - The pull request no longer shows any conflicts. - -#### Merge requirements - -Pull requests are merged when they comply with the following criteria: - -- All reviews by approvers, maintainers, technical committee members, or subject - matter experts have the status "Approved". -- 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 behalf. - -## Open an issue - -If you notice an error or want to suggest improvements to existing content, open -an issue. - -1. Click the **Create documentation issue** link on any document. This redirects - you to a GitHub issue page prepopulated with some headers. -2. Describe the issue or suggestion for improvement. Provide as many details as - you can. -3. Click **Submit new issue**. - -After submitting, check in on your issue occasionally or turn on GitHub -notifications. It might take a few days until maintainers and approvers respond. -Reviewers and other community members might ask questions before they can take -action on your issue. - -### Suggesting new content or features - -If you have an idea for new content or a feature, but you aren't sure where it -should go, you can still file an issue. You can also report bugs and security -vulnerabilities. - -1. Go to - [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and - select **New issue** inside the **Issues** tab. - -1. Select the type of issue that best applies to your request or doubt. - -1. Fill out the template. - -1. Submit the issue. - -### How to file great issues - -Keep the following in mind when filing an issue: - -- Provide a clear issue description. Describe what specifically is missing, out - of date, wrong, or needs improvement. -- Explain the specific impact the issue has on users. -- Limit the scope of a given issue to a reasonable unit of work. For problems - with a large scope, break them down into smaller issues. For example, "Fix the - security docs" is too broad, but "Add details to the 'Restricting network - access' topic" is specific enough to be actionable. -- Search the existing issues to see if there's anything related or similar to - the new issue. -- If the new issue relates to another issue or pull request, refer to it either - by its full URL or by the issue or pull request number prefixed with a `#` - character. For example, `Introduced by #987654`. -- Follow the - [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). - Respect your fellow contributors. For example, "The docs are terrible" is not - helpful or polite feedback. - -## Announcement management - -An announcement is a _regular Hugo page_ contained under the `announcements` -section of a locale. This means that we leverage Hugo's builtin handling of page -dates (future or expired), internationalization, and more, to automatically show -or hide banners depending on the build date, determine banner ordering, handle -fall back to English banners, etc. - -> Announcements are currently used as banners only. We _might_ eventually -> support slightly more general announcements as well. - -### Creating an announcement - -To add a new announcement, create an announcement markdown file under the -`announcements` folder of your localization using the following command: - -```sh -hugo new --kind announcement content/YOUR-LOCALE/announcements/announcement-file-name.md -``` - -Adjust according to your desired locale and file name. Add the announcement text -as the body of the page. - -> For banners, the announcement body should be a short phrase. - -{{% alert title="For localizations" %}} - -If you are creating a **locale specific announcement override**, make sure that -you use the **same filename** as the English language announcement. - -{{% /alert %}} - -### Announcement list - -Any given announcement will appear in a site build when the build date falls -between the `date` and `expiryDate` fields of the announcement. When those -fields are missing they are assumed to be "now" and "forever", respectively. - -Announcements will appear in the standard page order as determined using Hugo's -[Regular pages](https://gohugo.io/methods/site/regularpages/) function. That is, -the "lightest" announcements (by `weight`) will appear first; when weights are -the same or unspecified, the most recent announcements (by `date`) will appear -first, etc. - -So, if you want to force an announcement to the top, use a negative `weight` in -the front matter. - -## Contribute to other repositories - -OpenTelemetry is an open source project, and we gladly accept new contributions -and contributors. See the CONTRIBUTING.md file in each SIG repository for -information on getting started. - -Individual SIGs may maintain documentation above and beyond what is offered -here, but we strive for accurate general guidance on using the project from our -main website. - -If you see text you'd like to improve, use GitHub to search all repositories in -the OpenTelemetry organization. This can help you figure out where to submit -your issue or PR. Each repository has its own processes and procedures. Before -you file an issue or submit a PR, read that repository's `README.md`, -`CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist. - -Most repositories use issue and PR templates. Have a look through some open -issues and PRs to get a feel for that team's processes. Make sure to fill out -the templates with as much detail as possible when you file issues or PRs. +For guidance on how to contribute to the OpenTelemetry project in general, see +the +[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +, which provides details on the Contributor License Agreement and the Code of +Conduct. Every language implementation, Collector, and conventions +[repository](https://github.com/open-telemetry/) has its own specific +contributing guides. ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). - Submit a [blog post or case study](/docs/contributing/blog/). - -[dashboard]: https://app.netlify.com/sites/opentelemetry/overview -[deploy preview]: - https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ - -## Code of conduct - -OpenTelemetry follows the -[CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/content/en/docs/contributing/announcements.md b/content/en/docs/contributing/announcements.md new file mode 100644 index 000000000000..808ee7f902b7 --- /dev/null +++ b/content/en/docs/contributing/announcements.md @@ -0,0 +1,68 @@ +--- +title: Announcements +description: Create announcements or banners for special events. +weight: 50 +--- + +An announcement is a _regular Hugo page_ contained under the `announcements` +section of a locale. This means that we leverage Hugo's builtin handling of page +dates (future or expired), internationalization, and more, to automatically show +or hide banners depending on the build date, determine banner ordering, handle +fall back to English banners, etc. + +> Announcements are currently used as banners only. We _might_ eventually +> support slightly more general announcements as well. + +### Creating an announcement + +To add a new announcement, create an announcement markdown file under the +`announcements` folder of your localization using the following command: + +```sh +hugo new --kind announcement content/YOUR-LOCALE/announcements/announcement-file-name.md +``` + +Adjust according to your desired locale and file name. Add the announcement text +as the body of the page. + +> For banners, the announcement body should be a short phrase. + +{{% alert title="For localizations" %}} + +If you are creating a **locale specific announcement override**, make sure that +you use the **same filename** as the English language announcement. + +{{% /alert %}} + +### Announcement list + +Any given announcement will appear in a site build when the build date falls +between the `date` and `expiryDate` fields of the announcement. When those +fields are missing they are assumed to be "now" and "forever", respectively. + +Announcements will appear in the standard page order as determined using Hugo's +[Regular pages](https://gohugo.io/methods/site/regularpages/) function. That is, +the "lightest" announcements (by `weight`) will appear first; when weights are +the same or unspecified, the most recent announcements (by `date`) will appear +first, etc. + +So, if you want to force an announcement to the top, use a negative `weight` in +the front matter. + +If you find a bug or a problem with the content of this repository, or you would +like to request an enhancement, [create an issue][new-issue]. + +If you discover a security issue, read the +[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) +before opening an issue. + +Before reporting a new issue, make sure 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 a clear +description. Add as much relevant information as you can, and, if possible, a +test case. + +[new-issue]: + https://github.com/open-telemetry/opentelemetry.io/issues/new/choose diff --git a/content/en/docs/contributing/development.md b/content/en/docs/contributing/development.md new file mode 100644 index 000000000000..28b05d316f38 --- /dev/null +++ b/content/en/docs/contributing/development.md @@ -0,0 +1,171 @@ +--- +title: Development +description: + Learn how to set up a development environment for the opentelemetry.io site. +weight: 60 +--- + +The following instructions explain how to set up a development environment for +the website. + +## Cloud-IDE setup + +These instructions are for [Gitpod.io][], adjust as needed for your favorite +cloud IDE: + +1. Fork this repository. For help, see [Fork a repository][fork]. +2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or + open an existing workspace over your fork. You can also visit a link of the + form: + . + + > **Note**: If you have the necessary permissions to work from this + > repository, or just want to look around, open + > . + +Gitpod automatically installs the repo-specific packages for you. + +You're now ready to [build](#build), [serve](#serve) or make updates to the +website files. + +## Local setup + +1. [Fork][] and then [clone][] this repository. +2. Go to the repository directory. +3. Install or upgrade to the [**active LTS** release][nodejs-rel] of Node.js. + We recommend using [nvm][] to manage your Node installation. Under Linux, + run the following command, which will install and upgrade to the version + specified in the .nvmrc file: + + ```sh + nvm install + ``` + + To [install under Windows][nodejs-win], use [nvm-windows][]: + + ```cmd + > nvm install lts && nvm use lts + ``` + +4. Get npm packages and other prerequisites: + + ```sh + npm install + ``` + +You're now ready to [build](#build), [serve](#serve) or make updates to the +website files. + +### Build + +To build the site run: + +```sh +npm run build +``` + +The generated site files are under `public`. + +### Serve + +To serve the site run: + +```sh +npm run serve +``` + +The site is served at [localhost:1313][]. + +If you need to test [Netlify] redirects, use the following command and visit the +site at [localhost:8888][]: + +```sh +npm run serve:netlify +``` + +The serve command serves files from memory, not from disk. + +If you see an error like `too many open files` or `pipe failed` under macOS, you +might need to increase the file descriptor limit. See +[Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109). + +### Content and submodules + +The website is built from the following content: + +- Files under `content/`, `static/`, etc. per [Hugo][] defaults. +- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either + directly from git submodules under [content-modules][], or preprocessed + content from `content-modules` (placed under `tmp/`), and no where else. + +[hugo.yaml]: + https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml +[content-modules]: + https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules + +### Submodule changes + +If you change any content inside of a [content-modules][] submodule, then you +need to first submit a PR (containing the submodule changes) to the submodule's +repository. Only after the submodule PR has been accepted, can you update the +submodule and have the changes appear in this website. + +It's easiest to manage your `content-modules` changes by working with the +repository that the corresponding submodule is linked to, rather than inside the +submodule itself. + +Expert contributors can work directly in the submodule. You are then able to +directly build and serve your (submodule) changes. By default, the CI scripts +get submodules on every invocation. To prevent this behavior while you work +within a submodule, set the environment variable `GET=no`. You also need to run +`git fetch --unshallow` the submodule before you can submit a PR. Alternatively, +set `DEPTH=100` and re-fetch submodules. + +## Approver and maintainer practices + +This last section includes guidelines and some common practices used by +approvers and maintainers while doing code reviews: + +- PRs with changes to documentation co-owned by a SIG (collector, demo, + language-specific...) should aim for two approvals: one by a docs approver and + one by a SIG approver: + - Doc approver label such PRs with `sig:` and tag the SIG `-approvers` + group on that PR + - If no SIG approval is given within a certain grace period (two weeks in + general, but may be less in urgent cases), docs maintainer may use their own + judgement to merge that PR +- If the PR branch is `out-of-date with the base branch`, they do not need to be + updated continuously: every update triggers all the PR CI checks to be run! + It's often enough to update them before merging. +- A PR by non-maintainers should **never** update git sub modules. This happens + by accident from time to time. Let the PR author know that they should not + worry about it, we will fix this before merging, but in the future they should + make sure that they work from an up-to-date fork. +- If the contributor is having trouble signing the CLA or used the wrong email + by mistake in one of their commits, ask them to fix the issue or rebase the + pull request. Worst case scenario, close and re-open the PR to trigger a new + CLA check. +- Words unknown to cspell should be added to the cspell ignore list per page by + PR authors. Only approvers and maintainers will add commonly used terms to the + global list. +- When an approver or maintainer won't be available to contribute for an + extended period of time (more than a few days or a week) or won't be available + in that period of time, they should communicate this using the + [#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and + updating the GitHub status. + +[clone]: + https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository +[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo +[gitpod.io]: https://gitpod.io +[gitpod.io/workspaces]: https://gitpod.io/workspaces +[hugo]: https://gohugo.io +[localhost:1313]: http://localhost:1313 +[localhost:8888]: http://localhost:8888 +[netlify]: https://netlify.com +[nodejs-rel]: https://nodejs.org/en/about/previous-releases +[nodejs-win]: + https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows +[nvm]: + https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating +[nvm-windows]: https://github.com/coreybutler/nvm-windows diff --git a/content/en/docs/contributing/issues.md b/content/en/docs/contributing/issues.md new file mode 100644 index 000000000000..4aeca18c85e9 --- /dev/null +++ b/content/en/docs/contributing/issues.md @@ -0,0 +1,57 @@ +--- +title: Reporting an issue +description: How to report a bug, a security issue, or a potential improvement. +weight: 50 +cSpell:ignore: prepopulated +--- + +If you notice an error or want to suggest improvements to existing content, open +an issue. + +1. Click the **Create documentation issue** link on any document. This redirects + you to a GitHub issue page prepopulated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as + you can. +3. Click **Submit new issue**. + +After submitting, check in on your issue occasionally or turn on GitHub +notifications. It might take a few days until maintainers and approvers respond. +Reviewers and other community members might ask questions before they can take +action on your issue. + +## Suggesting new content or features + +If you have an idea for new content or a feature, but you aren't sure where it +should go, you can still file an issue. You can also report bugs and security +vulnerabilities. + +1. Go to + [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and + select **New issue** inside the **Issues** tab. + +1. Select the type of issue that best applies to your request or doubt. + +1. Fill out the template. + +1. Submit the issue. + +### How to file great issues + +Keep the following in mind when filing an issue: + +- Provide a clear issue description. Describe what specifically is missing, out + of date, wrong, or needs improvement. +- Explain the specific impact the issue has on users. +- Limit the scope of a given issue to a reasonable unit of work. For problems + with a large scope, break them down into smaller issues. For example, "Fix the + security docs" is too broad, but "Add details to the 'Restricting network + access' topic" is specific enough to be actionable. +- Search the existing issues to see if there's anything related or similar to + the new issue. +- If the new issue relates to another issue or pull request, refer to it either + by its full URL or by the issue or pull request number prefixed with a `#` + character. For example, `Introduced by #987654`. +- Follow the + [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). + Respect your fellow contributors. For example, "The docs are terrible" is not + helpful or polite feedback. diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md index b5c07db3c6d4..c66647d64a59 100644 --- a/content/en/docs/contributing/localization.md +++ b/content/en/docs/contributing/localization.md @@ -3,7 +3,7 @@ title: Site localization description: Guidance on creating and maintaining site page in non-English localizations. linkTitle: Localization -weight: 20 +weight: 25 --- {{% pageinfo color="warning" %}} diff --git a/content/en/docs/contributing/new-content.md b/content/en/docs/contributing/new-content.md new file mode 100644 index 000000000000..7ccb57284f95 --- /dev/null +++ b/content/en/docs/contributing/new-content.md @@ -0,0 +1,503 @@ +--- +title: Add new content +description: Learn how to add new content using GitHub UI or a local fork. +weight: 2 +--- + +To contribute new content pages or improve existing content pages, open a pull +request (PR): + +- If your change is small, or you're unfamiliar with Git, read + [Changes using GitHub](#changes-using-github) to learn how to edit a page. +- If your changes are large, read [Work from a local fork](#fork-the-repo) to + learn how to make changes locally on your computer. + +{{% alert title="Tip" %}} + +Turn your pull request into a draft to signal that the content still isn't ready +for review. Maintainers may still comment or do high-level reviews, though they +won't review the content in full until you remove the draft status. + +{{% /alert %}} + +The following figure illustrates how to contribute new documentation. + +```mermaid +flowchart LR + subgraph first[How to contribute] + direction TB + T[ ] -.- + B[Fork the repo in GitHub] --- C[Write docs in markdown
and build site with Hugo] + C --- D[Push source to the fork] + D --- E[Open a pull request] + E --- F[Sign the CNCF CLA] + end + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,C,D,E,F,G,H grey +class S,T spacewhite +class first,second white +``` + +_Figure 1. Contributing new content._ + +## Changes using GitHub {#changes-using-github} + +If you're less experienced with Git workflows, here's an easier method of +opening a pull request. Figure 2 outlines the steps and the details follow. + +```mermaid +flowchart LR +A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] +subgraph tasks[Changes using GitHub] +direction TB + 0[ ] -.- + 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] + 2 --> 3[3. fill in Propose file change] + +end +subgraph tasks2[ ] +direction TB +4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] +6 --> 7[7. select Create pull request] +end + +id1 --> tasks --> tasks2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,1,2,3,4,5,6,7 grey +class 0 spacewhite +class tasks,tasks2 white +class id1 k8s +``` + +_Figure 2. Steps for opening a PR using GitHub._ + +1. On the page where you see the issue, select the **Edit this page** option in + the right-hand side navigation panel. + +1. If you're not a member of the project, GitHub offers to create a fork of the + repository. Select **Fork this repository**. + +1. Make your changes in the GitHub editor. + +1. Fill in the **Propose file change** form. + +1. Select **Propose file change**. + +1. Select **Create pull request**. + +1. The **Open a pull request** screen appears. Your description helps reviewers + understand your change. + +1. Select **Create pull request**. + +Before merging a pull request, OpenTelemetry community members review and +approve it. + +If a reviewer asks you to make changes: + +1. Go to the **Files changed** tab. +1. Select the pencil (edit) icon on any files changed by the pull request. +1. Make the changes requested. If there's a code suggestion, apply it. +1. Commit the changes. + +When your review is complete, a reviewer merges your PR and your changes goes +live a few minutes later. + +{{% alert title="Tip" %}} + +Comment `/fix:format` on your pull request to trigger an automated check for +formatting issues. + +{{% /alert %}} + +## Work from a local fork {#fork-the-repo} + +If you're more experienced with Git, or if your changes are larger than a few +lines, work from a local fork. + +Make sure you have +[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +on your computer. You can also use a user interface for Git. + +Figure 3 shows the steps to follow when you work from a local fork. The details +for each step follow. + +```mermaid +flowchart LR +1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] +subgraph changes[Your changes] +direction TB +S[ ] -.- +3[Create a branch
example: my_new_branch] --> 3a[Make changes using
a text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)"] +end +subgraph changes2[Commit / Push] +direction TB +T[ ] -.- +5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] +end + +2 --> changes --> changes2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class 1,2,3,3a,4,5,6 grey +class S,T spacewhite +class changes,changes2 white +``` + +_Figure 3. Working from a local fork to make your changes._ + +### Fork the opentelemetry.io repository + +1. Navigate to the + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) + repository. +1. Select **Fork**. + +### Create a local clone and set the upstream + +1. In a terminal window, clone your fork and install the requirements: + + ```shell + git clone git@github.com:/opentelemetry.io.git + cd opentelemetry.io + npm install + ``` + +1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` + remote: + + ```shell + git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git + ``` + +1. Confirm your `origin` and `upstream` repositories: + + ```shell + git remote -v + ``` + + Output is similar to: + + ```none + origin git@github.com:/opentelemetry.io.git (fetch) + origin git@github.com:/opentelemetry.io.git (push) + upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch) + upstream https://github.com/open-telemetry/opentelemetry.io.git (push) + ``` + +1. Fetch commits from your fork's `origin/main` and + `open-telemetry/opentelemetry.io`'s `upstream/main`: + + ```shell + git fetch origin + git fetch upstream + ``` + + This makes sure your local repository is up to date before you start making + changes. Push changes from upstream to origin regularly to keep your fork in + sync with upstream. + +### Create a branch + +1. Create a new branch. This example assumes the base branch is `upstream/main`: + + ```shell + git checkout -b upstream/main + ``` + +1. Make your changes using a code or text editor. + +At any time, use the `git status` command to see what files you've changed. + +### Commit your changes + +When you are ready to submit a pull request, commit your changes. + +1. In your local repository, check which files you need to commit: + + ```shell + git status + ``` + + Output is similar to: + + ```none + On branch + Your branch is up to date with 'origin/'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: content/en/docs/file-you-are-editing.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Add the files listed under **Changes not staged for commit** to the commit: + + ```shell + git add + ``` + + Repeat this for each file. + +1. After adding all the files, create a commit: + + ```shell + git commit -m "Your commit message" + ``` + +1. Push your local branch and its new commit to your remote fork: + + ```shell + git push origin + ``` + +1. Once the changes are pushed, GitHub lets you know that you can create a PR. + +### Open a pull request from your fork {#open-a-pr} + +Figure 4 shows the steps to open a PR from your fork to +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). + +```mermaid +flowchart LR +subgraph first[ ] +direction TB +1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request] +2 --> 3[3. Select compare across forks] +3 --> 4[4. Select your fork from
head repository drop-down menu] +end +subgraph second [ ] +direction TB +5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] +6 --> 7[7. Add a description
to your PR] +7 --> 8[8. Select Create pull request] +end + +first --> second + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +class 1,2,3,4,5,6,7,8 grey +class first,second white +``` + +_Figure 4. Steps to open a PR from your fork to_ +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). + +1. In a web browser, go to the + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) + repository. +1. Select **New Pull Request**. +1. Select **compare across forks**. +1. From the **head repository** drop-down menu, select your fork. +1. From the **compare** drop-down menu, select your branch. +1. Select **Create Pull Request**. +1. Add a description for your pull request: + + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. + + - If there is a related GitHub issue, include `Fixes #12345` or + `Closes #12345` in the description so that GitHub's automation closes the + mentioned issue after merging the PR. If there are other related PRs, + link those as well. + - If you want advice on something specific, include any questions you'd + like reviewers to think about in your description. + +1. Select the **Create pull request** button. + +Your pull request is available in +[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). + +After opening a PR, GitHub runs automated tests and tries to deploy a preview +using [Netlify](https://www.netlify.com/). + +- If the Netlify build fails, select **Details** for more information. +- If the Netlify build succeeds, select **Details** to open a staged version of + the OpenTelemetry website with your changes applied. This is how reviewers + check your changes. + +Other checks might also fail. See the +[list of all PR checks](/docs/contributing/pr-checks). + +### Fix content issues automatically + +Before submitting a change to the repository, run the following command and (i) +address any reported issues, (ii) commit any files changed by the script: + +```sh +npm run test-and-fix +``` + +To separately test and fix all issues with your files, run: + +```sh +npm run test # Checks but does not update any files +npm run fix:all # May update files +``` + +To list available NPM scripts, run `npm run`. See +[PR checks](/docs/contributing/pr-checks) for more information on pull request +checks and how to fix errors automatically. + +### Preview your changes locally {#preview-locally} + +Preview your changes locally before pushing them or opening a pull request. A +preview lets you catch build errors or markdown formatting problems. + +To build and serve the site locally with Hugo, run the following command: + +```shell +npm run serve +``` + +Navigate to `http://localhost:1313` in your web browser to see the local +preview. Hugo watches for changes and rebuilds the site as needed. + +To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or +close the terminal window. + +### Site deploys and PR previews + +If you submit a PR, Netlify creates a [deploy preview][] so that you can review your +changes. Once your PR is merged, Netlify deploys the updated site to the production +server. + +> **Note**: PR previews include _draft pages_, but production builds do not. + +To see deploy logs and more, visit the project's [dashboard][] -- Netlify login +required. + +### PR guidelines + +Before a PR gets merged, it sometimes requires a few iterations of +review-and-edit. To help us and yourself make this process as easy as possible, +we ask that you adhere to the following: + +- If your PR isn't a quick fix, 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). + +### Changes from reviewers + +Sometimes reviewers commit to your pull request. Before making any other +changes, fetch those commits. + +1. Fetch commits from your remote fork and rebase your working branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + +1. After rebasing, force-push new changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +You can also solve merge conflicts from the GitHub UI. + +### Merge conflicts and rebasing + +If another contributor commits changes to the same file in another PR, it can +create a merge conflict. You must resolve all merge conflicts in your PR. + +1. Update your fork and rebase your local branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + + Then force-push the changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and + rebase your branch: + + ```shell + git fetch upstream + git rebase upstream/main + ``` + +1. Inspect the results of the rebase: + + ```shell + git status + ``` + + This results in a number of files marked as conflicted. + +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, + and `===`. Resolve the conflict and delete the conflict marker. + + For more information, see + [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + +1. Add the files to the changeset: + + ```shell + git add + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Repeat steps 2 to 5 as needed. + + After applying all commits, the `git status` command shows that the rebase is + complete. + +1. Force-push the branch to your fork: + + ```shell + git push --force-with-lease origin + ``` + + The pull request no longer shows any conflicts. + +### Merge requirements + +Pull requests are merged when they comply with the following criteria: + +- All reviews by approvers, maintainers, technical committee members, or subject + matter experts have the status "Approved". +- 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 behalf. + +[dashboard]: https://app.netlify.com/sites/opentelemetry/overview +[deploy preview]: + https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ diff --git a/content/en/docs/contributing/pr-checks.md b/content/en/docs/contributing/pr-checks.md index 64b1e2d9ae0a..d59ce9abcb47 100644 --- a/content/en/docs/contributing/pr-checks.md +++ b/content/en/docs/contributing/pr-checks.md @@ -19,7 +19,7 @@ a set of checks are executed. The PR checks verify that... {{% alert title="Note" color="primary" %}} If any of the PR checks fails, please try to -[fix content issues automatically](/docs/contributing/#fix-content-issues-automatically) +[fix content issues automatically](/docs/contributing/new-content/#fix-content-issues-automatically) first by running `npm run fix:all` on your machine. Additionally, you can comment `/fix:all` on your Pull Request. This will make @@ -34,7 +34,7 @@ can recover from a failed state. ## Easy CLA This check fails if you haven't -[signed the CLA](/docs/contributing/#sign-the-cla). +[signed the CLA](/docs/contributing/requirements/#sign-the-cla). ## Netlify deployment diff --git a/content/en/docs/contributing/requirements.md b/content/en/docs/contributing/requirements.md new file mode 100644 index 000000000000..cd90ca36161f --- /dev/null +++ b/content/en/docs/contributing/requirements.md @@ -0,0 +1,33 @@ +--- +title: Requirements +description: + To contribute, you need to be familiar with the following techs and tools. +weight: 1 +--- + +To contribute, you need to be familiar with the following techs and tools: + +- [git](https://git-scm.com/) +- [GitHub](https://github.com/) +- Markdown ([CommonMark](https://commonmark.org/)) +- YAML + +For technical details concerning how the documentation is built and tested +locally, see [Development](/docs/contributing/development). + +## Sign the CNCF CLA {#sign-the-cla} + +All OpenTelemetry contributors must read the +[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +and +[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors). + +Pull requests from contributors who haven't signed the CLA fail the automated +tests. The name and email you provide must match those found in your +`git config`, and your git name and email must match those used for the CNCF +CLA. + +## Code of conduct + +OpenTelemetry follows the +[CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/content/en/docs/contributing/style-guide.md b/content/en/docs/contributing/style-guide.md index 3d3341733982..2ccf5400367c 100644 --- a/content/en/docs/contributing/style-guide.md +++ b/content/en/docs/contributing/style-guide.md @@ -1,7 +1,8 @@ --- title: Documentation style guide +description: Terminology and style when writing OpenTelemetry docs. linkTitle: Style guide -weight: 10 +weight: 20 cSpell:ignore: open-telemetry postgre style-guide textlintrc --- @@ -22,7 +23,7 @@ before submitting a (PR), run `npm run fix:all` on your local machine and commit the changes. If you run into errors or [failed PR checks](/docs/contributing/pr-checks), read -about our style guide below and what you can do to fix certain common issues. +about our style guide and learn what you can do to fix certain common issues. {{% /alert %}} @@ -36,7 +37,7 @@ the site. | --- | --- | | OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. | | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | -| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | +| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. Write "The Collector" or "The Opentelemetry Collector" if you're starting a sentence. Write "the Collector" or "the OpenTelemetry Collector" in the middle or end of a sentence. Use just "Collector" if you are using Collector as an adjective (for example, "Collector configuration").| | OTEP | OpenTelemetry Enhancement Proposal. Write "OTEPs" as plural form. Don't write "OTep" or "otep". | | OpAMP | Open Agent Management Protocol. Don't write "OPAMP" or "opamp" in descriptions or instructions. | diff --git a/static/refcache.json b/static/refcache.json index 0943e0b7b65e..d29d9abe4deb 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1115,6 +1115,10 @@ "StatusCode": 206, "LastSeen": "2024-02-15T11:30:46.466434+01:00" }, + "https://docs.github.com/en/get-started/quickstart/fork-a-repo": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:07.765039+02:00" + }, "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests": { "StatusCode": 206, "LastSeen": "2024-01-30T15:25:17.633498-05:00" @@ -1127,6 +1131,10 @@ "StatusCode": 206, "LastSeen": "2024-01-30T16:15:52.403553-05:00" }, + "https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:20.570863+02:00" + }, "https://docs.google.com/document/d/15vR7D1x2tKd7u3zaTF0yH1WaHkUr2T4hhr7OyiZgmBg/edit#heading=h.4xuru5ljcups": { "StatusCode": 200, "LastSeen": "2024-01-18T08:53:29.813821-05:00" @@ -1371,6 +1379,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T15:25:34.070633-05:00" }, + "https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows": { + "StatusCode": 200, + "LastSeen": "2024-06-12T11:21:28.721143+02:00" + }, "https://docs.microsoft.com/rest/api/resources/resources/get-by-id": { "StatusCode": 200, "LastSeen": "2024-01-30T16:14:41.535288-05:00" @@ -2511,6 +2523,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T06:02:26.156181-05:00" }, + "https://github.com/coreybutler/nvm-windows": { + "StatusCode": 200, + "LastSeen": "2024-06-12T11:21:31.676115+02:00" + }, "https://github.com/cri-o/cri-o": { "StatusCode": 200, "LastSeen": "2024-01-30T06:02:13.062841-05:00" @@ -2683,6 +2699,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T16:14:59.006242-05:00" }, + "https://github.com/gohugoio/hugo/issues/6109": { + "StatusCode": 200, + "LastSeen": "2024-06-12T11:21:46.656082+02:00" + }, "https://github.com/gosnmp/gosnmp": { "StatusCode": 200, "LastSeen": "2024-01-18T19:55:40.84138-05:00" @@ -4279,6 +4299,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T16:15:47.00387-05:00" }, + "https://github.com/open-telemetry/opentelemetry.io/issues": { + "StatusCode": 200, + "LastSeen": "2024-06-13T15:48:00.42543+02:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/4427": { "StatusCode": 200, "LastSeen": "2024-05-06T15:32:24.49099-04:00" @@ -4303,6 +4327,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T16:15:25.833527-05:00" }, + "https://github.com/open-telemetry/opentelemetry.io/security/policy": { + "StatusCode": 200, + "LastSeen": "2024-06-13T15:47:57.766697+02:00" + }, "https://github.com/open-telemetry/otel-arrow": { "StatusCode": 200, "LastSeen": "2024-01-30T16:15:31.46184-05:00" @@ -4719,6 +4747,22 @@ "StatusCode": 200, "LastSeen": "2024-01-18T19:13:35.287029-05:00" }, + "https://gitpod.io": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:04.801578+02:00" + }, + "https://gitpod.io#https://github.com/YOUR_GITHUB_ID/opentelemetry.io": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:16.984715+02:00" + }, + "https://gitpod.io/#https://github.com/open-telemetry/opentelemetry.io": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:18.187197+02:00" + }, + "https://gitpod.io/workspaces": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:11.528217+02:00" + }, "https://go.dev/": { "StatusCode": 200, "LastSeen": "2024-01-30T15:25:10.378732-05:00" @@ -4807,6 +4851,10 @@ "StatusCode": 206, "LastSeen": "2024-01-30T16:05:33.151121-05:00" }, + "https://gohugo.io": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:44.81351+02:00" + }, "https://gohugo.io/content-management/multilingual/": { "StatusCode": 206, "LastSeen": "2024-06-06T14:51:47.628909-04:00" @@ -5635,6 +5683,10 @@ "StatusCode": 200, "LastSeen": "2024-01-18T19:02:19.249572-05:00" }, + "https://netlify.com": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:36.089536+02:00" + }, "https://newrelic.com/": { "StatusCode": 206, "LastSeen": "2024-02-26T10:53:38.368111+01:00" @@ -5699,6 +5751,10 @@ "StatusCode": 206, "LastSeen": "2024-01-18T19:10:39.6518-05:00" }, + "https://nodejs.org/en/about/previous-releases": { + "StatusCode": 206, + "LastSeen": "2024-06-12T11:21:22.384836+02:00" + }, "https://nodejs.org/en/blog/module/service-logging-in-json-with-bunyan/": { "StatusCode": 206, "LastSeen": "2024-01-18T19:10:50.84564-05:00"