Adding documentation for auto create issue workflow

CONVENTIONS.md

@@ -1,22 +1,22 @@
 - [Plugin Naming Conventions](#plugin-naming-conventions)
-    - [GitHub](#github)
-        - [OpenSearch Plugins](#opensearch-plugins)
-        - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
-    - [Metadata](#metadata)
-        - [OpenSearch Plugins](#opensearch-plugins)
-        - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
-    - [Artifacts](#artifacts)
-        - [OpenSearch Plugins](#opensearch-plugins)
-        - [OpenSearch Dashboards Plugins](#opensearch-dashboards-plugins)
-    - [Folders](#folders)
-        - [OpenSearch Plugins](#opensearch-plugins)
-        - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
-    - [Classes](#classes)
-    - [Settings](#settings)
-    - [APIs](#apis)
-    - [Indices](#indices)
-    - [Identifiers](#identifiers)
-    - [Variables](#variables)
+  - [GitHub](#github)
+    - [OpenSearch Plugins](#opensearch-plugins)
+    - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
+  - [Metadata](#metadata)
+    - [OpenSearch Plugins](#opensearch-plugins-1)
+    - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins-1)
+  - [Artifacts](#artifacts)
+    - [OpenSearch Plugins](#opensearch-plugins-2)
+    - [OpenSearch Dashboards Plugins](#opensearch-dashboards-plugins)
+  - [Folders](#folders)
+    - [OpenSearch Plugins](#opensearch-plugins-3)
+    - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins-2)
+  - [Classes](#classes)
+  - [Settings](#settings)
+  - [APIs](#apis)
+  - [Indices](#indices)
+  - [Identifiers](#identifiers)
+  - [Variables](#variables)
 
 ## Plugin Naming Conventions
 

HEADERS.md

@@ -1,6 +1,7 @@
 <!-- TOC -->
 - [Headers](#headers)
-    - [License Headers](#license-headers)
+  - [License Headers](#license-headers)
+  - [Automated License Headers' Checks](#automated-license-headers-checks)
 <!-- TOC -->
 ## Headers
 

MAINTAINERS.md

@@ -12,4 +12,4 @@
 
 ### Backports
 
-After a PR is merged, maintainers can backport this PR to appropriate release branches if applicable. To automatically backport PRs, please see [BACKPORT](BACKPORT.md).
+After a PR is merged, maintainers can backport this PR to appropriate release branches if applicable. To automatically backport PRs, please see [BACKPORT](WORKFLOWS.md#managing-backports).

README.md

@@ -7,11 +7,13 @@
   - [Upgrading Plugins to work with OpenSearch](#upgrading-plugins-to-work-with-opensearch)
   - [Installing Plugins](#installing-plugins)
   - [Developing Plugins for OpenSearch](#developing-plugins-for-opensearch)
+  - [Workflows](#workflows)
   - [Plugin Release Notes](#plugin-release-notes)
   - [Headers](#headers)
   - [Standards](#standards)
 - [Contributing](#contributing)
 - [License](#license)
+- [Copyright](#copyright)
 
 ## OpenSearch Plugins
 
@@ -43,6 +45,10 @@ See [INSTALLING](INSTALLING.md) for details.
 
 See [DEVELOPING_PLUGINS](BUILDING.md#developing-new-plugins-for-opensearch) for details.
 
+### Workflows
+
+See [WORKFLOWS](WORKFLOWS.md) for useful workflows that can be added.
+
 ### Plugin Release Notes
 
 Plugins generally use a standard format for release notes, see [RELEASE_NOTES](./RELEASE_NOTES.md).

RELEASE_NOTES.md

@@ -110,4 +110,4 @@ _Correct:_ `* Fix the out of memory issue ([#456](http:/#456))`
 
 Create a GitHub Actions workflow to help draft release notes. See [.github/workflows/draft-release-notes.yml](.github/workflows/draft-release-notes.yml) for an example. This workflow is configured using [.github/draft-release-notes-config.yml](.github/draft-release-notes-config.yml).
 
-See [release-drafter](https://github.com/release-drafter/release-drafter) for more information. Note that this GitHub action utilizes labels on PRs. For more information on automating labels, see the [auto-labeling workflow](./LABELS.md).
+See [release-drafter](https://github.com/release-drafter/release-drafter) for more information. Note that this GitHub action utilizes labels on PRs. For more information on automating labels, see the [auto-labeling workflow](./WORKFLOWS.md#labeling-prs).

WORKFLOWS.md

@@ -0,0 +1,70 @@
+- [Workflows](#workflows)
+  - [Managing Backports](#managing-backports)
+    - [Features](#features)
+    - [Integration](#integration)
+    - [Usage](#usage)
+  - [Labeling PRs](#labeling-prs)
+    - [Integration](#integration-1)
+  - [Auto Create Documentation Issues](#auto-create-documentation-issues)
+    - [Integration](#integration-2)
+
+# Workflows
+
+This document lists down useful workflows that can be added to repositories to alleviate manual processes.
+
+## Managing Backports
+
+Backporting a PR/commit to a release branch is a manual process and can lead to missed backports before a release. The auto backport Github Action allows to create automatic backport PRs just by labelling them.
+
+### Features
+
+When the auto backport workflow is integrated with a repo, the following features are available:
+
+1. Allows auto backports on PRs that are merged and labelled (can be in any order). To backport a PR to 1.x, please add a label called `backport 1.x` to the PR and the backport workflow will do the rest.
+2. The backport workflow is now created by a Github App called `opensearch-trigger-bot` instead of `github-actions` which allows CI to run on such PRs.
+3. The backport branches are named in the form `backport/backport-<original PR number>-to-<base>`. These branches will be cleaned up by an auto delete workflow once the backport PR is merged.
+
+### Integration
+
+Integrating the backport workflow is easy and can be done with the following steps:
+
+1. Add the [backport](https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/backport.yml) workflow in your repo.
+2. Add secrets in your repo for the Github App ID and Private key. This is used to generate a token for the Github App `opensearch-trigger-bot`. Using this token helps generate the automatic backport PR from the app token so that all the CI triggers work on the PR. ([OpenSearch#2071](https://github.com/opensearch-project/OpenSearch/pull/2071))
+3. Add [auto delete](https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/delete_backport_branch.yml) workflow for deleting the backport branches once the backport PRs are merged. This enables the backport workflow to clean up after itself.
+4. Backport this auto delete workflow to release branches so the backport branches created against the release branches can be auto deleted.
+5. Add appropriate branch permissions for backport related branches in your repo.
+6. Add related labels for release branches. For auto-backports, the labels should be of the form `backport <release-branch-name>`. (`backport 1.x`, `backport 1.2` etc.)
+
+### Usage
+
+To use the auto backport workflow:
+
+1. Label the original PR according to the release-branch. For example, to backport to 1.x, please add a label `backport 1.x`. You can add multiple backport labels to different release branches. Labels can be added in any order: meaning before or after the PR is merged. Note that there is an [auto-labeling](#labeling-prs) action that can be configured to help automate this process.
+2. Once the label is added and the original PR is in a merged state, the auto backport workflow will create backport PR if there are no merge conflicts using `opensearch-trigger-bot`. If there are merge conflicts, it will comment on the original PR on the steps to take.
+3. Once the backport PR is merged, the branch created for backport will be auto-deleted.
+
+An example of auto backport:
+- Original PR: https://github.com/opensearch-project/OpenSearch/pull/2094 with label `backport 1.x`.
+- Backport PR: https://github.com/opensearch-project/OpenSearch/pull/2106 with merged backport branch auto deleted.
+
+
+## Labeling PRs
+
+Many of the automated workflows to generate [release notes](./RELEASE_NOTES.md) or [backport PRs](#managing-backports) require labels on the PRs to correctly categorize them and perform the right actions. To eliminate having to do this manually, there is an [auto-labeling GitHub action](https://github.com/actions/labeler), which allows for automatically labeling opened PRs based on the files that the PR changes.
+
+### Integration
+
+1. Integrate the `opensearch-trigger-bot` in your repository, if not done already. This requires adding some GitHub secrets. See the [backport documentation](#managing-backports) for details.
+2. Add a labeling config `.github/labeler.yml` ([example](https://github.com/actions/labeler#common-examples)) to your repository. This is where labels can be defined, along with their associated glob patterns, such that if any matching files are changed in a PR, that label will be applied.
+3. Add a GitHub workflow `.github/workflows/labeler.yml` ([example](https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/blob/main/.github/workflows/labeler.yml)) to your repository, to utilize the configuration. Note this uses permissions provided from the `opensearch-trigger-bot` instead of the default `github-actions`, due to security limitations regarding forked repository pull requests (details on the limitations [here](https://github.com/actions/first-interaction/issues/10)).
+
+
+## Auto Create Documentation Issues
+
+When new features are introduced or changes are added that need to be documented, developers have to remember to create issues in the [`documentation-website`](https://github.com/opensearch-project/documentation-website) in order to document the changes. This is a manual process. To eliminate this manual process, there is a [create-documentation-issue](https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/create-documentation-issue.yml) workflow which can be added to automatically create issues in the `documentation-website` repo by adding a label `needs-documentation` to the pull request.
+
+### Integration
+
+1. Integrate the `opensearch-trigger-bot` in your repository, if not done already. This requires adding some GitHub secrets. See the [backport documentation](#managing-backports) for details.
+2. Add an issue template `.ci/documentation/issue.md` ([example](https://github.com/opensearch-project/OpenSearch/blob/main/.ci/documentation/issue.md)) to your repository. This markdown file defines the template that will be used to create issues in the documentation-website repo.
+3. Add a GitHub workflow `.github/workflows/create-documentation-issue.yml` ([example](https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/create-documentation-issue.yml)) to your repository, this workflow gets triggered when a label `needs-documentation` is added to a pull request. It creates an issue with the title and issue template provided to the workflow.