open-telemetry
/
opentelemetry.io
mirror of https://github.com/open-telemetry/opentelemetry.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add style guide and basic contribution section (#3651)

This commit is contained in:
Fabrizio Ferri-Benedetti 2024-01-11 16:54:06 +01:00 committed by GitHub
parent f8a7ec7367
commit 243aa95a48
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 900 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
CONTRIBUTING.md
View File

@ -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.
**Thanks for your interest in contributing to
[OpenTelemetry.io](https://opentelemetry.io/)!**
Note that all of your interactions in the project are subject to our
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.
Also review the general
### Contributor License Agreement
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
## Contributor's guide
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
- 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

72
README.md
View File

@ -1,78 +1,42 @@
# <img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OTel logo" width="45"> 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][]!
missing [let us know][].
Read on to learn about other ways on how you can help.
### Submit a blog post
## Adding a project to the OpenTelemetry [Registry]
For guidance on how to write and submit a blog post, see
[Submit a blog post](/content/en/docs/contributing/blog).
For details, see [Adding to the registry][].
### Add a project to the OpenTelemetry [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.
### Fork & Write locally
Follow the [setup instructions][contributing.md] then, to create a skeletal blog
post, run the following command from the repository root:
```sh
npx hugo new content/en/blog/2023/short-name-for-post.md
```
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

623
content/en/docs/contributing/_index.md Normal file
View File

@ -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<br>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<br>Contributor]) --- id1[(open-telemetry/opentelemetry.io<br>GitHub)]
subgraph tasks[Changes using GitHub]
direction TB
0[ ] -.-
1[1. Edit this page] --> 2[2. Use GitHub markdown<br>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<br>repository] --> 2[Create local clone<br>and set upstream]
subgraph changes[Your changes]
direction TB
S[ ] -.-
3[Create a branch<br>example: my_new_branch] --> 3a[Make changes using<br>a text editor] --> 4["Preview your changes<br>locally using Hugo<br>(localhost:1313)"]
end
subgraph changes2[Commit / Push]
direction TB
T[ ] -.-
5[Commit your changes] --> 6[Push commit to<br>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:<your_github_username>/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:<your_github_username>/opentelemetry.io.git (fetch)
origin git@github.com:<your_github_username>/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 <my_new_branch> 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 <my_new_branch>
Your branch is up to date with 'origin/<my_new_branch>'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." 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 <your_file_name>
```
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 <my_new_branch>
```
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<br>head repository drop-down menu]
end
subgraph second [ ]
direction TB
5[5. Select your branch from<br>the compare drop-down menu] --> 6[6. Select Create Pull Request]
6 --> 7[7. Add a description<br>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/<your-branch-name>
```
1. After rebasing, force-push new changes to your fork:
```shell
git push --force-with-lease origin <your-branch-name>
```
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/<your-branch-name>
```
Then force-push the changes to your fork:
```shell
git push --force-with-lease origin <your-branch-name>
```
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 <filename>
```
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 <your-branch-name>
```
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/

1
content/en/docs/acknowledgements/_index.md → content/en/docs/contributing/acknowledgements.md
View File

@ -2,7 +2,6 @@
title: Acknowledgements
description: Acknowledgements for sources for content on this site
aliases: [/acknowledgements]
weight: 200
cSpell:ignore: Pigram
---

106
content/en/docs/contributing/blog.md Normal file
View File

@ -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.

41
content/en/docs/contributing/style-guide.md Normal file
View File

@ -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.
<!-- prettier-ignore-start -->
| 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. |
<!-- prettier-ignore-end -->
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.

8
content/en/docs/contribution-guidelines.md
View File

@ -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

68
static/refcache.json
View File

@ -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"