From f4e97acd36ab7fb69a731660680b38bb9e095d7f Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Thu, 29 Sep 2022 15:53:13 -0700 Subject: [PATCH] [docs] update contributors guide --- docs/.markdownlint.json | 36 +++++++++++++------ .../preview/contribute/docs/docs-build.md | 17 ++++----- .../preview/contribute/docs/docs-edit.md | 18 +++++++--- .../contribute/docs/docs-editor-setup.md | 4 +-- 4 files changed, 49 insertions(+), 26 deletions(-) diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json index 0ead439341a8..de7485f51945 100644 --- a/docs/.markdownlint.json +++ b/docs/.markdownlint.json @@ -1,13 +1,27 @@ { "default": true, - "MD007": {"indent": 2}, - "MD009": {"list_item_empty_lines": false, "strict": true}, - "MD013": false, - "MD014": false, - "MD024": {"siblings_only": true}, - "MD033": false, - "MD036": false, - "MD041": {"front_matter_title": "^\\s*title\\s*[:=]"}, - "MD046": {"style": "fenced"}, - "MD048": {"style": "backtick"} -} + "code-block-style": { + "style": "fenced" + }, + "code-fence-style": { + "style": "backtick" + }, + "commands-show-output": false, + "line-length": false, + "no-duplicate-heading": { + "siblings_only": true + }, + "first-line-heading": { + "front_matter_title": "^\\s*title\\s*[:=]" + }, + "link-fragments": false, + "no-emphasis-as-heading": false, + "no-inline-html": false, + "no-trailing-spaces": { + "list_item_empty_lines": false, + "strict": true + }, + "ul-indent": { + "indent": 2 + } +} \ No newline at end of file diff --git a/docs/content/preview/contribute/docs/docs-build.md b/docs/content/preview/contribute/docs/docs-build.md index dee7b0c867d6..c66b95a12582 100644 --- a/docs/content/preview/contribute/docs/docs-build.md +++ b/docs/content/preview/contribute/docs/docs-build.md @@ -28,15 +28,14 @@ To run the docs site locally and edit the docs, you'll need: * [**Homebrew**](https://brew.sh) on macOS or Linux. -* **Node.js**, installable in several ways: +* **[Node.js](https://nodejs.org/en/download/)** LTS (16) or current (18): - * Using Homebrew: `brew install node` - * Using NVM: `nvm use node` - * From the [node.js website](https://nodejs.org/en/download/) + * Using Homebrew: `brew install node` for current, or `brew install node@16` for LTS + * Using NVM: `nvm install 18` for current, or `nvm install --lts` for LTS -* **Hugo**: `brew install hugo` gets you the latest version. +* **Hugo**: `brew install hugo` installs the latest version. -* **Go**: `brew install go` gets you the latest version. +* **Go**: `brew install go` installs the latest version. * **A GitHub account**. @@ -56,13 +55,15 @@ Create the folder with `mkdir ~/.hugo-cache`, then start a new terminal session. ## 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. +1. To make the commands in this section work correctly when you paste them, set an environment variable to store your GitHub username. (Replace `your-github-id` here with your own GitHub ID.) ```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: +1. Fork the [`yugabyte-db` GitHub repository](https://github.com/yugabyte/yugabyte-db/). + +1. Create a local clone of your fork: ```sh git clone https://github.com/$GITHUB_ID/yugabyte-db.git diff --git a/docs/content/preview/contribute/docs/docs-edit.md b/docs/content/preview/contribute/docs/docs-edit.md index 0d95ffa1a7e9..6494357b1d58 100644 --- a/docs/content/preview/contribute/docs/docs-edit.md +++ b/docs/content/preview/contribute/docs/docs-edit.md @@ -18,13 +18,21 @@ If you need to edit syntax diagrams, see [Edit syntax diagrams](../syntax-diagra ## Edit an existing page -1. In your local copy of your yugabyte-db fork, make a branch. +1. In your local copy of your `yugabyte-db` fork, make sure your local `master` branch is up to date, and send any changes to GitHub's copy of your fork. + + ```sh + git checkout master + git pull upstream master # get up to date with the Yugabyte GitHub repo + git push origin # send any changes to your fork on GitHub + ``` + +1. Next, make a branch. ```sh git checkout -b my-branch-name ``` -1. Find your file in `docs/content//` and edit it as required. +1. Find your file(s) in `docs/content//...` and edit as required. 1. Verify that your changes look good in the live-reload server. @@ -64,16 +72,16 @@ Preview builds take 5 minutes to build. All PR previews on the main repository are of the form `https://deploy-preview-ABCDE--infallible-bardeen-164bc9.netlify.app/` where ABCDE 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: +Add a line in your pull request's description to tag the Netlify bot and tell it where to launch the preview: `@netlify /preview/quick-start/` ### Run a link checker -https://linkchecker.github.io/linkchecker/ + ### 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. +**Internal contributors**, please add the `area/documentation` label to your pull request, 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/). diff --git a/docs/content/preview/contribute/docs/docs-editor-setup.md b/docs/content/preview/contribute/docs/docs-editor-setup.md index 2fa9a93868c7..427112e9c766 100644 --- a/docs/content/preview/contribute/docs/docs-editor-setup.md +++ b/docs/content/preview/contribute/docs/docs-editor-setup.md @@ -24,9 +24,9 @@ To install an extension in Visual Studio Code, click the Extensions icon in the * **GitHub Pull Requests and Issues**, by GitHub: Pretty good pull request support. Not perfect, and can get confused with large PRs, but handy on a regular basis. -* **GitLens — Git supercharged**, by Eric Amodio: Useful git tooling, including per-line blame/history. +* **GitLens — Git supercharged**, by Eric Amodio: Useful Git tooling, including per-line blame/history. -* **Markdown Preview Enhanced**, by Yiyi Wang: Even nicer markdown previews. +* **Markdown Preview Enhanced**, by Yiyi Wang: Even nicer Markdown previews. * **markdownlint**, by David Anson: Lints your markdown formatting to catch errors and inconsistencies.