iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrite Contributing and readme (#4416) 

* Rewrite Contributing and readme

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Changes to the structure

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update CONTRIBUTING.md

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Reordered sections

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Apply suggestions from code review

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Doc review changes

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update CONTRIBUTING.md

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Update CONTRIBUTING.md

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* added list of resources

Signed-off-by: Heather Halter <hdhalter@amazon.com>

* Moved front matter section to formatting guide and linting to contributing

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Apply suggestions from code review

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* 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>

* Add doc review comments

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Delete word

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Minor rewording

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Change link

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Implemented editorial comments

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update CONTRIBUTING.md

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Signed-off-by: Heather Halter <hdhalter@amazon.com>
Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>
This commit is contained in:
kolchfa-aws 2023-07-19 12:36:37 -04:00 committed by GitHub
parent 9b386b3d47
commit 5f8ddb8060
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 145 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
CONTRIBUTING.md
View File

@ -1,60 +1,144 @@
# Contributing Guidelines
- [Creating an issue](#creating-an-issue)
- [Contributing content](#contributing-content)
- [Contribution workflow](#contribution-workflow)
- [Before you start](#before-you-start)
- [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)
- [Style linting](#style-linting)
- [Getting help](#getting-help)
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.
# Contributing guidelines
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.
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.
## How to request changes
You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself.
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.
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.
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.
## Creating an issue
**Create an Issue**
Use the documentation issue template 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**.
1. Enter the requested information, including as much detail as possible, especially which version or versions the request affects.
1. Select **Submit new issue**.
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.
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.
## Contributing content
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.
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 allows you to test the documentation.
**Create a pull request**
### Contribution workflow
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 the same as 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 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 submitting, make sure to:
### Before you start
* 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 contributing content, make sure to read the following resources:
- [README](README.md)
- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md)
- [API Style Guide](API_STYLE_GUIDE.md)
- [Formatting Guide](FORMATTING_GUIDE.md)
To create a pull request:
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.
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.
### Making minor changes
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 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).
## Finding contributions to work on
1. In your fork on GitHub, navigate to the file that you want to change.
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.
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**.
## Security issue notifications
### Making major changes
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.
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
## Licensing
Follow these steps to set up your local copy of the repository:
See the [LICENSE](LICENSE) file for our project's licensing.
1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork.
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 you can use any method you prefer:
```
curl -sSL https://get.rvm.io | bash -s stable
rvm install 2.7
ruby -v
```
1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it:
```
gem install bundler jekyll
```
1. Install the Jekyll dependencies:
```
bundle install
```
#### Making, viewing, and submitting changes
Here's how to build the website, make changes, and view them locally:
1. Build the website:
```
sh build.sh
```
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.
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'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 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 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 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 it and will 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:
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, 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
For help with the contribution process, reach out to one of the [points of contact](README.md#points-of-contact).

17
FORMATTING_GUIDE.md
View File

@ -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 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.
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.

139
README.md
View File

@ -2,12 +2,19 @@
# 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-website` repository contains the user documentation for OpenSearch. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs).
## How you can help
## Contributing
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.
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).
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 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
@ -21,128 +28,6 @@ If you encounter problems or have questions when contributing to the documentati
- [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.
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:
```
---
layout: default
title: Alerting security
nav_order: 10
parent: Alerting
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.
### 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`.
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.
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.
## 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.
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).
## 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).
## 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:
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.
## Code of conduct
This project has adopted an [Open Source Code of Conduct](https://opensearch.org/codeofconduct.html).
@ -150,12 +35,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/). 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