-
Notifications
You must be signed in to change notification settings - Fork 223
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README and CONTRIBUTING sections (#1392)
* Move gatsby CONTRIBUTING files to separate folder * Update README and CONTRIBUTING with instructions for Grafana docs
- Loading branch information
1 parent
a50d9bf
commit a7b7680
Showing
6 changed files
with
220 additions
and
125 deletions.
There are no files selected for viewing
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 |
|---|---|---|
|
|
@@ -7,127 +7,89 @@ When you contribute to the docs, it helps to know how things work. | |
|
|
||
| - [Important directories](#important-directories) | ||
| - [Build locally](#build-locally) | ||
| - [Necessary software](#necessary-software) | ||
| - [Build procedure](#build-procedure) | ||
| - [Before you begin](#before-you-begin) | ||
| - [Build and preview](#build-and-preview) | ||
| - [Write](#write) | ||
| - [Style Guides](#style-guides) | ||
| - [Gatsby components](#gatsby-components) | ||
| - [Troubleshooting](#troubleshooting) | ||
| - [Shortcodes](#shortcodes) | ||
| - [Deploy](#deploy) | ||
| - [Upgrade a main release](#upgrade-a-main-release) | ||
|
|
||
| <!-- markdown-toc end --> | ||
|
|
||
|
|
||
| ## Important directories | ||
|
|
||
| For writers, these are the most important directories: | ||
| - [`src/data/markdown`](../src/data/markdown) is where the docs live | ||
| - `translated-guides` has the principle OSS docs | ||
| - [`gatsby-node.js`](../gatsby-node.js) is where URI redirects are programmed. | ||
| - [`src/templates/docs`](../src/templates/docs) has the "landing pages" for major docs sections: cloud, guides, examples, et cetera. | ||
| - [`src/components/shared`](../src/components/shared) has the reusable writing enhancements, like our stylish `<blockquote>` | ||
|
|
||
| - [`docs/sources`](../docs/sources) is where the docs live. | ||
| - `docs/sources/VERSION/shared` has Markdown files that can be reused across multiple pages by using the [`shared` shortcode](https://grafana.com/docs/writers-toolkit/write/shortcodes/#docsshared). | ||
|
|
||
| ## Build locally | ||
|
|
||
| For any substantial changes, a local, live preview hugely improves writer comfort, which translates to better doc quality. | ||
| ### Before you begin | ||
|
|
||
| ### Necessary software | ||
| To build the k6 docs in your machine, you'll need: | ||
|
|
||
| If you don't want to build with Docker (refer to repo README), you'll need the following | ||
| - [NodeJS](https://nodejs.org/en/download/), version 16.0.0 or higher | ||
| - A node version manager like [`nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) or `fnm` | ||
| - `npm` or `yarn` | ||
| - [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) | ||
|
|
||
| ### Build procedure | ||
| If you're using Docker, make sure you have the Docker Desktop application running. | ||
|
|
||
| To build locally: | ||
| ### Build and preview | ||
|
|
||
| 1. Clone the project. | ||
| Clone the repository to your machine: | ||
|
|
||
| ```bash | ||
| git clone [email protected]:grafana/k6-docs.git | ||
| cd k6-docs | ||
| ``` | ||
| ```bash | ||
| git clone https://github.com/grafana/k6-docs.git | ||
| ``` | ||
|
|
||
| 2. Use the version manager to install a version of node compatible with the version in `package.json`. | ||
| Navigate to the `docs` directory and run `make docs`: | ||
|
|
||
| ```bash | ||
| nvm install 16.16 | ||
| nvm use 16.16 | ||
| ``` | ||
| ```bash | ||
| cd docs && make docs | ||
| ``` | ||
|
|
||
| 3. Install dependencies (only necessary the first time). | ||
| You should see an output similar to this when the site finishes building: | ||
|
|
||
| ```bash | ||
| npm install # or yarn install | ||
| ``` | ||
| ```bash | ||
| View documentation locally: | ||
| http://localhost:3002/docs/k6/ | ||
|
|
||
| 4. Run the docs locally. | ||
| Press Ctrl+C to stop the server | ||
| ``` | ||
|
|
||
| ```bash | ||
| npm start # or yarn start | ||
| ``` | ||
| Go to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs. | ||
|
|
||
| If everything works, a live preview should be serving on http://localhost:8000. | ||
| Things don't always work, though. The [Troubleshooting](./troubleshooting) section covers some common breaks. | ||
| Refer to [Writers' Toolkit, Build and review documentation](https://grafana.com/docs/writers-toolkit/review/) for more details about how to build the docs, and tools you can use such as Vale. | ||
|
|
||
| ## Write | ||
|
|
||
| Each Markdown page should start with the following frontmatter. | ||
| Each Markdown page should start with the following front matter. | ||
|
|
||
| ```yaml | ||
| --- | ||
| title: <page title> | ||
| excerpt: <summary text for social shares. Aim for 170 characters>. | ||
| description: <summary text for search engines and social shares. Aim for 170 characters>. | ||
| --- | ||
| ``` | ||
|
|
||
| ### Style guides | ||
|
|
||
| - k6 follows the style prescribed in the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/), which itself inherits most of its rules from the [Google developer documentation style guide](https://developers.google.com/style). | ||
|
|
||
| ### Shortcodes | ||
|
|
||
| ### Gatsby components | ||
|
|
||
| - To organize your pages on the site, Gatsby has a specific way to make paths and organize topics. | ||
| We've also added a number of writing enhancements, like nested tables, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Contributor's reference](./gatsby-reference.md). | ||
| - We've also added a number of writing enhancements, like admonitions, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Writers' Toolkit, Shortcodes](https://grafana.com/docs/writers-toolkit/write/shortcodes/). | ||
|
|
||
| ### Troubleshooting | ||
|
|
||
| - [Troubleshooting](troubleshooting.md) has fixes for common breaks. | ||
| Refer to [Writers' Toolkit, Write documentation](https://grafana.com/docs/writers-toolkit/write/) for more details about how to write new topics, how to use shortcodes, how to add images, and more. | ||
|
|
||
| ## Deploy | ||
|
|
||
| GitHub actions build previews of the site in multiple stages: | ||
|
|
||
| 1. Each PR to main gets a build preview at `https://mdr-ci.staging.k6.io/docs/refs/pull/<PR-NUMBER>/merge`. With every commit to the PR branch, the preview updates. | ||
| 1. The main branch deploys to `staging.k6.io` | ||
| 1. **After the repo release number is upgraded, the main branch deploys to `k6.io`** | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Once a PR is merged to the main branch, if there are any changes made to the `docs/sources` folder, the GitHub Action [`publish-technical-documentation.yml`](https://github.com/grafana/k6-docs/blob/main/.github/workflows/publish-technical-documentation.yml) will sync the changes with the grafana/website repository, and the changes will be deployed to production soon after. | ||
|
|
||
| ### Upgrade a main release | ||
|
|
||
| > #### ⚠️ Versions | ||
| > | ||
| > Versions follow the same major and minor numbers as github.com/grafana/k6. When cutting a new release of the docs between k6 releases, only increment the patch digits. | ||
| Before you upgrade versions, it's a good idea to give the updated docs a final look at `https://staging.k6.io` | ||
| **Especially check that redirects work and components render correctly!** | ||
|
|
||
| Unless k6 OSS has a version upgrade, increment the version by 0.0.1. For example, `0.43.1` → `0.43.2` | ||
| As the UI might change, refer to the GitHub [Managing releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) doc for the canonical instructions. | ||
|
|
||
| Each release has a tag, which you can create either through the Github CLI or from https://github.com/grafana/k6-docs/releases. | ||
| To upgrade through the UI: | ||
|
|
||
| 1. From the releases page, select **Draft a new Release**. | ||
|  | ||
|
|
||
| 1. In the next screen, select **Choose a tag**, type a version number increasing the one below (in image, it should be v0.37.17). | ||
|  | ||
| > Versions follow the same major and minor numbers as github.com/grafana/k6. | ||
| 1. For a small release (fixing a typo or broken link), you can manually add a short description. Otherwise, select **Generate release notes** to automatically include more information about what's changed, and then select **Publish release**. | ||
| TODO: Add step-by-step instructions for creating a new major version release. | ||
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,133 @@ | ||
| # Contributor's guide | ||
|
|
||
| When you contribute to the docs, it helps to know how things work. | ||
|
|
||
| <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --> | ||
| **Table of Contents** | ||
|
|
||
| - [Important directories](#important-directories) | ||
| - [Build locally](#build-locally) | ||
| - [Necessary software](#necessary-software) | ||
| - [Build procedure](#build-procedure) | ||
| - [Write](#write) | ||
| - [Style Guides](#style-guides) | ||
| - [Gatsby components](#gatsby-components) | ||
| - [Troubleshooting](#troubleshooting) | ||
| - [Deploy](#deploy) | ||
| - [Upgrade a main release](#upgrade-a-main-release) | ||
|
|
||
| <!-- markdown-toc end --> | ||
|
|
||
| ## Important directories | ||
|
|
||
| For writers, these are the most important directories: | ||
|
|
||
| - [`src/data/markdown`](../../src/data/markdown) is where the docs live | ||
| - `translated-guides` has the principle OSS docs | ||
| - [`gatsby-node.js`](../../gatsby-node.js) is where URI redirects are programmed. | ||
| - [`src/templates/docs`](./../src/templates/docs) has the "landing pages" for major docs sections: cloud, guides, examples, et cetera. | ||
| - [`src/components/shared`](../../src/components/shared) has the reusable writing enhancements, like our stylish `<blockquote>` | ||
|
|
||
| ## Build locally | ||
|
|
||
| For any substantial changes, a local, live preview hugely improves writer comfort, which translates to better doc quality. | ||
|
|
||
| ### Necessary software | ||
|
|
||
| If you don't want to build with Docker (refer to repo README), you'll need the following | ||
| - [NodeJS](https://nodejs.org/en/download/), version 16.0.0 or higher | ||
| - A node version manager like [`nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) or `fnm` | ||
| - `npm` or `yarn` | ||
|
|
||
| ### Build procedure | ||
|
|
||
| To build locally: | ||
|
|
||
| 1. Clone the project. | ||
|
|
||
| ```bash | ||
| git clone [email protected]:grafana/k6-docs.git | ||
| cd k6-docs | ||
| ``` | ||
|
|
||
| 2. Use the version manager to install a version of node compatible with the version in `package.json`. | ||
|
|
||
| ```bash | ||
| nvm install 16.16 | ||
| nvm use 16.16 | ||
| ``` | ||
|
|
||
| 3. Install dependencies (only necessary the first time). | ||
|
|
||
| ```bash | ||
| npm install # or yarn install | ||
| ``` | ||
|
|
||
| 4. Run the docs locally. | ||
|
|
||
| ```bash | ||
| npm start # or yarn start | ||
| ``` | ||
|
|
||
| If everything works, a live preview should be serving on http://localhost:8000. | ||
| Things don't always work, though. The [Troubleshooting](./troubleshooting) section covers some common breaks. | ||
|
|
||
| ## Write | ||
|
|
||
| Each Markdown page should start with the following front matter. | ||
|
|
||
| ```yaml | ||
| --- | ||
| title: <page title> | ||
| excerpt: <summary text for social shares. Aim for 170 characters>. | ||
| --- | ||
| ``` | ||
|
|
||
| ### Style guides | ||
|
|
||
| - k6 follows the style prescribed in the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/), which itself inherits most of its rules from the [Google developer documentation style guide](https://developers.google.com/style). | ||
|
|
||
|
|
||
| ### Gatsby components | ||
|
|
||
| - To organize your pages on the site, Gatsby has a specific way to make paths and organize topics. | ||
| We've also added a number of writing enhancements, like nested tables, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Contributor's reference](./gatsby-reference.md). | ||
|
|
||
| ### Troubleshooting | ||
|
|
||
| - [Troubleshooting](troubleshooting.md) has fixes for common breaks. | ||
|
|
||
| ## Deploy | ||
|
|
||
| GitHub actions build previews of the site in multiple stages: | ||
|
|
||
| 1. Each PR to main gets a build preview at `https://mdr-ci.staging.k6.io/docs/refs/pull/<PR-NUMBER>/merge`. With every commit to the PR branch, the preview updates. | ||
| 1. The main branch deploys to `staging.k6.io` | ||
| 1. **After the repo release number is upgraded, the main branch deploys to `k6.io`** | ||
|
|
||
|  | ||
|
|
||
|
|
||
|
|
||
| ### Upgrade a main release | ||
|
|
||
| > #### ⚠️ Versions | ||
| > | ||
| > Versions follow the same major and minor numbers as github.com/grafana/k6. When cutting a new release of the docs between k6 releases, only increment the patch digits. | ||
| Before you upgrade versions, it's a good idea to give the updated docs a final look at `https://staging.k6.io` | ||
| **Especially check that redirects work and components render correctly!** | ||
|
|
||
| Unless k6 OSS has a version upgrade, increment the version by 0.0.1. For example, `0.43.1` → `0.43.2` | ||
| As the UI might change, refer to the GitHub [Managing releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) doc for the canonical instructions. | ||
|
|
||
| Each release has a tag, which you can create either through the Github CLI or from https://github.com/grafana/k6-docs/releases. | ||
| To upgrade through the UI: | ||
|
|
||
| 1. From the releases page, select **Draft a new Release**. | ||
|  | ||
|
|
||
| 1. In the next screen, select **Choose a tag**, type a version number increasing the one below (in image, it should be v0.37.17). | ||
|  | ||
|
|
||
| 1. For a small release (fixing a typo or broken link), you can manually add a short description. Otherwise, select **Generate release notes** to automatically include more information about what's changed, and then select **Publish release**. |
Oops, something went wrong.