Skip to content

Latest commit

 

History

History
382 lines (258 loc) · 14.3 KB

how-to-contribute.md

File metadata and controls

382 lines (258 loc) · 14.3 KB
Raw

How to contribute to the Teleport documentation

We encourage everyone with an interest in improving Teleport documentation to contribute content, submit issues, and suggest changes. This guide describes the process for making changes to the documentation whether you are an internal or external contributor.

Prerequisites

Before you begin, verify that your environment meets the following prerequisites:

  • You have a code editor, a GitHub account, and experience using command-line programs, including git commands and command line options.
  • You have Node.js, version 18.x or newer, installed. Run node --version to check whether Node is installed. If you need to install or update Node, see Installing Node.js for instructions to download and install Node.js using a package manager.
  • You have the yarn package manager installed. Run yarn --version to check whether yarn is installed. If you need to install yarn, run the command brew install yarn or npm install --global yarn to add it to your local system.

Step 1/5. Set up your local environment

To set up a local environment for contributing to Teleport documentation:

  1. Open a terminal shell on your computer.

  2. Clone the gravitational/docs repository by running the following command:

    $ git clone https://github.com/gravitational/docs --recurse-submodules

    This command clones the documentation submodules that correspond to the different major release versions of the Teleport code. For example, there are currently documentation submodules for the 11.x, 12.x, 13.x, and 14.x versions of Teleport.

  3. Change to the root of the docs directory:

    $ cd docs

  4. Update the documentation to the latest version from the master branch:

    $ yarn git-update

  5. Install dependencies:

    $ yarn

Step 2/5. Navigate to a specific version

Different versions of the documentation are organized into the content directory of the gravitational/docs repository. Each subdirectory of the content directory includes a git submodule for a different branch of gravitational/teleport.

To navigate to a specific version of the documentation:

  1. View the versions of the documentation listed in the content directory by running the following command:

    $ ls -l content

  2. Change to the directory under content that contains the version of documentation you want to update. For example, navigate to the directory that corresponds to latest version of Teleport:

    # Set this to a major version number
$ TELEPORT_VERSION=""
$ cd content/${TELEPORT_VERSION?}.x

  3. Switch to the master branch by running the following command:

    $ git switch master

    You can use a versioned branch if you want to update documentation for a specific previous version of Teleport. However, it most cases, you should use the master branch.

  4. Create a new branch of gravitational/teleport for your changes by running a command similar to the following:

    $ git switch -c my-branch

    You now have a branch for a specific version of the documentation content. Before making any changes, note how the content is organized so you know where to find the files to update.

    Within the content/*.* directory in your branch, there's a docs subdirectory. The content/*.*/docs subdirectory contains the files and folders used to produce a specific version of the documentation.

    The subdirectory includes the following:

    • The img/ folder for images used inside the pages.
    • The pages/ folder for the Markdown files that contain documentation content. Every file in this folder is rendered as a page.
    • The pages/includes folder for content that's only rendered when it's included in the body of a page.
    • The config.json file for configuring version information.

    You're now ready to make changes in your own branch using the code editor of your choice.

Step 3/5. Test changes locally

As you make changes to the content in your local branch, it's helpful to see how the changes will be rendered when the documentation is published.

You can use yarn to run a development server that detects changes to the documentation and displays them whenever you manually refresh the page in the browser. You can also use yarn commands to check for errors and fix common issues.

To test changes in your local environment:

  1. Change to the top-level docs directory in your local copy of the https://github.com/gravitational/docs repository.

  2. Start the development server by running the following commands:

    $ yarn dev

  3. Open a web browser and navigate to the documentation using the URL localhost:3000/docs.

  4. Validate the Markdown syntax by running the following commends:

    # Check your Markdown syntax
$ yarn markdown-lint
# markdown-lint, but also checks that external links work
$ yarn markdown-lint-external-links

    For more information about using yarn commands to work with Teleport documentation, see the README.

Step 4/5. Create a pull request

If you're an internal contributor with permission to access the Teleport repository, you can commit changes and push branches directly to the repository. If you're an external contributor, you can commit changes to your private branch and push private branches to a fork of the Teleport repository.

Internal contributors

If you work at Teleport:

  1. Add files and commit changes to your local branch periodically with commands similar to the following:

    $ git add <new-file-name>                      # Add a specific new file to be committed
$ git add -A                                   # Add all changed files to the list of files to be committed
$ git commit -am "Fix or feature description"  # Add and commit changes with a comment
$ git commit -m "Fix or feature description"   # Commit changes already added

  2. Push your branch to gravitational/teleport with a command similar to the following:

    $ git push origin my-branch

  3. Open the Teleport repository, select your branch as the branch to merge into main, then click New pull request.

    The continuous integration (CI) pipeline automatically assigns reviewers to your pull request.

  4. Wait for the minimum required approvals, then merge your pull request as soon as possible.

External contributors

If you are an external contributor, you must commit your changes to your branch and push your branch to a fork of the gravitational/teleport repository.

