diff --git a/BACKPORT.md b/BACKPORT.md deleted file mode 100644 index f922fdf..0000000 --- a/BACKPORT.md +++ /dev/null @@ -1,39 +0,0 @@ -- [Managing Backports in OpenSearch Plugins](#managing-backports-in-opensearch-plugins) - - [Features](#features) - - [Integration](#integration) - - [Usage](#usage) - -## Managing Backports in OpenSearch Plugins - -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--to-`. 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 `. (`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](./LABELS.md) 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. \ No newline at end of file diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 58ead67..5b721ba 100644 --- a/CONVENTIONS.md +++ b/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 diff --git a/HEADERS.md b/HEADERS.md index ea8af82..fa66ab2 100644 --- a/HEADERS.md +++ b/HEADERS.md @@ -1,6 +1,7 @@ - [Headers](#headers) - - [License Headers](#license-headers) + - [License Headers](#license-headers) + - [Automated License Headers' Checks](#automated-license-headers-checks) ## Headers diff --git a/LABELS.md b/LABELS.md deleted file mode 100644 index ece5f64..0000000 --- a/LABELS.md +++ /dev/null @@ -1,12 +0,0 @@ -- [Labeling PRs](#labeling-prs) - - [Integration](#integration) - -# Labeling PRs - -Many of the automated workflows to generate [release notes](./RELEASE_NOTES.md) or [backport PRs](./BACKPORT.md) 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](./BACKPORT.md) 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)). \ No newline at end of file diff --git a/MAINTAINERS.md b/MAINTAINERS.md index e7b960f..6ae2efb 100644 --- a/MAINTAINERS.md +++ b/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). \ No newline at end of file +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). \ No newline at end of file diff --git a/README.md b/README.md index 055082a..74fe224 100644 --- a/README.md +++ b/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). diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index ccf39d2..401ca01 100644 --- a/RELEASE_NOTES.md +++ b/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). \ No newline at end of file +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). \ No newline at end of file diff --git a/WORKFLOWS.md b/WORKFLOWS.md new file mode 100644 index 0000000..67706d7 --- /dev/null +++ b/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--to-`. 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 `. (`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. \ No newline at end of file