Skip to content

Propagate 10207 to 1.2 #10240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 11, 2025
Merged

Propagate 10207 to 1.2 #10240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
# This should match the owning team set up in https://github.com/orgs/opensearch-project/teams
* @opensearch-project/docs
* @kolchfa-aws @AMoo-Miki @natebower @dlvenable @epugh @sumobrian
23 changes: 23 additions & 0 deletions MAINTAINERS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## Overview

This document lists the maintainers in this repo. See [opensearch-project/.github/RESPONSIBILITIES.md](https://github.com/opensearch-project/.github/blob/main/RESPONSIBILITIES.md#maintainer-responsibilities) for information about the role of a maintainer, what maintainers do in this and other repos, and how they should be doing it. If you're interested in contributing or becoming a maintainer, see [CONTRIBUTING](CONTRIBUTING.md).

## Current Maintainers

| Maintainer | GitHub ID | Affiliation |
| ---------------- | ----------------------------------------------- | ----------- |
| Fanit Kolchina | [kolchfa-aws](https://github.com/kolchfa-aws) | Amazon |
| Nathan Bower | [natebower](https://github.com/natebower) | Amazon |
| Miki Barahmand | [AMoo-Miki](https://github.com/AMoo-Miki) | Amazon |
| David Venable | [dlvenable](https://github.com/dlvenable) | Amazon |
| Brian Presley | [sumobrian](https://github.com/sumobrian/) | Amazon |
| Eric Pugh | [epugh](https://github.com/epugh) | OpenSource Connections |

## Emeritus

| Maintainer | GitHub ID | Affiliation |
| ---------------- | ------------------------------------------------------- | ----------- |
| Heather Halter | [hdhalter](https://github.com/hdhalter) | Amazon |
| Melissa Vagi | [vagimeli](https://github.com/vagimeli) | Amazon |
| Stephen Crawford | [stephen-crawford](https://github.com/stephen-crawford) | Amazon |
| Nate Archer | [Naarcha-AWS](https://github.com/Naarcha-AWS) | Amazon |
251 changes: 1 addition & 250 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,256 +26,7 @@ Community contributions remain essential in keeping this documentation comprehen

If you encounter problems or have questions when contributing to the documentation, these people can help:

- [keithhc2](https://github.com/keithhc2)
- [Naarcha-AWS](https://github.com/Naarcha-AWS)
- [lizsnyder](https://github.com/lizsnyder)


## How the website works

This repository contains many [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're making [trivial changes](#trivial-changes), you don't have to worry about front matter.

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 three ways to contribute content, depending on the magnitude of the change.

- [Trivial changes](#trivial-changes)
- [Minor changes](#minor-changes)
- [Major changes](#major-changes)


### Trivial changes

If you just need to fix a typo or add a sentence, this web-based method works well:

1. On any page in the documentation, click the **Edit this page** link in the lower-left.

1. Make your changes.

1. Sign off on the commit by including the text "Signed-off by: <GitHub Username> <your-email-here>" in the optional description. Be sure to use an email that's added to your GitHub account.

1. Choose **Create a new branch for this commit and start a pull request** and **Commit changes**.


### 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 build 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-plugin/`).

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

1. Try to stay consistent with existing content and consistent within your new content. Don't call the same plugin KNN, k-nn, and k-NN in three different places.

1. Shorter paragraphs are better than longer paragraphs. Use headers, tables, lists, and images to make your content easier for readers to scan.

1. Use **bold** for user interface elements, *italics* for key terms or emphasis, and `monospace` for Bash commands, file names, REST paths, and code.

1. Markdown file names should be all lowercase, use hyphens to separate words, and end in `.md`.

1. Avoid future tense. Use present tense.

**Bad**: After you click the button, the process will start.

**Better**: After you click the button, the process starts.

1. "You" refers to the person reading the page. "We" refers to the OpenSearch contributors.

**Bad**: Now that we've finished the configuration, we have a working cluster.

**Better**: At this point, you have a working cluster, but we recommend adding dedicated master nodes.

1. Don't use "this" and "that" to refer to something without adding a noun.

**Bad**: This can cause high latencies.

**Better**: This additional loading time can cause high latencies.

1. Use active voice.

**Bad**: After the request is sent, the data is added to the index.

**Better**: After you send the request, the OpenSearch cluster indexes the data.

1. Introduce acronyms before using them.

**Bad**: Reducing customer TTV should accelerate our ROIC.

**Better**: Reducing customer time to value (TTV) should accelerate our return on invested capital (ROIC).

1. Spell out one through nine. Start using numerals at 10. If a number needs a unit (GB, pounds, millimeters, kg, celsius, etc.), use numerals, even if the number if smaller than 10.

**Bad**: 3 kids looked for thirteen files on a six GB hard drive.

**Better**: Three kids looked for 13 files on a 6 GB hard drive.


## New releases

1. Branch.
1. Change the `opensearch_version`, `opensearch_major_minor_version`, and `lucene_version` variables in `_config.yml`.
1. Start up a new cluster using the updated Docker Compose file in `docs/install/docker.md`.
1. Update the version table in `version-history.md`.

Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch and Lucene versions.

1. Update the plugin compatibility table in `_opensearch/install/plugin.md`.

Use `curl -XGET https://localhost:9200/_cat/plugins -u admin:admin -k` to get the correct version strings.

1. Update the plugin compatibility table in `_dashboards/install/plugins.md`.

Use `docker ps` to find the ID for the OpenSearch Dashboards node. Then use `docker exec -it <opensearch-dashboards-node-id> /bin/bash` to get shell access. Finally, run `./bin/opensearch-dashboards-plugin list` to get the plugins and version strings.

1. Run a build (`build.sh`), and look for any warnings or errors you introduced.
1. Verify that the individual plugin download links in `docs/install/plugins.md` and `docs/opensearch-dashboards/plugins.md` work.
1. Check for any other bad links (`check-links.sh`). Expect a few false positives for the `localhost` links.
1. Submit a PR.


## Classes within Markdown

This documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme, which has some useful classes for labels and buttons:

```
[Get started](#get-started){: .btn .btn-blue }

## Get started
New
{: .label .label-green }
```

* Labels come in default (blue), green, purple, yellow, and red.
* Buttons come in default, purple, blue, green, and outline.
* Warning, tip, and note blocks are available (`{: .warning }`, etc.).
* If an image has a white background, you can use `{: .img-border }` to add a one pixel border to the image.

These classes can help with readability, but should be used *sparingly*. Each addition of a class damages the portability of the Markdown files and makes moving to a different Jekyll theme (or a different static site generator) more difficult.

Besides, standard Markdown elements suffice for most documentation.


## Labels for APIs

Each API operation has a label indicating when it was introduced. For most operations, this label is 1.0:

```
## Get roles
Introduced 1.0
{: .label .label-purple }
```

If we introduce a breaking change to an operation, add an additional label with a link to the release note for that breaking change:

```
## Get roles
Introduced 1.0
{: .label .label-purple }
[Last breaking change 2.0](https://example.com)
{: .label .label-red }
```


## Math

If you want to use the sorts of pretty formulas that [MathJax](https://www.mathjax.org) allows, add `has_math: true` to the Jekyll page metadata. Then insert LaTeX math into HTML tags with the rest of your Markdown content:

```
## Math

Some Markdown paragraph. Here's a formula:

<p>
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
</p>

And back to Markdown.
```
- [kolchfa-aws](https://github.com/kolchfa-aws)


## Code of conduct
Expand Down
Loading