diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94a3bcf27a6e..f15f09d170cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,53 @@ # Contributing to OpenTelemetry.io -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 +**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 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. +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 -Also review the general +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 +as it provides additional details, especially that you need to sign a Contributor License Agreement (CLA) before you can contribute. -## Found a security issue? +### 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). +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? +### 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]. +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, please ensure that the issue was not already -reported or fixed by searching through our +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 clear a -description, as much relevant information as possible, and, if possible, a test -case. +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? +### 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 @@ -59,64 +66,11 @@ 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. After forking the repository, follow the instructions -in [Editing files][]. - -However, formatting may still be needed, like reducing line lengths in the -edited file. The options for fixing formatting are: - -- Checking out the project and running the CLI scripts mentioned in - [Submitting a change](#submitting-a-change). -- Commenting `/fix:format` on your pull request to trigger an automated script. - This requires a unique branch name, which can be edited under _View all - branches_ in your fork. - -For larger fixes, follow the -[instructions to setup a development environment](#development) below. - -### PR Guidelines - -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 +## Contributor's guide -- 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. +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/content/en/docs/contributing), which includes a style +guide and useful information on the review process. ## Development @@ -219,24 +173,6 @@ The website is built from the following content: [content-modules]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules -### Submitting a change - -Before submitting a change 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 -``` - -To separately test and fix issues with your files, run: - -```sh -npm run test # checks but does not update any files -npm run fix # may update files -``` - -To list available NPM scripts, run `npm run`. - ### Submodule changes If you change any content inside of a [content-modules][] submodule, then you'll @@ -255,17 +191,6 @@ 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 - -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 -the production server. - -> **Note**: PR previews include _draft pages_, but production builds do not. - -To see deploy logs and more, visit project's [dashboard][] -- Netlify login -required. - ## Approver and Maintainer practices This last section includes guidelines and some common practices used by @@ -302,18 +227,12 @@ approvers and maintainers while doing code reviews: [.nvmrc]: .nvmrc [clone]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[dashboard]: https://app.netlify.com/sites/opentelemetry/overview -[deploy preview]: - https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ -[editing files]: - https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files [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 @@ -323,5 +242,3 @@ approvers and maintainers while doing code reviews: 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 -[pr]: - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests diff --git a/README.md b/README.md index ae4de4622615..716841e21c0d 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,42 @@ # OTel logo OpenTelemetry.io This is the source repository for the [OpenTelemetry][] website, project -documentation and blog. The site is [built][contributing.md] using [Hugo][] and -hosted on [Netlify][]. +documentation, and blog. The site is [built][contributing.md] using [Hugo][] and +is hosted on [Netlify][]. ## Get involved +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/content/en/docs/contributing), which includes a style +guide and useful information on the review process. + If you are new to OpenTelemetry and just get started with it, you are in a perfect position to help us get better: the website and documentation is the entry point for newcomers like you, so if something is unclear or something is -missing [let us know][]! - -Read on to learn about other ways on how you can help. - -## Adding a project to the OpenTelemetry [Registry] - -For details, see [Adding to the registry][]. - -## Submitting a blog post - -You can submit a blog post either by forking this repository and writing it -locally or by using the GitHub UI. In both cases we ask you to follow the -instructions provided by the [blog post template](archetypes/blog.md). - -**Note**: Before writing a blog post, please ask yourself, if your content also -might be a good addition to the documentation. If the answer is yes, create a -new issue/PR with your content to get it added to the docs. +missing [let us know][]. -### Fork & Write locally +### Submit a blog post -Follow the [setup instructions][contributing.md] then, to create a skeletal blog -post, run the following command from the repository root: +For guidance on how to write and submit a blog post, see +[Submit a blog post](/content/en/docs/contributing/blog). -```sh -npx hugo new content/en/blog/2023/short-name-for-post.md -``` +### Add a project to the OpenTelemetry [Registry] -If your post will have images or other assets, instead run: - -```sh -npx hugo new content/en/blog/2023/short-name-for-post/index.md -``` - -Edit the markdown file at the path you provided in the previous command. The -file is initialized from the blog-post starter under [archetypes](archetypes). - -Put assets, if any, like images into the folder created. - -Once your post is ready, submit it through a [pull request][]. - -### Using the GitHub UI - -- Go to the [blog post template](archetypes/blog.md) and click on - `Copy raw content` at the top right of the menu. -- [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main). -- Paste the content from the template. -- Name your file, e.g. - `content/en/blog/2022/short-name-for-your-blog-post/index.md` -- Start editing the markdown file. -- Once your post is ready click on `Propose changes` at the bottom. +For details on how to add a project to the OpenTelemetry Registry, see [Adding +to the registry][]. ## Contributing -See [CONTRIBUTING.md][]. - 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 +issue][]. This should allow you to quickly find a place to contribute. See +[CONTRIBUTING.md][] for more information. -We (OTel Comms SIG) meet every two weeks on Monday at 9:00 PT. Check out the +We, the OTel Comms SIG, meet every two weeks on Monday at 9:00 PT. Check out the [OpenTelemetry community calendar][] for the Zoom link and any updates to this schedule. Meeting notes are available as a public [Google doc][]. If you have trouble -accessing the doc, please get in touch on [Slack][]. +accessing the doc, get in touch on [Slack][]. Here is a list of community roles with current and previous members: @@ -121,8 +85,6 @@ already contributed][contributors]! [hugo]: https://gohugo.io [netlify]: https://netlify.com [opentelemetry]: https://opentelemetry.io -[pull request]: - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request [registry]: https://opentelemetry.io/ecosystem/registry/ [opentelemetry community calendar]: https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com diff --git a/content/en/docs/contributing/_index.md b/content/en/docs/contributing/_index.md new file mode 100644 index 000000000000..f4d471831a14 --- /dev/null +++ b/content/en/docs/contributing/_index.md @@ -0,0 +1,623 @@ +--- +title: Contributing +description: Learn how to contribute to OpenTelemetry documentation. +aliases: [/docs/contribution-guidelines] +weight: 200 +cSpell:ignore: prepopulated spacewhite +--- + +You can open an issue about OpenTelemetry documentation, 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. +- Create new content. +- Update the OpenTelemetry Registry. +- Improve the code that builds the site. + +See also the general +[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. + +## 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 - Contributing new content_** + +The previous figure presents the basic steps for new docs contributions. + +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. + +### 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 1 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 1. 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 will offer to create a fork of + the repository. Select **Fork this repository**. + +1. Make your changes in the GitHub editor. + +1. Below the editor, 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 2 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 2. 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 you 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 3 shows the steps to open a PR from your fork to the +[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 3. Steps to open a PR from your fork to the +[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. GitHub's automation closes the + mentioned issue after merging the PR if used. 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** opens a staged version of + the OpenTelemetry website with your changes applied. This is how reviewers + check your changes. + +Other checks might also fail, including: + +- File name checks +- Links resolution +- Markdown formatting +- Spelling + +GitHub also automatically assigns labels to a PR to help reviewers. + +#### Fix content issues automatically + +Before submitting a change 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 +``` + +To separately test and fix issues with your files, run: + +```sh +npm run test # checks but does not update any files +npm run fix # 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 `https://localhost:1313` in your web browser to see the local +preview. Hugo watches the 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 will create 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 project's [dashboard][] -- Netlify login +required. + +#### PR guidelines + +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, 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 behave. + +## Open an issue + +If you want to suggest improvements to existing content or notice an error, 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. + +## Contribute to other repositories + +The OpenTelemetry project contains many repositories. Several of these +repositories contain documentation: user-facing help text, error messages, API +references or code comments. + +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. + +## 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/ diff --git a/content/en/docs/acknowledgements/_index.md b/content/en/docs/contributing/acknowledgements.md similarity index 98% rename from content/en/docs/acknowledgements/_index.md rename to content/en/docs/contributing/acknowledgements.md index 80c5c81be5e4..c2dd3d55a71f 100644 --- a/content/en/docs/acknowledgements/_index.md +++ b/content/en/docs/contributing/acknowledgements.md @@ -2,7 +2,6 @@ title: Acknowledgements description: Acknowledgements for sources for content on this site aliases: [/acknowledgements] -weight: 200 cSpell:ignore: Pigram --- diff --git a/content/en/docs/contributing/blog.md b/content/en/docs/contributing/blog.md new file mode 100644 index 000000000000..1a245ec94364 --- /dev/null +++ b/content/en/docs/contributing/blog.md @@ -0,0 +1,106 @@ +--- +title: Blog +description: Learn how to submit a blog post. +weight: 30 +--- + +The [OpenTelemetry blog](/blog/) communicates new features, community reports, +and any news that might be relevant to the OpenTelemetry community. This +includes end users and developers. Anyone can write a blog post and submit it +for review. + +## Before submitting a blog post + +Blog posts should not be commercial in nature and should consist of original +content that applies broadly to the OpenTelemetry community. + +Verify that your intended content broadly applies to the OpenTelemetry Community +. Appropriate content includes: + +- New OpenTelemetry capabilities +- OpenTelemetry projects updates +- Updates from Special Interest Groups +- Tutorials and walkthroughs +- OpenTelemetry Integrations + +Unsuitable content includes: + +- Vendor product pitches + +To submit a blog post, +[raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/new?title=New%20Blog%20Post:%20%3Ctitle%3E) +with the title and a short description of your blog post. If you are not a +[Member](https://github.com/open-telemetry/community/blob/main/community-membership.md#member), +you also need to provide a _sponsor_ for your blog post, who is a Member (by +that definition) and who is willing to provide a first review of your blog post. + +If you do not raise an issue before providing your PR, we may request you to do +so before providing a review. + +## Submit a blog post + +You can submit a blog post either by forking this repository and writing it +locally or by using the GitHub UI. In both cases we ask you to follow the +instructions provided by the +[blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md). + +**Note**: Before writing a blog post, ask yourself if your content also might be +a good addition to the documentation. If the answer is "yes", create a new issue +or pull request (PR) with your content to get it added to the docs. + +### Fork and write locally + +After you've set up the local fork you can create a blog post using a template. +Follow these steps to create a post from the template: + +1. Run the following command from the repository root: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post.md + ``` + + If your post has images or other assets, run the following command: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post/index.md + ``` + +1. Edit the Markdown file at the path you provided in the previous command. The + file is initialized from the blog-post starter under + [archetypes](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/). + +1. Put assets, like images or other files, into the folder you've created. + +1. When your post is ready, submit it through a pull request. + +### Use the GitHub UI + +If you prefer not to create a local fork, you can use the GitHub UI to create a +new post. Follow these steps to add a post using the UI: + +1. Go to the + [blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md) + and click on **Copy raw content** at the top right of the menu. + +1. Select + [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main). + +1. Paste the content from the template you copied in the first step. + +1. Name your file, for example + `content/en/blog/2022/short-name-for-your-blog-post/index.md`. + +1. Edit the Markdown file in GitHub. + +1. When your post is ready, select **Propose changes** and follow the + instructions. + +## Publication timelines + +The OpenTelemetry blog doesn't follow a strict publication timeline, this means: + +- Your blog post will be published when it has all the approvals required. +- Publication can be postponed if needed, but maintainers can't guarantee + publication at or before a certain date. +- Certain blog posts (major announcements) take precedence and may be published + before your blog post. diff --git a/content/en/docs/contributing/style-guide.md b/content/en/docs/contributing/style-guide.md new file mode 100644 index 000000000000..9109823f7d1c --- /dev/null +++ b/content/en/docs/contributing/style-guide.md @@ -0,0 +1,41 @@ +--- +title: Documentation style guide +linkTitle: Style guide +weight: 10 +cSpell:ignore: open-telemetry postgre style-guide textlintrc +--- + +We don't have an official style guide yet, but the current OpenTelemetry +documentation style is inspired by the following style guides: + +- [Google Developer Documentation Style Guide](https://developers.google.com/style) +- [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) + +The following sections contain guidance that is specific to the OpenTelemetry +project. + +## OpenTelemetry.io word list + +A list of OpenTelemetry-specific terms and words to be used consistently across +the site. + + +| Term | Usage | +| --- | --- | +| 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. | +| Repository | Code repository, lowercase when in the middle of a sentence. Don't use "repo" or "repos". | +| 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. | +| OTLP | OpenTelemetry Protocol. Don't write "OTlP" or "otlp" in descriptions or instructions. | + + +Make sure that proper nouns, such as other CNCF projects or third-party tools, +are properly written and use the original capitalization. For example, write +"PostgreSQL" instead of "postgre". For a full list, check the +[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) +file. + +See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry +terms and their definition. diff --git a/content/en/docs/contribution-guidelines.md b/content/en/docs/contribution-guidelines.md index e30a94dfe6a7..a09510f1cd42 100644 --- a/content/en/docs/contribution-guidelines.md +++ b/content/en/docs/contribution-guidelines.md @@ -5,10 +5,14 @@ toc_hide: true --- OpenTelemetry is an open source project, and we gladly accept new contributions -and contributors. Please see the CONTRIBUTING.md file in each SIG repository for +and contributors. See the CONTRIBUTING.md file in each SIG repository for information on getting started. -## Contributing to the OpenTelemetry Documentation +## Contribute to the OpenTelemetry Documentation + +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/docs/contributing), which includes a style guide and +useful information on the review process. 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 diff --git a/static/refcache.json b/static/refcache.json index 1e5029d59ad0..a2ad3f784d54 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -83,6 +83,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T13:39:44.708765-04:00" }, + "https://app.netlify.com/sites/opentelemetry/overview": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:13.292839+01:00" + }, "https://app.telemetryhub.com/docs": { "StatusCode": 200, "LastSeen": "2023-06-29T12:27:18.815688-04:00" @@ -483,6 +487,10 @@ "StatusCode": 200, "LastSeen": "2023-10-01T12:48:08.791661-04:00" }, + "https://commonmark.org/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T14:56:57.912039+01:00" + }, "https://community.cncf.io/end-user-community/": { "StatusCode": 200, "LastSeen": "2023-07-03T17:44:06.5954165Z" @@ -739,6 +747,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:51:20.598962-04:00" }, + "https://developers.google.com/style": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.694842+01:00" + }, "https://devstats.cncf.io/": { "StatusCode": 206, "LastSeen": "2023-06-29T16:21:23.471592-04:00" @@ -995,6 +1007,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:46:50.059623-04:00" }, + "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": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:14.272624+01:00" + }, "https://docs.google.com/document/d/15vR7D1x2tKd7u3zaTF0yH1WaHkUr2T4hhr7OyiZgmBg/edit#heading=h.4xuru5ljcups": { "StatusCode": 200, "LastSeen": "2023-06-29T15:52:33.514228-04:00" @@ -1107,6 +1123,10 @@ "StatusCode": 206, "LastSeen": "2023-09-15T16:58:35.759747+02:00" }, + "https://docs.linuxfoundation.org/lfx/easycla/contributors": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:05.806034+01:00" + }, "https://docs.locust.io/en/stable/writing-a-locustfile.html": { "StatusCode": 200, "LastSeen": "2023-06-29T15:47:17.793642-04:00" @@ -1959,6 +1979,18 @@ "StatusCode": 200, "LastSeen": "2023-06-29T16:04:43.002783-04:00" }, + "https://git-scm.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.723883+01:00" + }, + "https://git-scm.com/book/en/v2/Getting-Started-Installing-Git": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:05.965228+01:00" + }, + "https://git-scm.com/docs/git-merge#_how_conflicts_are_presented": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.954292+01:00" + }, "https://github.blog/2021-05-26-why-and-how-github-is-adopting-opentelemetry/": { "StatusCode": 200, "LastSeen": "2023-06-30T16:26:22.927158-04:00" @@ -1967,6 +1999,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:49:02.328002-04:00" }, + "https://github.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-13T14:56:57.330463+01:00" + }, "https://github.com/Aneurysm9": { "StatusCode": 200, "LastSeen": "2023-06-30T09:32:40.687601-04:00" @@ -3687,6 +3723,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:48:34.579016-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.562763+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io#adding-a-project-to-the-opentelemetry-registry": { "StatusCode": 200, "LastSeen": "2023-06-30T08:46:35.260059-04:00" @@ -3699,6 +3739,14 @@ "StatusCode": 200, "LastSeen": "2023-09-08T10:57:01.381266-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:06.564186+01:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/fork": { + "StatusCode": 200, + "LastSeen": "2023-12-13T15:27:13.947245+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/new": { "StatusCode": 200, "LastSeen": "2023-06-30T08:31:06.342368-04:00" @@ -3715,6 +3763,10 @@ "StatusCode": 200, "LastSeen": "2023-09-12T11:57:04.702626-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/pulls": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.270135+01:00" + }, "https://github.com/open-telemetry/otel-arrow": { "StatusCode": 200, "LastSeen": "2023-11-14T11:45:08.675719+01:00" @@ -4527,6 +4579,10 @@ "StatusCode": 206, "LastSeen": "2023-07-28T12:17:39.145108-04:00" }, + "https://kubernetes.io/docs/contribute/style/style-guide/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:04:54.259484+01:00" + }, "https://kubernetes.io/docs/reference/kubectl/": { "StatusCode": 206, "LastSeen": "2023-06-30T11:49:31.853471-04:00" @@ -6127,6 +6183,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T18:48:57.135457-04:00" }, + "https://www.cncf.io/about/contact/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:06.564168+01:00" + }, "https://www.cncf.io/blog/2019/05/21/a-brief-history-of-opentelemetry-so-far/": { "StatusCode": 206, "LastSeen": "2023-06-30T09:22:37.957195-04:00" @@ -6507,6 +6567,14 @@ "StatusCode": 206, "LastSeen": "2023-10-16T20:09:59.62173+02:00" }, + "https://www.netlify.com/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:07.468279+01:00" + }, + "https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:12.735575+01:00" + }, "https://www.nomadproject.io": { "StatusCode": 206, "LastSeen": "2023-06-30T08:50:51.721695-04:00"