Contributing to the Service Mesh Hub Documentation

Hi! So you'd like to help us out with the Service Mesh Hub documentation. That is awesome! Before you get started, we have a couple things to mention about contributing standards and process. We'd like to make this easy as possible, so if you have a tiny edit to make, check out the Quickstart section of the guide. Otherwise, here are the ways you can get involved:


Background

The Service Mesh Hub docs live in the docs/content directory of the Service Mesh Hub GitHub repository. The docs are written in Markdown and rendered to a static site using Hugo. The docs make use of shortcodes from Hugo and some custom shortcodes that are part of a solo-io theme stored in this repository. Shortcodes are a way to render custom HTML on a page without injecting that HTML directly into Markdown.

The docs website can be rendered locally for updates and testing by using Hugo and make. There are some software prerequisites that need to be fulfilled in order to render and view the site successfully. More information can be found in the Install prerequisite software section of the Editing Locally guide.

For minor changes and edits, it is not necessary to clone the repository and render it locally. You can simply make the changes directly on GitHub and submit a pull request (PR).


Log an issue

The simplest way to get involved with docs is by submitting an issue when you see something that needs to be changed. It could be a grammatical error, an unclear statement, or a suggestion for a new document or example. If you see something that should be amended or improved, head on over to the Service Mesh Hub GitHub repository and follow the steps in the Quickstart for logging an issue.


Quickstart

While it is possible to clone the entire Service Mesh Hub repository, make changes to the documentation, render it locally to validate, and then submit a PR; that's a lot of work. For minor edits and small improvements, it is much simpler to edit the docs directly on GitHub and submit a pull request. Here is the quickstart process:

  1. Log an issue on the main Service Mesh Hub repository
  2. Fork the Service Mesh Hub repository to your own account
  3. Make the update and commit it
  4. Create a pull request to merge the change

Once the PR has been submitted, someone from solo.io will review the change and either approve it or ask for more information. See below for an example of creating and submitting a change.

Log an issue on the main Service Mesh Hub repository

In this step you will log an issue on the Service Mesh Hub GitHub repository so that others know you are working on a fix. You can also simply log an issue with the documentation to let others know about the problem.

Fork the Service Mesh Hub repository to your own account

In this step you will fork the Service Mesh Hub repository into your own account. This step assumes that you already have a GitHub account. More information on forking a repository can be found on GitHub's website.

After a few moments the fork will complete and you will be taken to the page with your fork of the Service Mesh Hub repository. Now you can make edits and submit a PR.

Make the update and commit it

In this step you will make the actual change to the document that has an issue. From the forked repository, select the branch you want to make changes to. The current branch being used to generate the Service Mesh Hub docs is master. The files that make up the docs website are in docs/content, and the directory structure follows the menu structure of the docs site.

The change has been committed to a new branch on your forked repository.

Create a pull request to merge the change

Now that the change has been committed to your fork of the Service Mesh Hub repository, it's time to submit a pull request to merge the change into the official Service Mesh Hub repository.

Once the PR is submitted, someone from solo.io will review the change and either approve it or ask for more information.


Making big updates

While making minor edits and fixes works well on GitHub directly, more involved changes require using a proper editor and rendering the site locally. If you'd like to contribute at that level, we recommend reading through our style guide and setting up your local system properly.

Next Steps