From fbc36ad370edc4d5b4aa5996eb0b3a6e6c35d87c Mon Sep 17 00:00:00 2001 From: Vacha Shah Date: Thu, 21 Apr 2022 14:59:24 -0700 Subject: [PATCH 1/3] Adding documentation for auto create issue workflow Signed-off-by: Vacha Shah --- DOCUMENTATION.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 DOCUMENTATION.md diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..c9060e4 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,12 @@ +- [Auto Create Documentation Issues](#auto-create-documentation-issues) + - [Integration](#integration) + +# 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](./BACKPORT.md) 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 From 34d25da9f0eec8d72d5775755bb567cc52d52c0b Mon Sep 17 00:00:00 2001 From: Vacha Shah Date: Fri, 22 Apr 2022 12:00:24 -0700 Subject: [PATCH 2/3] Combining workflow documentation Signed-off-by: Vacha Shah --- BACKPORT.md | 39 --------------------------- CONVENTIONS.md | 36 ++++++++++++------------- DOCUMENTATION.md | 12 --------- HEADERS.md | 3 ++- LABELS.md | 12 --------- MAINTAINERS.md | 2 +- README.md | 6 +++++ WORKFLOWS.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 97 insertions(+), 83 deletions(-) delete mode 100644 BACKPORT.md delete mode 100644 DOCUMENTATION.md delete mode 100644 LABELS.md create mode 100644 WORKFLOWS.md 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/DOCUMENTATION.md b/DOCUMENTATION.md deleted file mode 100644 index c9060e4..0000000 --- a/DOCUMENTATION.md +++ /dev/null @@ -1,12 +0,0 @@ -- [Auto Create Documentation Issues](#auto-create-documentation-issues) - - [Integration](#integration) - -# 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](./BACKPORT.md) 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 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/WORKFLOWS.md b/WORKFLOWS.md new file mode 100644 index 0000000..b7f6912 --- /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](./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. + + +## 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 From adea1526fc688fd4b68835e3f2715ef54dceaada Mon Sep 17 00:00:00 2001 From: Vacha Shah Date: Fri, 22 Apr 2022 12:13:08 -0700 Subject: [PATCH 3/3] Fixing links Signed-off-by: Vacha Shah --- RELEASE_NOTES.md | 2 +- WORKFLOWS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index b7f6912..67706d7 100644 --- a/WORKFLOWS.md +++ b/WORKFLOWS.md @@ -39,7 +39,7 @@ Integrating the backport workflow is easy and can be done with the following ste 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. +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.