-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] create a new contributors' guide (#11669)
- Loading branch information
Alex Ball
authored
May 21, 2022
1 parent
b888fb7
commit 296a633
Showing
15 changed files
with
989 additions
and
663 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| --- | ||
| title: Contribute to the documentation | ||
| headerTitle: Contribute to the documentation | ||
| linkTitle: Documentation | ||
| description: Contribute to the documentation | ||
| image: /images/section_icons/index/quick_start.png | ||
| headcontent: How to contribute to the YugabyteDB documentation | ||
| type: page | ||
| section: CONTRIBUTOR GUIDES | ||
| menu: | ||
| preview: | ||
| identifier: docs | ||
| parent: contribute | ||
| weight: 2910 | ||
| --- | ||
|
|
||
| <div class="row"> | ||
| <div class="col-12 col-md-6 col-lg-12 col-xl-6"> | ||
| <a class="section-link icon-offset" href="docs-checklist/"> | ||
| <div class="head"> | ||
| <img class="icon" src="/images/section_icons/deploy/checklist.png" aria-hidden="true" /> | ||
| <div class="title">Checklist</div> | ||
| </div> | ||
| <div class="body"> | ||
| Explore the contribution process, from start to finish | ||
| </div> | ||
| </a> | ||
| </div> | ||
|
|
||
| <div class="col-12 col-md-6 col-lg-12 col-xl-6"> | ||
| <a class="section-link icon-offset" href="docs-layout/"> | ||
| <div class="head"> | ||
| <img class="icon" src="/images/section_icons/explore/json_documents.png" aria-hidden="true" /> | ||
| <div class="title">Docs layout</div> | ||
| </div> | ||
| <div class="body"> | ||
| Find the right page or section | ||
| </div> | ||
| </a> | ||
| </div> | ||
| <div class="col-12 col-md-6 col-lg-12 col-xl-6"> | ||
| <a class="section-link icon-offset" href="docs-build/"> | ||
| <div class="head"> | ||
| <img class="icon" src="/images/section_icons/index/troubleshoot.png" aria-hidden="true" /> | ||
| <div class="title">Build the docs</div> | ||
| </div> | ||
| <div class="body"> | ||
| Run the docs site on your local machine | ||
| </div> | ||
| </a> | ||
| </div> | ||
|
|
||
| <div class="col-12 col-md-6 col-lg-12 col-xl-6"> | ||
| <a class="section-link icon-offset" href="docs-edit/"> | ||
| <div class="head"> | ||
| <img class="icon" src="/images/section_icons/index/troubleshoot.png" aria-hidden="true" /> | ||
| <div class="title">Edit the docs</div> | ||
| </div> | ||
| <div class="body"> | ||
| Fork the repository and edit the docs | ||
| </div> | ||
| </a> | ||
| </div> | ||
|
|
||
| <div class="col-12 col-md-6 col-lg-12 col-xl-6"> | ||
| <a class="section-link icon-offset" href="docs-style/"> | ||
| <div class="head"> | ||
| <img class="icon" src="/images/section_icons/architecture/concepts.png" aria-hidden="true" /> | ||
| <div class="title">Style guide</div> | ||
| </div> | ||
| <div class="body"> | ||
| Read the YugabyteDB documentation style guide | ||
| </div> | ||
| </a> | ||
| </div> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| --- | ||
| title: Build the YugabyteDB docs locally | ||
| headerTitle: Build the docs | ||
| linkTitle: Build the docs | ||
| description: Build the YugabyteDB docs locally | ||
| image: /images/section_icons/index/quick_start.png | ||
| type: page | ||
| menu: | ||
| preview: | ||
| identifier: docs-build | ||
| parent: docs | ||
| weight: 2913 | ||
| isTocNested: true | ||
| showAsideToc: true | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| To run the docs site locally and edit the docs, you'll need: | ||
|
|
||
| * **A text editor**, such as [Visual Studio Code](https://code.visualstudio.com) | ||
|
|
||
| * **Command-line tools for Xcode** on macOS. | ||
|
|
||
| ```sh | ||
| $ xcode-select --install | ||
| ``` | ||
|
|
||
| \ | ||
| Xcode is many gigabytes. Install the command-line tools unless you actually need the full Xcode. | ||
|
|
||
| * [**Homebrew**](https://brew.sh) on macOS or Linux. | ||
|
|
||
| * **Node.js** v16.x, installable in several ways: | ||
|
|
||
| * From the [node.js website](https://nodejs.org/en/download/) | ||
| * Using Homebrew: `brew install node@16` | ||
| * Using NVM: `nvm use 16` | ||
|
|
||
| * **Hugo**: `brew install hugo` gets you the latest version. | ||
|
|
||
| * **A GitHub account** | ||
|
|
||
| * **Git client**: The system Git binary is out of date, but works. If you like, you can use Homebrew to get a newer version (`brew install git`). | ||
|
|
||
| ## Fork the repository | ||
|
|
||
| 1. To make the commands in this section work correctly when you paste them, set an environment variable to store your GitHub username. | ||
|
|
||
| ```sh | ||
| export GITHUB_ID=your-github-id | ||
| ``` | ||
|
|
||
| 1. Fork the `yugabyte-db` GitHub repository and create a local clone of your fork with a command like this: | ||
|
|
||
| ```sh | ||
| git clone https://github.com/$GITHUB_ID/yugabyte-db.git | ||
| ``` | ||
|
|
||
| 1. Identify your fork as _origin_ and the original YB repository as _upstream_: | ||
|
|
||
| ```sh | ||
| cd yugabyte-db/ | ||
| git remote set-url origin https://github.com/$GITHUB_ID/yugabyte-db.git | ||
| git remote add upstream https://github.com/yugabyte/yugabyte-db.git | ||
| ``` | ||
|
|
||
| 1. Make sure that your local repository is still current with the upstream Yugabyte repository: | ||
|
|
||
| ```sh | ||
| git checkout master | ||
| git pull upstream master | ||
| git push origin | ||
| ``` | ||
|
|
||
| ## Build the docs site {#live-reload} | ||
|
|
||
| The YugabyteDB documentation is written in Markdown, and processed by Hugo (a static site generator) into an HTML site. | ||
|
|
||
| To get the docs site running in a live-reload server on your local machine, run the following commands: | ||
|
|
||
| ```sh | ||
| cd yugabyte-db/docs # Make sure this is YOUR fork. | ||
| npm ci # Only necessary the first time you clone the repo. | ||
| npm start # Builds the docs and launches the live-reload server. | ||
| ``` | ||
|
|
||
| The live-reload server runs at <http://localhost:1313/> unless port 1313 is already in use. Check the output from the `npm start` command to verify the port in use. | ||
|
|
||
| When you're done, type Ctrl-C stop the server. | ||
| {{< note title="Not looking quite right?" >}} | ||
| There's a transient bug in the live-reload build. If your local docs site doesn't look right, type Ctrl-C and re-run the `npm start` command. | ||
| {{< /note >}} | ||
| ### Optional: Run a full build {#full-build} | ||
| The live-reload server is the quickest way to get the docs running locally. If you want to run the build exactly the same way the CI pipeline does for a deployment, do the following: | ||
| ```sh | ||
| cd yugabyte-db/docs | ||
| npm run build | ||
| ``` | ||
| When the build is done, the `yugabyte-db/docs/public` folder contains a full HTML site, exactly the same as what's deployed on the live website at <https://docs.yugabyte.com/>. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| * Make sure the GUI installer for the command-line tools finishes with a dialog box telling you the install succeeded. If not, run it again. | ||
|
|
||
| * If you get an error about missing command-line tools, make sure xcode-select is pointing to the right directory, and that the directory contains a `usr/bin` subdirectory. Run `xcode-select -p` to find the path to the tools. Re-run xcode-select --install. | ||
|
|
||
| * If the live-reload site looks odd, stop the server with Ctrl-C and re-run `npm start`. | ||
|
|
||
| ## Next steps | ||
|
|
||
| Need to edit an existing page? [Start editing](../docs-edit/) it now. (Optional: [set up your editor](../docs-editor-setup/).) | ||
|
|
||
| Adding a new page? Use the [overview of sections](../docs-layout/) to find the appropriate location. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| title: Docs contribution checklist | ||
| headerTitle: Docs checklist | ||
| linkTitle: Docs checklist | ||
| description: Review the steps to start contributing documentation | ||
| image: /images/section_icons/index/quick_start.png | ||
| type: page | ||
| menu: | ||
| preview: | ||
| identifier: docs-checklist | ||
| parent: docs | ||
| weight: 2911 | ||
| isTocNested: true | ||
| showAsideToc: true | ||
| --- | ||
|
|
||
| ## Quick notes | ||
|
|
||
| * [File issues in GitHub](#file-tickets). | ||
| * Internal users: please file Platform and Cloud issues in Jira. | ||
| * Docs are written in Markdown and built using the Hugo static site generator. | ||
| * For live previews as you work, install the command-line tools (macOS), Node.js, and Hugo. (See [How to build the docs](../docs-build/).) | ||
| * Pull requests | ||
| * Open PRs against a fork of the yugabyte-db/docs repository, project Documentation. | ||
| * Assign a member of the docs team as a reviewer. | ||
|
|
||
| ## File docs issues and make suggestions {#file-tickets} | ||
|
|
||
| Regardless of the type of problem (such as errors, bad links, out-of-date content, or new features), if you don't intend to [edit the docs](#edit-the-docs) and make a pull request right away to fix the problem, please create an issue in GitHub or Jira (Yugabyte internal users only) to track the problem. | ||
|
|
||
| Every YugabyteDB docs page has a Contribute button that lets you file an issue or make a suggestion, both of which help you to create a GitHub issue. You can also create an issue [directly from GitHub](https://github.com/yugabyte/yugabyte-db/issues/new/choose). | ||
|
|
||
| The GitHub issue template starts your issue title with `[docs]` for faster scanning, and adds the `area/documentation` label. You can also add the section of the docs (for example, `[docs] [troubleshooting]`) for added context. | ||
|
|
||
| **Internal users**, add a member of the docs team as a reviewer, in addition to any other technical reviewers, and add your ticket directly to the Documentation project. | ||
|
|
||
| ## Run the docs site locally | ||
|
|
||
| Follow the instructions in [Build the docs](../docs-build/) to fork the repository and get the docs site running on your local machine. | ||
|
|
||
| ## Find the right page or section | ||
|
|
||
| Use the [overview of sections](../docs-layout/) to help you find the page you want to edit, or the correct section for a new page you want to add. | ||
|
|
||
| ## Edit the docs {#edit-the-docs} | ||
|
|
||
| Follow the instructions in [Edit the docs](../docs-edit/) to make your changes (read the [docs style guide](../docs-style/), too!) and submit a pull request. | ||
|
|
||
| ## Submit a pull request {#make-a-pr} | ||
|
|
||
| Congratulations on the change! You should now [submit a pull request](../docs-edit/#make-a-pr) for review and leave a message on the Slack channel. After it's reviewed and approved, your docs change will get merged in. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| --- | ||
| title: Edit the YugabyteDB docs | ||
| headerTitle: Edit the docs | ||
| linkTitle: Edit the docs | ||
| description: Get set up and edit the YugabyteDB docs locally | ||
| image: /images/section_icons/index/quick_start.png | ||
| type: page | ||
| menu: | ||
| preview: | ||
| identifier: docs-edit | ||
| parent: docs | ||
| weight: 2914 | ||
| isTocNested: true | ||
| showAsideToc: true | ||
| --- | ||
|
|
||
| After you've gotten the docs site [running locally](../docs-build/), make your changes. If you're going to be doing this a lot, read some [tips on setting up your text editor](../docs-editor-setup/). | ||
|
|
||
| If you need to edit syntax diagrams, see [Edit syntax diagrams](../syntax-diagrams/). | ||
|
|
||
| ## Edit an existing page | ||
|
|
||
| 1. In your local copy of your yugabyte-db fork, make a branch. | ||
|
|
||
| ```sh | ||
| git checkout -b my-branch-name | ||
| ``` | ||
|
|
||
| 1. Find your file in `docs/content/<version>/` and edit it as required. | ||
|
|
||
| 1. Verify that your changes look good in the live-reload server. | ||
|
|
||
| ```sh | ||
| npm start | ||
| ``` | ||
|
|
||
| 1. Commit your changes. | ||
|
|
||
| ```sh | ||
| git commit -A -m "Your commit message here" | ||
| ``` | ||
|
|
||
| 1. Push your changes to your fork. | ||
|
|
||
| ```sh | ||
| git push origin | ||
| ``` | ||
|
|
||
| At this point, you're ready to [create a pull request](#make-a-pr). | ||
| ## Add a new page | ||
| Adding a new page is similar in most ways to editing an existing page, with the added complexity of sorting out the _frontmatter_ so that the page works correctly in the site, including showing up in the left-side navigation menu. See [how docs pages are structured](../docs-page-structure/) for more information. | ||
| _More content in this section is coming soon._ | ||
| ## Make a pull request {#make-a-pr} | ||
| Once you've made your changes, make a pull request by telling GitHub to compare a branch _on your fork_ to the master branch on the main repository. | ||
|
|
||
| ### Use the PR preview build | ||
|
|
||
| Preview builds take 10-15 minutes to build. | ||
|
|
||
| All PR previews on the main repository are of the form `https://deploy-preview-ABCD--infallible-bardeen-164bc9.netlify.app/` where ABCD is the pull request number. | ||
|
|
||
| Add a line in your PR's description to tag the Netlify bot and tell it where to launch the preview: | ||
| `@netlify /preview/quick-start/` | ||
| ### Ask for a review | ||
| **Internal contributors**, please tag a member of the docs team for review, along with technical reviewers as required, and let us know about your PR in the #docs channel in Slack. | ||
| **External contributors**, please add the `area/documentation` label to your pull request, and let us know about it [in Slack](https://www.yugabyte.com/slack/). |
Oops, something went wrong.