From 714d270fc65d2a87dbd9d0f6ca87c4969e481f8e Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 28 Jun 2023 16:37:17 -0400 Subject: [PATCH 01/19] Rewrite Contributing and readme Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 121 ++++++++++++++++++++++++++++++++++++------------ README.md | 120 +++++++++-------------------------------------- 2 files changed, 113 insertions(+), 128 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f06b655e7..b83035347f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,60 +1,123 @@ # Contributing Guidelines -Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and to report technical issues with the documentation site. +Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. -The OpenSearch documentation team is dedicated to providing complete and best-in-class documentation. Thank you for your patience as we build our documentation team and content library. We appreciate your support and patience. +## Finding contributions to work on -## How to request changes +If you’d like to contribute but don't know where to start, try browsing existing issues. Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. -Before entering a change request, please read this document carefully. We want to make sure we have all the information necessary to effectively respond to your contribution. +## Contributing to the documentation site -There are two ways to contribute: 1) create an issue where you describe the change and 2) create a pull request that contains the content to directly insert into the documentation. +There are two ways to contribute: +1. [Create an issue](#create-an-issue) asking us to change the documentation. +2. [Contribute documentation content](#contribute-content) yourself. -**Create an Issue** +## Create an issue -Use the Github issue tracker to describe the change you'd like to make. +Use the GitHub issue tracker to describe the change you'd like to make: 1. Go to https://github.com/opensearch-project/documentation-website/issues and select *New issue*. -2. Enter the requested information and include as much detail as possible, especially which version or versions the request affects. +2. Enter the requested information, including as much detail as possible, especially which version or versions the request affects. 3. Select *Submit new issue*. +The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. -The ‘untriaged’ label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. +## Contribute content +There are two ways to contribute content: -**Create a pull request** +- [Editing files directly in GitHub](#editing-files-in-github): Best for small changes like fixing a typo or adding a parameter. This approach does not require cloning the repository and does not let you test the documentation. +- [Making changes locally and pushing to GitHub](#making-changes-locally): Best for changes you want to test locally first, like adding a table or section, or reorganizing pages. This approach requires setting up a local version of the repository and lets you test documentation. -If you’d like to make a change directly to the content, create a pull request. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. +The workflow for contributing documentation is no different than the one for contributing code: -Note that a pull request requires DCO sign off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example $ git commit -s -m 'This is my commit message'. For more information, see https://github.com/apps/dco. +- Make your changes +- Build locally to check your work (only possible if you are making changes locally) +- Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR) +- Maintainers review and merge your PR -Before submitting, make sure to: +If the change requires significant work, open an issue where we can first discuss your request. -* Work against the latest source on the main branch. -* Check existing open and recently merged pull requests to ensure that someone else hasn't addressed the problem already. -* If the change requires significant work, open an issue where we can first discuss your request. +### Before you start -To create a pull request: +Before contributing content, make sure to read the following resources: +- [README](README) +- [OpenSearch Project Style Guidelines](STYLE_GUIDE) +- [API Style Guide](API_STYLE_GUIDE) +- [Formatting Guide](FORMATTING_GUIDE) -1. Fork the repository. -2. Modify the source. Make sure to focus on the specific change you are contributing. For example, if you also reformat the code, it will be hard for us to focus on your change. -3. Test the code. Make sure that any local tests pass. -4. Commit to your fork using clear commit messages. -5. Create the [pull request](https://github.com/opensearch-project/documentation-website/pulls) and save it, making sure to answer the default questions in the pull request template. +### Editing files in GitHub -If you need additional support, GitHub provides documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/). +If you want to add a few paragraphs to a file, try this approach: +1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo). -## Finding contributions to work on +1. In your fork on GitHub, navigate to the file that you want to change. + +1. In the upper-right corner, select the dropdown with the pencil icon and select **Edit in place**. Edit the file. + +1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**. + + +### Making changes locally + +If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to make the changes and view them locally: + +1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork. + +1. Navigate to the repository root. + +1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer: + + ``` + curl -sSL https://get.rvm.io | bash -s stable + rvm install 2.6 + ruby -v + ``` + +1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it: + + ``` + gem install bundler jekyll + ``` + +1. Install dependencies: + + ``` + bundle install + ``` + +1. Build: + + ``` + sh build.sh + ``` + +1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/). + +1. Create a new branch against the latest source on the main branch. + +1. Edit the Markdown files that you want to change. + +1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10 to 30 seconds. + +1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. + + Note that a pull request requires DCO sign off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example $ git commit -s -m 'This is my commit message'. For more information, see https://github.com/apps/dco. + + +### Review process + +We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. -If you’d like to contribute but don't know where to start, try browsing existing issues. Our projects use custom GitHub issue labels for status, version, type of request, etc., but we recommend looking at any issues labeled “good first issue” first. +During the PR process, expect that there will be some back-and-forth. Please try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. +We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README#style-linting). -## Security issue notifications +If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. -If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. +## Getting help -## Licensing +For help with any step in the contributing process, please reach out to one of the [points of contact](README#points-of-contact). -See the [LICENSE](LICENSE) file for our project's licensing. diff --git a/README.md b/README.md index a7c5033080..1b97433e96 100644 --- a/README.md +++ b/README.md @@ -4,33 +4,9 @@ The documentation repository contains the documentation for OpenSearch, the search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs). - -## How you can help - -Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. If you are interested in contributing, please see the [Contribution](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) file. - - -## Points of contact - -If you encounter problems or have questions when contributing to the documentation, these people can help: - -- [cwillum](https://github.com/cwillum) -- [hdhalter](https://github.com/hdhalter) -- [kolchfa-aws](https://github.com/kolchfa-aws) -- [Naarcha-AWS](https://github.com/Naarcha-AWS) -- [vagimeli](https://github.com/vagimeli) - - ## How the website works -This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll "collections" (e.g., `_search-plugins`, `_opensearch`, etc.). Each Markdown file correlates with one page on the website. - -Using plain text on GitHub has many advantages: - -- Everything is free, open source, and works on every operating system. Use your favorite text editor, Ruby, Jekyll, and Git. -- Markdown is easy to learn and looks good in side-by-side diffs. -- The workflow is no different than contributing code. Make your changes, build locally to check your work, and submit a pull request. Reviewers check the PR before merging. -- Alternatives like wikis and WordPress are full web applications that require databases and ongoing maintenance. They also have inferior versioning and content review processes compared to Git. Static websites, such as the ones Jekyll produces, are faster, more secure, and more stable. +This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll _collections_ (for example, `_api-reference` or `_dashboards`). Each Markdown file corresponds to one page on the website. In addition to the content for a given page, each Markdown file contains some Jekyll [front matter](https://jekyllrb.com/docs/front-matter/). Front matter looks like this: @@ -44,82 +20,14 @@ has_children: false --- ``` -If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the lefthand navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/). - - -## Contribute content - -There are a few ways to contribute content, depending on the magnitude of the change. - -- [Minor changes](#minor-changes) -- [Major changes](#major-changes) -- [Create an issue](https://github.com/opensearch-project/documentation-website/issues) - - -### Minor changes - -If you want to add a few paragraphs across multiple files and are comfortable with Git, try this approach: - -1. Fork this repository. - -1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork. - -1. Navigate to the repository root. - -1. Create a new branch. - -1. Edit the Markdown files in `/docs`. - -1. Commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. +If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/). -### Major changes - -If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to make the changes and view them locally: - -1. Fork this repository. - -1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork. - -1. Navigate to the repository root. - -1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer: - - ``` - curl -sSL https://get.rvm.io | bash -s stable - rvm install 2.6 - ruby -v - ``` - -1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it: - - ``` - gem install bundler jekyll - ``` - -1. Install dependencies: - - ``` - bundle install - ``` - -1. Build: - - ``` - sh build.sh - ``` - -1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/). - -1. Create a new branch. - -1. Edit the Markdown files in each collection (e.g. `_security/`). - - If you're a web developer, you can customize `_layouts/default.html` and `_sass/custom/custom.scss`. +## How you can help -1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10-30 seconds. +Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. -1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. +If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md). ## Writing tips @@ -128,6 +36,8 @@ The OpenSearch team released [style guidelines](https://github.com/opensearch-pr We also provide guidelines on terminology. For a list of OpenSearch terms, see [Terms](https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md). +If you are contributing API content, see the [API Style Guide](API_STYLE_GUIDE) for API documentation guidelines. + ## Formatting documentation @@ -143,6 +53,18 @@ We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our d Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension that integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. + +## Points of contact + +If you encounter problems or have questions when contributing to the documentation, these people can help: + +- [cwillum](https://github.com/cwillum) +- [hdhalter](https://github.com/hdhalter) +- [kolchfa-aws](https://github.com/kolchfa-aws) +- [Naarcha-AWS](https://github.com/Naarcha-AWS) +- [vagimeli](https://github.com/vagimeli) + + ## Code of conduct This project has adopted an [Open Source Code of Conduct](https://opensearch.org/codeofconduct.html). @@ -150,12 +72,12 @@ This project has adopted an [Open Source Code of Conduct](https://opensearch.org ## Security -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. +If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue. ## License -This project is licensed under the Apache-2.0 License. +This project is licensed under the [Apache 2.0 License](LICENSE). ## Copyright From b878946a7f8fab24c66164f2a6c716b5e62ab2aa Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 28 Jun 2023 22:00:13 -0400 Subject: [PATCH 02/19] Changes to the structure Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++---------------- README.md | 8 +++---- 2 files changed, 47 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b83035347f..faafe1b7f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,40 @@ +- [Finding contributions to work on](#finding-contributions-to-work-on) +- [Contributing to the documentation](#contributing-to-the-documentation) +- [Creating an issue](#creating-an-issue) +- [Contributing content](#contributing-content) + - [Before you start](#before-you-start) + - [Editing files in GitHub](#editing-files-in-github) + - [Making changes locally](#making-changes-locally) + - [Setting up your local copy of the repository](#setting-up-your-local-copy-of-the-repository) + - [Making, viewing, and submitting changes](#making-viewing-and-submitting-changes) +- [Review process](#review-process) +- [Getting help](#getting-help) + # Contributing Guidelines Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. ## Finding contributions to work on -If you’d like to contribute but don't know where to start, try browsing existing issues. Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. +If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. -## Contributing to the documentation site +## Contributing to the documentation There are two ways to contribute: -1. [Create an issue](#create-an-issue) asking us to change the documentation. -2. [Contribute documentation content](#contribute-content) yourself. +1. [Create an issue](#creating-an-issue) asking us to change the documentation. +2. [Contribute documentation content](#contributing-content) yourself. -## Create an issue +## Creating an issue Use the GitHub issue tracker to describe the change you'd like to make: -1. Go to https://github.com/opensearch-project/documentation-website/issues and select *New issue*. -2. Enter the requested information, including as much detail as possible, especially which version or versions the request affects. -3. Select *Submit new issue*. +1. Go to https://github.com/opensearch-project/documentation-website/issues and select **New issue**. +1. Enter the requested information, including as much detail as possible, especially which version or versions the request affects. +1. Select **Submit new issue**. The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. -## Contribute content +## Contributing content There are two ways to contribute content: @@ -41,10 +53,13 @@ If the change requires significant work, open an issue where we can first discus ### Before you start Before contributing content, make sure to read the following resources: -- [README](README) -- [OpenSearch Project Style Guidelines](STYLE_GUIDE) -- [API Style Guide](API_STYLE_GUIDE) -- [Formatting Guide](FORMATTING_GUIDE) +- [README](README.md) +- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) +- [API Style Guide](API_STYLE_GUIDE.md) +- [Formatting Guide](FORMATTING_GUIDE.md) + +NOTE: Please make sure that any documentation you submit is your work or work you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. + ### Editing files in GitHub @@ -61,7 +76,11 @@ If you want to add a few paragraphs to a file, try this approach: ### Making changes locally -If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to make the changes and view them locally: +If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, you need to work in a local copy of the repository. + +#### Setting up your local copy of the repository + +Follow these steps to set up your local copy of the repository: 1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork. @@ -87,13 +106,17 @@ If you're making major changes to the documentation and need to see the rendered bundle install ``` -1. Build: +#### Making, viewing, and submitting changes + +Here's how to build the website, make the changes, and view them locally: + +1. Build the website: ``` sh build.sh ``` -1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/). + The build script should automatically open your web browser, but if it doesn't, open [http://localhost:4000/docs/](http://localhost:4000/docs/). 1. Create a new branch against the latest source on the main branch. @@ -103,21 +126,21 @@ If you're making major changes to the documentation and need to see the rendered 1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. - Note that a pull request requires DCO sign off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example $ git commit -s -m 'This is my commit message'. For more information, see https://github.com/apps/dco. + Note that a pull request requires DCO sign-off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example `git commit -s -m 'This is my commit message'`. For more information, see https://github.com/apps/dco. -### Review process +## Review process We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. During the PR process, expect that there will be some back-and-forth. Please try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. -We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README#style-linting). +We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README.md#style-linting). If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. ## Getting help -For help with any step in the contributing process, please reach out to one of the [points of contact](README#points-of-contact). +For help with any step in the contributing process, please reach out to one of the [points of contact](README.md#points-of-contact). diff --git a/README.md b/README.md index 1b97433e96..2a4ac3bc3f 100644 --- a/README.md +++ b/README.md @@ -27,16 +27,16 @@ If you want to reorganize content or add new pages, keep an eye on `has_children Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. -If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md). +If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](CONTRIBUTING.md). ## Writing tips -The OpenSearch team released [style guidelines](https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md) for our documentation and marketing content. These guidelines cover the style standards and terms to be observed when creating OpenSearch content. We ask that you please adhere to these guidelines whenever contributing content. +The OpenSearch team released [style guidelines](STYLE_GUIDE.md) for our documentation and marketing content. These guidelines cover the style standards and terms to be observed when creating OpenSearch content. We ask that you please adhere to these guidelines whenever contributing content. -We also provide guidelines on terminology. For a list of OpenSearch terms, see [Terms](https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md). +We also provide guidelines on terminology. For a list of OpenSearch terms, see [Terms](TERMS.md). -If you are contributing API content, see the [API Style Guide](API_STYLE_GUIDE) for API documentation guidelines. +If you are contributing API content, see the [API Style Guide](API_STYLE_GUIDE.md) for API documentation guidelines. ## Formatting documentation From 2f5ef0956a70e244fe2f92993196b7dfbb6ef5d5 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 29 Jun 2023 12:39:59 -0400 Subject: [PATCH 03/19] Update CONTRIBUTING.md Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index faafe1b7f0..010de1d9bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ There are two ways to contribute: ## Creating an issue -Use the GitHub issue tracker to describe the change you'd like to make: +Use the documentation issue template to describe the change you'd like to make. 1. Go to https://github.com/opensearch-project/documentation-website/issues and select **New issue**. 1. Enter the requested information, including as much detail as possible, especially which version or versions the request affects. From 93e3544c00753e4660337d95cf89a1223be4d4d2 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 29 Jun 2023 14:29:35 -0400 Subject: [PATCH 04/19] Reordered sections Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 41 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index faafe1b7f0..77769a7daa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ -- [Finding contributions to work on](#finding-contributions-to-work-on) -- [Contributing to the documentation](#contributing-to-the-documentation) - [Creating an issue](#creating-an-issue) +- [Finding contributions to work on](#finding-contributions-to-work-on) - [Contributing content](#contributing-content) + - [Documentation workflow](#documentation-workflow) - [Before you start](#before-you-start) - - [Editing files in GitHub](#editing-files-in-github) - - [Making changes locally](#making-changes-locally) + - [Making minor changes](#making-minor-changes) + - [Making major changes](#making-major-changes) - [Setting up your local copy of the repository](#setting-up-your-local-copy-of-the-repository) - [Making, viewing, and submitting changes](#making-viewing-and-submitting-changes) - [Review process](#review-process) @@ -14,15 +14,7 @@ Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. -## Finding contributions to work on - -If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. - -## Contributing to the documentation - -There are two ways to contribute: -1. [Create an issue](#creating-an-issue) asking us to change the documentation. -2. [Contribute documentation content](#contributing-content) yourself. +You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself. ## Creating an issue @@ -34,12 +26,18 @@ Use the GitHub issue tracker to describe the change you'd like to make: The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. +## Finding contributions to work on + +If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. + ## Contributing content -There are two ways to contribute content: +There are two ways to contribute content depending on the magnitude of the change: -- [Editing files directly in GitHub](#editing-files-in-github): Best for small changes like fixing a typo or adding a parameter. This approach does not require cloning the repository and does not let you test the documentation. -- [Making changes locally and pushing to GitHub](#making-changes-locally): Best for changes you want to test locally first, like adding a table or section, or reorganizing pages. This approach requires setting up a local version of the repository and lets you test documentation. +- [Minor changes](#making-minor-changes): For small changes like fixing a typo or adding a parameter, you can edit files in GitHub directly. This approach does not require cloning the repository and does not let you test the documentation. +- [Major changes](#making-major-changes): For changes you want to test first, like reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. + +### Documentation workflow The workflow for contributing documentation is no different than the one for contributing code: @@ -60,8 +58,7 @@ Before contributing content, make sure to read the following resources: NOTE: Please make sure that any documentation you submit is your work or work you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. - -### Editing files in GitHub +### Making minor changes If you want to add a few paragraphs to a file, try this approach: @@ -73,8 +70,7 @@ If you want to add a few paragraphs to a file, try this approach: 1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**. - -### Making changes locally +### Making major changes If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, you need to work in a local copy of the repository. @@ -128,7 +124,6 @@ Here's how to build the website, make the changes, and view them locally: Note that a pull request requires DCO sign-off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example `git commit -s -m 'This is my commit message'`. For more information, see https://github.com/apps/dco. - ## Review process We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. @@ -139,8 +134,6 @@ We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our d If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. - ## Getting help -For help with any step in the contributing process, please reach out to one of the [points of contact](README.md#points-of-contact). - +For help with any step in the contributing process, please reach out to one of the [points of contact](README.md#points-of-contact). \ No newline at end of file From e258bf25cdb064fca340e77257553d8a7d2d836f Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 29 Jun 2023 15:02:34 -0400 Subject: [PATCH 05/19] Apply suggestions from code review Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68eeac3410..93a1b7e543 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ There are two ways to contribute content depending on the magnitude of the chang - [Minor changes](#making-minor-changes): For small changes like fixing a typo or adding a parameter, you can edit files in GitHub directly. This approach does not require cloning the repository and does not let you test the documentation. - [Major changes](#making-major-changes): For changes you want to test first, like reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. -### Documentation workflow +### Contribution workflow The workflow for contributing documentation is no different than the one for contributing code: @@ -56,11 +56,11 @@ Before contributing content, make sure to read the following resources: - [API Style Guide](API_STYLE_GUIDE.md) - [Formatting Guide](FORMATTING_GUIDE.md) -NOTE: Please make sure that any documentation you submit is your work or work you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. +NOTE: Please make sure that any documentation you submit is your work or work that you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. ### Making minor changes -If you want to add a few paragraphs to a file, try this approach: +If you want to make minor changes to an existing file, you can use this approach: 1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo). @@ -72,7 +72,7 @@ If you want to add a few paragraphs to a file, try this approach: ### Making major changes -If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, you need to work in a local copy of the repository. +If you're adding new pages or making major changes to the documentation, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a pull request. #### Setting up your local copy of the repository From 59b10f3dd0ef1ea82a4c7340c440d18aec676726 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 29 Jun 2023 15:05:39 -0400 Subject: [PATCH 06/19] Doc review changes Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 93a1b7e543..9d1eaa23c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,4 @@ - [Creating an issue](#creating-an-issue) -- [Finding contributions to work on](#finding-contributions-to-work-on) - [Contributing content](#contributing-content) - [Documentation workflow](#documentation-workflow) - [Before you start](#before-you-start) @@ -16,6 +15,8 @@ Thank you for your interest in improving the OpenSource documentation! We value You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself. +NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. + ## Creating an issue Use the documentation issue template to describe the change you'd like to make. @@ -26,10 +27,6 @@ Use the documentation issue template to describe the change you'd like to make. The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. -## Finding contributions to work on - -If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. - ## Contributing content There are two ways to contribute content depending on the magnitude of the change: @@ -42,12 +39,10 @@ There are two ways to contribute content depending on the magnitude of the chang The workflow for contributing documentation is no different than the one for contributing code: - Make your changes -- Build locally to check your work (only possible if you are making changes locally) +- Build the documentation website to check your work (only possible if you are making changes locally) - Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR) - Maintainers review and merge your PR -If the change requires significant work, open an issue where we can first discuss your request. - ### Before you start Before contributing content, make sure to read the following resources: From 25a173fcf4add8f9afb2f00f32501abf9447cb00 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 29 Jun 2023 16:24:07 -0400 Subject: [PATCH 07/19] Update CONTRIBUTING.md Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d1eaa23c3..4ff512fc28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ The `untriaged` label is assigned automatically. During the triage process, the There are two ways to contribute content depending on the magnitude of the change: - [Minor changes](#making-minor-changes): For small changes like fixing a typo or adding a parameter, you can edit files in GitHub directly. This approach does not require cloning the repository and does not let you test the documentation. -- [Major changes](#making-major-changes): For changes you want to test first, like reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. +- [Major changes](#making-major-changes): For changes you want to test first, like adding new or reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. ### Contribution workflow From ef011edc8184040b76660d85b1905fec8b33563a Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 29 Jun 2023 16:24:40 -0400 Subject: [PATCH 08/19] Update CONTRIBUTING.md Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ff512fc28..b13b37f470 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ The `untriaged` label is assigned automatically. During the triage process, the There are two ways to contribute content depending on the magnitude of the change: -- [Minor changes](#making-minor-changes): For small changes like fixing a typo or adding a parameter, you can edit files in GitHub directly. This approach does not require cloning the repository and does not let you test the documentation. +- [Minor changes](#making-minor-changes): For small changes to existing files, like fixing typos or adding parameters, you can edit files in GitHub directly. This approach does not require cloning the repository and does not allow you to test the documentation. - [Major changes](#making-major-changes): For changes you want to test first, like adding new or reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. ### Contribution workflow From ab6e2511c1f14b06e54612de98b2bbd74d667954 Mon Sep 17 00:00:00 2001 From: Heather Halter Date: Thu, 29 Jun 2023 14:16:24 -0700 Subject: [PATCH 09/19] added list of resources Signed-off-by: Heather Halter --- README.md | 45 +++++++++------------------------------------ 1 file changed, 9 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 2a4ac3bc3f..49ae8efdca 100644 --- a/README.md +++ b/README.md @@ -2,51 +2,24 @@ # About the OpenSearch documentation repo -The documentation repository contains the documentation for OpenSearch, the search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs). +The documentation repository contains the documentation for OpenSearch, the highly scalable and extensible open-source software suite for search, analytics, observability, and other data-intensive applications. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs). -## How the website works -This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll _collections_ (for example, `_api-reference` or `_dashboards`). Each Markdown file corresponds to one page on the website. +## Contributing -In addition to the content for a given page, each Markdown file contains some Jekyll [front matter](https://jekyllrb.com/docs/front-matter/). Front matter looks like this: +Community contributions remain essential in keeping the documentation comprehensive, useful, well-organized, and up-to-date. If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](CONTRIBUTING.md). -``` ---- -layout: default -title: Alerting security -nav_order: 10 -parent: Alerting -has_children: false ---- -``` +See these important resources when you are considering contributing to the documentation: -If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/). - - -## How you can help - -Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. - -If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](CONTRIBUTING.md). - - -## Writing tips - -The OpenSearch team released [style guidelines](STYLE_GUIDE.md) for our documentation and marketing content. These guidelines cover the style standards and terms to be observed when creating OpenSearch content. We ask that you please adhere to these guidelines whenever contributing content. - -We also provide guidelines on terminology. For a list of OpenSearch terms, see [Terms](TERMS.md). - -If you are contributing API content, see the [API Style Guide](API_STYLE_GUIDE.md) for API documentation guidelines. - - -## Formatting documentation - -The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. For an overview of the commonly used formatted elements, including callouts, videos, and buttons, see the [FORMATTING_GUIDE](FORMATTING_GUIDE.md). +- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) - The style guide covers the style standards to be observed when creating OpenSearch content. +- [Terms](TERMS.md) - The terms list contains the key OpenSearch terms and tips on how and when to use them. +- [API Style Guide](API_STYLE_GUIDE.md) - The API style guide provides the basic structure for creating OpenSearch API documentation. +- [Formatting Guide](FORMATTING_GUIDE.md) - The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. Use the formatting guide for an overview of the commonly used formatted elements, including callouts, videos, and buttons. ## Style linting -We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). To install Vale locally, follow these steps: +To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) we use the [Vale](https://github.com/errata-ai/vale) linter. To install Vale locally, follow these steps: 1. Run `brew install vale`. 2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`. From 1741446c0c58a1f2853726f706b6cd0700538d2a Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 29 Jun 2023 17:57:43 -0400 Subject: [PATCH 10/19] Moved front matter section to formatting guide and linting to contributing Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 10 ++++++++++ FORMATTING_GUIDE.md | 17 +++++++++++++++++ README.md | 12 +----------- 3 files changed, 28 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b13b37f470..39127a4fa4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ - [Setting up your local copy of the repository](#setting-up-your-local-copy-of-the-repository) - [Making, viewing, and submitting changes](#making-viewing-and-submitting-changes) - [Review process](#review-process) + - [Style linting](#style-linting) - [Getting help](#getting-help) # Contributing Guidelines @@ -129,6 +130,15 @@ We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our d If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. +### Style linting + +To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) we use the [Vale](https://github.com/errata-ai/vale) linter. Addressing Vale comments on the PR expedites the review process. You can also install Vale locally as follows so you can address the comments before creating a PR: + +1. Run `brew install vale`. +2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`. + +Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension that integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. + ## Getting help For help with any step in the contributing process, please reach out to one of the [points of contact](README.md#points-of-contact). \ No newline at end of file diff --git a/FORMATTING_GUIDE.md b/FORMATTING_GUIDE.md index d5a4d2226a..f2ba41383f 100644 --- a/FORMATTING_GUIDE.md +++ b/FORMATTING_GUIDE.md @@ -31,6 +31,23 @@ This guide provides an overview of the formatted elements commonly used in the O ## Adding pages or sections +This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll _collections_ (for example, `_api-reference` or `_dashboards`). Each Markdown file corresponds to one page on the website. + +In addition to the content for a given page, each Markdown file contains some Jekyll [front matter](https://jekyllrb.com/docs/front-matter/) similar to the following: + +``` +--- +layout: default +title: Date +nav_order: 25 +has_children: false +parent: Date field types +grand_parent: Supported field types +--- +``` + +If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, `grand_parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. + When adding a page or a section, make the `nav_order` of the child pages multiples of 10. For example, if you have a parent page `Clients`, make child pages `Java`, `Python`, and `JavaScript` have a `nav_order` of 10, 20, and 30, respectively. Doing so makes inserting additional child pages easier because it does not require you to renumber existing pages. Each collection must have an `index.md` file that corresponds to the collection's index page. In the `index.md` file's front matter, specify `nav_excluded: true` so that the page does not appear separately under the collection. diff --git a/README.md b/README.md index 49ae8efdca..21fada1bc7 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,7 @@ See these important resources when you are considering contributing to the docum - [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) - The style guide covers the style standards to be observed when creating OpenSearch content. - [Terms](TERMS.md) - The terms list contains the key OpenSearch terms and tips on how and when to use them. - [API Style Guide](API_STYLE_GUIDE.md) - The API style guide provides the basic structure for creating OpenSearch API documentation. -- [Formatting Guide](FORMATTING_GUIDE.md) - The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. Use the formatting guide for an overview of the commonly used formatted elements, including callouts, videos, and buttons. - - -## Style linting - -To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) we use the [Vale](https://github.com/errata-ai/vale) linter. To install Vale locally, follow these steps: - -1. Run `brew install vale`. -2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`. - -Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension that integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. +- [Formatting Guide](FORMATTING_GUIDE.md) - The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. Use the formatting guide for an overview of the commonly used formatted elements and to learn how to add pages to the website. ## Points of contact From 787188fc42e4cef5144ca3fb5069e84f4493777b Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 29 Jun 2023 18:34:44 -0400 Subject: [PATCH 11/19] Apply suggestions from code review Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39127a4fa4..89bc8c9e1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ - [Creating an issue](#creating-an-issue) - [Contributing content](#contributing-content) - - [Documentation workflow](#documentation-workflow) + - [Contribution workflow](#contribution-workflow) - [Before you start](#before-you-start) - [Making minor changes](#making-minor-changes) - [Making major changes](#making-major-changes) @@ -10,9 +10,9 @@ - [Style linting](#style-linting) - [Getting help](#getting-help) -# Contributing Guidelines +# Contributing guidelines -Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. +Thank you for your interest in improving the OpenSearch documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself. From c7cd5ad976390cc273f550f6923fb2ebc26b7b53 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Fri, 30 Jun 2023 12:13:20 -0400 Subject: [PATCH 12/19] Apply suggestions from code review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 10 +++++----- README.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89bc8c9e1f..f48a45732a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ Before contributing content, make sure to read the following resources: - [API Style Guide](API_STYLE_GUIDE.md) - [Formatting Guide](FORMATTING_GUIDE.md) -NOTE: Please make sure that any documentation you submit is your work or work that you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. +NOTE: Make sure that any documentation you submit is your work or work that you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. ### Making minor changes @@ -68,7 +68,7 @@ If you want to make minor changes to an existing file, you can use this approach ### Making major changes -If you're adding new pages or making major changes to the documentation, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a pull request. +If you're adding new pages or making major changes to the documentation, such as adding new images, pages, sections, or styling, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a pull request. #### Setting up your local copy of the repository @@ -76,7 +76,7 @@ Follow these steps to set up your local copy of the repository: 1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork. -1. Navigate to the repository root. +1. Navigate to your cloned repository. 1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer: @@ -92,7 +92,7 @@ Follow these steps to set up your local copy of the repository: gem install bundler jekyll ``` -1. Install dependencies: +1. Install the Jekyll dependencies: ``` bundle install @@ -124,7 +124,7 @@ Here's how to build the website, make the changes, and view them locally: We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. -During the PR process, expect that there will be some back-and-forth. Please try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. +During the PR process, expect that there will be some back-and-forth. If you want to get your contribution merged quickly, try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README.md#style-linting). diff --git a/README.md b/README.md index 21fada1bc7..7dc265fd87 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ This project has adopted an [Open Source Code of Conduct](https://opensearch.org ## Security -If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue. +If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Do **not** create a public GitHub issue. ## License From 47205fc833cefc6865cf42137a32d9d41de5bf1c Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 30 Jun 2023 12:18:14 -0400 Subject: [PATCH 13/19] Add doc review comments Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39127a4fa4..ae0da6d5c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ Thank you for your interest in improving the OpenSource documentation! We value You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself. -NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. +NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on. We recommend starting with at any issue labeled `good first issue` if you're a beginner and `help wanted` if you're a more experienced user. ## Creating an issue @@ -62,7 +62,7 @@ If you want to make minor changes to an existing file, you can use this approach 1. In your fork on GitHub, navigate to the file that you want to change. -1. In the upper-right corner, select the dropdown with the pencil icon and select **Edit in place**. Edit the file. +1. In the upper-right corner, select the dropdown with the pencil icon and edit the file. 1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**. @@ -114,7 +114,7 @@ Here's how to build the website, make the changes, and view them locally: 1. Edit the Markdown files that you want to change. -1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10 to 30 seconds. +1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds. 1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. From 805913837cdd416a166549dfaa8e0d27dd525ea5 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 30 Jun 2023 12:21:24 -0400 Subject: [PATCH 14/19] Delete word Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae0da6d5c8..ca8225878b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -114,7 +114,7 @@ Here's how to build the website, make the changes, and view them locally: 1. Edit the Markdown files that you want to change. -1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds. +1. When you save a file, Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds. 1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. From cfbb73d482a4377dffa334e15319500e81b94f28 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 30 Jun 2023 13:53:28 -0400 Subject: [PATCH 15/19] Minor rewording Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc9f48a356..6040cfdd58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ If you want to make minor changes to an existing file, you can use this approach 1. In your fork on GitHub, navigate to the file that you want to change. -1. In the upper-right corner, select the dropdown with the pencil icon and edit the file. +1. In the upper-right corner, select the pencil icon and edit the file. 1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**. From 9281a3125165f07659dfcc77f45a10169034e4c2 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 30 Jun 2023 14:02:17 -0400 Subject: [PATCH 16/19] Change link Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6040cfdd58..eb02980a0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,7 +126,7 @@ We greatly appreciate everyone who takes the time to make a contribution. We wil During the PR process, expect that there will be some back-and-forth. If you want to get your contribution merged quickly, try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. -We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README.md#style-linting). +We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](#style-linting). If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. From e4c2cc524d7e81be59866e62ceaf59ca868cc8c8 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Wed, 5 Jul 2023 10:35:01 -0400 Subject: [PATCH 17/19] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 44 ++++++++++++++++++++++---------------------- FORMATTING_GUIDE.md | 2 +- README.md | 14 +++++++------- 3 files changed, 30 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb02980a0a..358b173127 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,33 +16,33 @@ Thank you for your interest in improving the OpenSearch documentation! We value You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself. -NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on. We recommend starting with at any issue labeled `good first issue` if you're a beginner and `help wanted` if you're a more experienced user. +NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on. We recommend starting with any issue labeled "good first issue" if you're a beginner or "help wanted" if you're a more experienced user. ## Creating an issue -Use the documentation issue template to describe the change you'd like to make. +Use the documentation issue template to describe the change you'd like to make: 1. Go to https://github.com/opensearch-project/documentation-website/issues and select **New issue**. 1. Enter the requested information, including as much detail as possible, especially which version or versions the request affects. 1. Select **Submit new issue**. -The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. +The `untriaged` label is assigned automatically. During the triage process, the Documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. ## Contributing content -There are two ways to contribute content depending on the magnitude of the change: +There are two ways to contribute content, depending on the magnitude of the change: - [Minor changes](#making-minor-changes): For small changes to existing files, like fixing typos or adding parameters, you can edit files in GitHub directly. This approach does not require cloning the repository and does not allow you to test the documentation. -- [Major changes](#making-major-changes): For changes you want to test first, like adding new or reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and lets you test documentation. +- [Major changes](#making-major-changes): For changes you want to test first, like adding new or reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and allows you to test the documentation. ### Contribution workflow -The workflow for contributing documentation is no different than the one for contributing code: +The workflow for contributing documentation is the same as the one for contributing code: -- Make your changes -- Build the documentation website to check your work (only possible if you are making changes locally) -- Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR) -- Maintainers review and merge your PR +- Make your changes. +- Build the documentation website to check your work (only possible if you are making changes locally). +- Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR). +- A maintainer reviews and merges your PR. ### Before you start @@ -52,7 +52,7 @@ Before contributing content, make sure to read the following resources: - [API Style Guide](API_STYLE_GUIDE.md) - [Formatting Guide](FORMATTING_GUIDE.md) -NOTE: Make sure that any documentation you submit is your work or work that you have the rights to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) that states you have the rights to submit this work and you understand we'll use your contribution. +NOTE: Make sure that any documentation you submit is your own work or work that you have the right to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) stating that you have the right to submit your contribution and that you understand that we will use your contribution. ### Making minor changes @@ -68,7 +68,7 @@ If you want to make minor changes to an existing file, you can use this approach ### Making major changes -If you're adding new pages or making major changes to the documentation, such as adding new images, pages, sections, or styling, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a pull request. +If you're adding a new page or making major changes to the documentation, such as adding new images, sections, or styling, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a PR. #### Setting up your local copy of the repository @@ -78,7 +78,7 @@ Follow these steps to set up your local copy of the repository: 1. Navigate to your cloned repository. -1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer: +1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but you can use any method you prefer: ``` curl -sSL https://get.rvm.io | bash -s stable @@ -100,7 +100,7 @@ Follow these steps to set up your local copy of the repository: #### Making, viewing, and submitting changes -Here's how to build the website, make the changes, and view them locally: +Here's how to build the website, make changes, and view them locally: 1. Build the website: @@ -114,25 +114,25 @@ Here's how to build the website, make the changes, and view them locally: 1. Edit the Markdown files that you want to change. -1. When you save a file, Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds. +1. When you save a file, Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds. -1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request. +1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a PR. - Note that a pull request requires DCO sign-off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example `git commit -s -m 'This is my commit message'`. For more information, see https://github.com/apps/dco. + Note that a PR requires DCO sign-off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example, `git commit -s -m 'This is my commit message'`. For more information, see https://github.com/apps/dco. ## Review process -We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. +We greatly appreciate all contributions to the documentation and will review them as quickly as possible. -During the PR process, expect that there will be some back-and-forth. If you want to get your contribution merged quickly, try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. +During the PR process, expect that there will be some back-and-forth. If you want your contribution to be merged quickly, try to respond to comments in a timely fashion, and let us know if you don't want to continue with the PR. We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](#style-linting). -If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves. +If we accept the PR, we will merge it and will usually backport it to the appropriate branches. ### Style linting -To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) we use the [Vale](https://github.com/errata-ai/vale) linter. Addressing Vale comments on the PR expedites the review process. You can also install Vale locally as follows so you can address the comments before creating a PR: +To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md), we use the [Vale](https://github.com/errata-ai/vale) linter. Addressing Vale comments on the PR expedites the review process. You can also install Vale locally as follows so you can address the comments before creating a PR: 1. Run `brew install vale`. 2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`. @@ -141,4 +141,4 @@ Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla ## Getting help -For help with any step in the contributing process, please reach out to one of the [points of contact](README.md#points-of-contact). \ No newline at end of file +For help with the contribution process, reach out to one of the [points of contact](README.md#points-of-contact). \ No newline at end of file diff --git a/FORMATTING_GUIDE.md b/FORMATTING_GUIDE.md index f2ba41383f..827effdc5c 100644 --- a/FORMATTING_GUIDE.md +++ b/FORMATTING_GUIDE.md @@ -46,7 +46,7 @@ grand_parent: Supported field types --- ``` -If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, `grand_parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. +If you want to reorganize content or add a new page, keep an eye on `has_children`, `parent`, `grand_parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. When adding a page or a section, make the `nav_order` of the child pages multiples of 10. For example, if you have a parent page `Clients`, make child pages `Java`, `Python`, and `JavaScript` have a `nav_order` of 10, 20, and 30, respectively. Doing so makes inserting additional child pages easier because it does not require you to renumber existing pages. diff --git a/README.md b/README.md index 7dc265fd87..002015b4d3 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,14 @@ The documentation repository contains the documentation for OpenSearch, the high ## Contributing -Community contributions remain essential in keeping the documentation comprehensive, useful, well-organized, and up-to-date. If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](CONTRIBUTING.md). +Community contributions remain essential to keeping the documentation comprehensive, useful, well organized, and up to date. If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](CONTRIBUTING.md). -See these important resources when you are considering contributing to the documentation: +The following resources provide important guidance regarding contributions to the documentation: -- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) - The style guide covers the style standards to be observed when creating OpenSearch content. -- [Terms](TERMS.md) - The terms list contains the key OpenSearch terms and tips on how and when to use them. -- [API Style Guide](API_STYLE_GUIDE.md) - The API style guide provides the basic structure for creating OpenSearch API documentation. -- [Formatting Guide](FORMATTING_GUIDE.md) - The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. Use the formatting guide for an overview of the commonly used formatted elements and to learn how to add pages to the website. +- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md) -- The style guide covers the style standards to be observed when creating OpenSearch Project content. +- [OpenSearch terms](TERMS.md) -- The terms list contains key OpenSearch terms and tips on how and when to use them. +- [API Style Guide](API_STYLE_GUIDE.md) -- The API Style Guide provides the basic structure for creating OpenSearch API documentation. +- [Formatting Guide](FORMATTING_GUIDE.md) -- The OpenSearch documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme. The Formatting Guide provides an overview of the commonly used formatting elements and how to add a page to the website. ## Points of contact @@ -35,7 +35,7 @@ This project has adopted an [Open Source Code of Conduct](https://opensearch.org ## Security -If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Do **not** create a public GitHub issue. +If you discover a potential security issue in this project, we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Do **not** create a public GitHub issue. ## License From 2e98c2ade4d304a4ef8bf7fa79785c787bdd05c1 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 5 Jul 2023 10:47:48 -0400 Subject: [PATCH 18/19] Implemented editorial comments Signed-off-by: Fanit Kolchina --- CONTRIBUTING.md | 4 ++-- FORMATTING_GUIDE.md | 2 +- README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 358b173127..238c3b8bf5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ During the PR process, expect that there will be some back-and-forth. If you wan We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](#style-linting). -If we accept the PR, we will merge it and will usually backport it to the appropriate branches. +If we accept the PR, we will merge it and will backport it to the appropriate branches. ### Style linting @@ -137,7 +137,7 @@ To ensure that our documentation adheres to the [OpenSearch Project Style Guidel 1. Run `brew install vale`. 2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`. -Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension that integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. +Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension, which integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. ## Getting help diff --git a/FORMATTING_GUIDE.md b/FORMATTING_GUIDE.md index 827effdc5c..0dd8371450 100644 --- a/FORMATTING_GUIDE.md +++ b/FORMATTING_GUIDE.md @@ -46,7 +46,7 @@ grand_parent: Supported field types --- ``` -If you want to reorganize content or add a new page, keep an eye on `has_children`, `parent`, `grand_parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. +If you want to reorganize content or add a new page, make sure to set the appropriate `has_children`, `parent`, `grand_parent`, and `nav_order` variables, which define the hierarchy of pages in the left navigation. When adding a page or a section, make the `nav_order` of the child pages multiples of 10. For example, if you have a parent page `Clients`, make child pages `Java`, `Python`, and `JavaScript` have a `nav_order` of 10, 20, and 30, respectively. Doing so makes inserting additional child pages easier because it does not require you to renumber existing pages. diff --git a/README.md b/README.md index 002015b4d3..13dae8a5bd 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # About the OpenSearch documentation repo -The documentation repository contains the documentation for OpenSearch, the highly scalable and extensible open-source software suite for search, analytics, observability, and other data-intensive applications. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs). +The `documentation-website` repository contains the user documentation for OpenSearch. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs). ## Contributing From 0ede05113ad7ba5bc1755fde9a7c22e7f04dd5b8 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 6 Jul 2023 14:11:30 -0400 Subject: [PATCH 19/19] Update CONTRIBUTING.md Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 238c3b8bf5..3ae32dd834 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ Follow these steps to set up your local copy of the repository: ``` curl -sSL https://get.rvm.io | bash -s stable - rvm install 2.6 + rvm install 2.7 ruby -v ```