To push changes as an external contributor:

  1. Verify that you have an SSH key pair and have stored your public key in GitHub.

  2. Open the Teleport repository, click Fork, then select Create a new fork.

  3. Verify the owner and repository name.

  4. Click Create fork.

    Alternatively, you can create a fork from the command-line by running a command similar to the following:

    $ git remote add fork ssh://[email protected]/my-user/teleport

    In this command, my-user represents your GitHub user name and teleport is the name of your Teleport repository fork.

  5. Pull all of the changes from the remote repository into your local fork by running the following command:

    $ git fetch origin

  6. Push changes from your local branch to the remote fork of the Teleport repository by running a command similar to the following:

    $ git push --set-upstream fork my-branch

  7. Open the Teleport repository, select your branch as the branch to merge into main, then click New pull request.

    The continuous integration (CI) pipeline automatically assigns reviewers to your pull request. To ensure that your pull request is merged, you should respond to reviewer feedback in a timely manner. After you incorporate reviewer feedback, your pull request might require a companion—or buddy—pull request to ensure that your changes conform to certain conventions and pass automated checks. The companion pull request includes all of your commits to verify they pass CI/CD validation and continues to identify you as the author of the changes committed.

    If you don't respond to reviewer feedback, your pull request is likely to be deemed inactive and closed.

  8. Wait for the minimum required approvals, then merge your pull request as soon as possible.

Step 5/5. Backport changes to earlier versions

Because the docs site is versioned, we want to ensure that any changes you make to the most recent version of the documentation are reflected in all of the appropriate versions of Teleport we currently support.

You can find our list of currently-supported versions in the FAQ.

There are many ways to create a backport. The following methods represent the most common ways to backport changes for Teleport documentation:

  • By using GitHub labels (internal contributors)
  • By using the make program (internal contributors)
  • By selecting commit hashes manually (internal or external contributors)

Using GitHub labels

You must be an internal contributor to use the GitHub label process to backport changes. This method fails for forks of the gravitational/teleport repository.

When you open a pull request, add labels of the format backport/branch/v[0-9]+ to backport your pull request to different versioned branches of the gravitational/teleport repository.

For example, to backport a change to v13 of the documentation, add the label backport/branch/v13 to the pull request.

After you merge your pull request, the continuous integration pipeline creates a table of links in the comments for the pull request. You can then create an additional pull request for your each backport version you specified as a label.

Using make

You must be an internal contributor and have Go installed in your environment to use the make backport script to backport changes. This method fails for forks of the gravitational/teleport repository.

To use make:

  1. Navigate to the root of your gravitational/teleport clone.

  2. Run the following command to assign the PR variable to the ID of your original GitHub pull request and the TO variable to a comma-separated list of versioned branch names:

    $ PR=0000 TO=branch/v10 make backport

    This make backport script automatically generates backport branches and opens pull requests for them.

Select commits (internal)

If the automatic backport methods fail and you're an internal contributor, you must backport changes manually by selecting specific commits.

The following example illustrates how to backport a change into Teleport, version 11.x.x. In this example:

  • Changes were made in the my-branch working branch, then committed and pushed to the remote branch.
  • A pull request was created to merge the change from my-branch into master.
  • A merge conflict prevented automatic backporting of the change.

To commit a change manually:

  1. Open the closed pull request for the my-branch change that was successfully merged.

  2. Click Commits, then copy the hash of the commit made to my-branch.

  3. Run the following commands to create a branch for the commit being backported:

    $ git switch branch/v11
$ git pull
$ git switch -c my-branch-backport-v11
$ git cherry-pick <commit-hash>

  4. Open the files that indicate there are merge conflicts and resolve all of the conflicts.

  5. Add the updated and saved files to the staged list of changes. For example:

    $ git add docs/pages/core-concepts.mdx

    You can use git status to check whether there are additional merge conflicts.

  6. Finish the cherry-pick operation by running the following command:

    git cherry-pick --continue

  7. Push the changes for the backport to the fork.

    $ git push origin my-branch-backport-v11

    If you see a warning that prevents you from pushing the backport, retry using the following command:

    $ git push --set-upstream origin my-branch-backport-v11

  8. Create a pull request in the Teleport repository to merge your backport in the branch you are backporting the fix into.

    For example, select branch/v11 as the base branch to backport your change into Teleport version 11.x. Include a reference to the original pull release identifier in the title for the backport. For example, create the pull request for a backport with a title similar to the following with the backport version number 11.x and the original pull request identifier 29210:

    [v11] Fix lint warning, make these unordered lists #29210

Select commits (external)

If you're an external contributor, you must backport changes manually.

The following example illustrates how to backport a change into Teleport version 11.x.x. In this example:

  • Changes were made in the my-branch branch and committed to a fork of the Teleport repository.
  • A pull request was created to merge the change from my-branch into origin/master from the fork.

  1. Copy the hash of the commit made to my-branch.

  2. Run the following commands to create a branch for the commit being backported:

    $ git switch branch/v11
$ git pull
$ git switch -c my-branch-backport-v11
$ git cherry-pick <commit-hash>

  3. Push the changes for the backport to the fork.

    $ git push --set-upstream fork my-branch-backport-v11

  4. Create a pull request in the Teleport repository for your backport.

Next steps

  • Consult the style guide to ensure your docs page is consistent with the rest of the documentation.
  • Use the documentation UI components reference guide to find the right UI components for your needs.