Submitting content

To contribute new or improve existing documentation content, submit a pull request (PR):

• If your change is small, or you’re unfamiliar with Git, see Changes using GitHub to learn how to edit a page.
• If your changes are large, see Work from a local fork to learn how to make changes locally on your computer.

The following figure illustrates how to contribute new documentation.

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 1. Contributing new content.

Changes using GitHub

If you’re less experienced with Git workflows, here’s an easier method of creating and submitting a pull request. Figure 2 outlines the steps and the details follow.

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 2. Steps for opening a PR using GitHub.

1. On the page where you see the issue, select the Edit this page option in the right-hand side navigation panel.

2. If you’re not a member of the project, GitHub offers to create a fork of the repository. Select Fork this repository.

3. Make your changes in the GitHub editor.

4. Fill in the Propose file change form.

5. Select Propose file change.

6. Select Create pull request.

7. The Open a pull request screen appears. Your description helps reviewers understand your change.

8. 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.
2. Select the pencil (edit) icon on any files changed by the pull request.
3. Make the changes requested. If there’s a code suggestion, apply it.
4. Commit the changes.

When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later.

Work from a local fork

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 installed on your computer. You can also use a user interface for Git.

Figure 3 shows the steps to follow when you work from a local fork. The details for each step follow.

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 3. Working from a local fork to make your changes.

Fork the opentelemetry.io repository

1. Navigate to the opentelemetry.io repository.
2. Select Fork.

Create a local clone and set the upstream

1. In a terminal window, clone your fork and install the requirements:

   git clone git@github.com:<your_github_username>/opentelemetry.io.git
   cd opentelemetry.io
   npm install
   

2. Set the open-telemetry/opentelemetry.io repository as the upstream remote:

   git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
   

3. Confirm your origin and upstream repositories:

   git remote -v
   

   Output is similar to:

   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)
   

4. Fetch commits from your fork’s origin/main and open-telemetry/opentelemetry.io’s upstream/main:

   git fetch origin
   git fetch upstream
   

   This makes sure your local repository is up to date before you start making changes. Push changes from upstream to origin regularly to keep your fork in sync with upstream.

Create a branch

1. Create a new branch. This example assumes the base branch is upstream/main:

   git checkout -b <my_new_branch> upstream/main
   

2. 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:

   git status
   

   Output is similar to:

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

2. Add the files listed under Changes not staged for commit to the commit:

   git add <your_file_name>
   

   Repeat this for each file.

3. After adding all the files, create a commit:

   git commit -m "Your commit message"
   

4. Push your local branch and its new commit to your remote fork:

   git push origin <my_new_branch>
   

5. Once the changes are pushed, GitHub lets you know that you can create a PR.

Open a pull request from your fork

Figure 4 shows the steps to open a PR from your fork to opentelemetry.io.

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 4. Steps to open a PR from your fork to opentelemetry.io.

1. In a web browser, go to the opentelemetry.io repository.

2. Select New Pull Request.

3. Select compare across forks.

4. From the head repository drop-down menu, select your fork.

5. From the compare drop-down menu, select your branch.

6. Select Create Pull Request.

7. Add a description for your pull request:

   • Title (50 characters or less): Summarize the intent of the change.

   • Description: Describe the change in more detail.

     • If there is a related GitHub issue, include Fixes #12345 or Closes #12345 in the description so that GitHub’s automation closes the mentioned issue after merging the PR. If there are other related PRs, link those as well.
     • If you want advice on something specific, include any questions you’d like reviewers to think about in your description.

8. Select the Create pull request button.

Your pull request is available in Pull requests.

After opening a PR, GitHub runs automated tests and tries to deploy a preview using Netlify.

• If the Netlify build fails, select Details for more information.
• If the Netlify build succeeds, select Details to open a staged version of the OpenTelemetry website with your changes applied. This is how reviewers check your changes.

Other checks might also fail. See the list of all PR checks.

Fix content issues automatically

Before submitting a change to the repository, run the following command and (i) address any reported issues, (ii) commit any files changed by the script:

npm run test-and-fix

To separately test and fix all issues with your files, run:

npm run test    # Checks but does not update any files
npm run fix:all # May update files

To list available NPM scripts, run npm run. See PR checks for more information on pull request checks and how to fix errors automatically.

Preview your changes 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:

npm run serve

Navigate to http://localhost:1313 in your web browser to see the local preview. Hugo watches for changes and rebuilds the site as needed.

To stop the local Hugo instance, go back to the terminal and type Ctrl+C, or close the terminal window.

Site deploys and PR previews

If you submit a PR, Netlify creates a deploy preview so that you can review your changes. Once your PR is merged, Netlify deploys the updated site to the production server.

Note: PR previews include draft pages, but production builds do not.

To see deploy logs and more, visit the project’s dashboard – Netlify login required.

PR guidelines

Before a PR gets merged, it sometimes requires a few iterations of review-and-edit. To help us and yourself make this process as easy as possible, we ask that you adhere to the following:

• If your PR isn’t a quick fix, then work from a fork: Click the Fork 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.

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:

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. After rebasing, force-push new changes to your fork:

   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:

   git fetch origin
   git rebase origin/<your-branch-name>
   

   Then force-push the changes to your fork:

   git push --force-with-lease origin <your-branch-name>
   

2. Fetch changes from open-telemetry/opentelemetry.io’s upstream/main and rebase your branch:

   git fetch upstream
   git rebase upstream/main
   

3. Inspect the results of the rebase:

   git status
   

   This results in a number of files marked as conflicted.

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

5. Add the files to the changeset:

   git add <filename>
   

6. Continue the rebase:

   git rebase --continue
   

7. Repeat steps 2 to 5 as needed.

   After applying all commits, the git status command shows that the rebase is complete.

8. Force-push the branch to your fork:

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