From 769607aeaee797ad52e56cd16dcff1107fcd5222 Mon Sep 17 00:00:00 2001 From: Umarov Ismoiljon Date: Thu, 28 Aug 2025 22:23:28 +0500 Subject: [PATCH 1/3] docs: Create a troubleshooting guide for CI checks (#12979) Signed-off-by: Umarov Ismoiljon --- .github/WORKFLOW_TROUBLESHOOTING.md | 45 +++++++++++++++++++++++++++++ CHANGELOG.md | 1 + 2 files changed, 46 insertions(+) create mode 100644 .github/WORKFLOW_TROUBLESHOOTING.md diff --git a/.github/WORKFLOW_TROUBLESHOOTING.md b/.github/WORKFLOW_TROUBLESHOOTING.md new file mode 100644 index 0000000000000..fcf30ee2ae106 --- /dev/null +++ b/.github/WORKFLOW_TROUBLESHOOTING.md @@ -0,0 +1,45 @@ +# Troubleshooting Pull Request Checks + +This guide helps contributors understand and fix common automated checks that fail on Pull Requests (PRs). When a check fails, a red '❌' will appear next to it. You must click the **"Details"** link next to any failed check to see the full error log. + +--- + +### 1. DCO (Developer Certificate of Origin) +This is a legal requirement. Your PR cannot be merged without it. + +* **What it is:** A check that verifies you have legally "signed off" on your commits. +* **Why it Fails:** The error log will mention a missing `Signed-off-by` line. This happens when you forget to use the `-s` flag in your commit command. +* **How to Fix It:** To fix your most recent commit, run `git commit --amend --signoff`. Then, you must update your PR by running `git push --force-with-lease`. + +--- + +### 2. Changelog Verifier +This is a very common failure for new contributors. + +* **What it is:** This check makes sure you have included a note about your change in the main `CHANGELOG.md` file. +* **Workflow File:** `.github/workflows/changelog-verifier.yml` +* **Why it Fails:** The error message is usually `Error: No update to CHANGELOG.md found!`. +* **How to Fix It:** + 1. Open the `CHANGELOG.md` file at the root of the project. + 2. Find the `## [Unreleased]` section at the top. + 3. Under the correct category (e.g., `### Fixed`, `### Added`), add a new line describing your change. For example: ` - Created a troubleshooting guide for CI checks. See #12979.` + +--- + +### 3. Gradle Check +This is the largest and most complex check. Be patient when this one fails. + +* **What it is:** It builds the entire OpenSearch project and runs thousands of automated tests. +* **Workflow File:** `.github/workflows/gradle-check.yml` +* **Why it Fails:** The error is usually a generic `Process completed with exit code 1`. This can be caused by a bug in your code, a broken test, or a "flaky test" in the system that fails randomly. +* **How to Fix It:** Click the **"Details"** link to open the full log. Scroll to the bottom of the log to find the specific Java test that failed or the error that caused the crash. The fix depends entirely on that specific error message. If you believe the failure is unrelated to your changes, you can try closing and reopening your PR to re-run the checks. + +--- + +### 4. Backport +You may see this check fail if your change is marked for older versions. + +* **What it is:** An automated process that tries to copy your change to older release branches of the project. +* **Workflow File:** `.github/workflows/backport.yml` +* **Why it Fails:** It often fails if your code has conflicts with the older codebase. +* **How to Fix It:** Usually, a project maintainer will handle backport failures. If this check fails on your PR, you can often leave a comment asking for help, but it's best to ensure your primary PR for the `main` branch is passing all other checks first. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 9565af89cd65c..82c24d6fe3675 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Use S3CrtClient for higher throughput while uploading files to S3 ([#18800](https://github.com/opensearch-project/OpenSearch/pull/18800)) - Add a dynamic setting to change skip_cache_factor and min_frequency for querycache ([#18351](https://github.com/opensearch-project/OpenSearch/issues/18351)) - Add overload constructor for Translog to accept Channel Factory as a parameter ([#18918](https://github.com/opensearch-project/OpenSearch/pull/18918)) +- Add a troubleshooting guide for CI/CD checks to help new contributors ([#12979](https://github.com/opensearch-project/OpenSearch/issues/12979)) ### Changed - Add CompletionStage variants to methods in the Client Interface and default to ActionListener impl ([#18998](https://github.com/opensearch-project/OpenSearch/pull/18998)) From 50674f3a06eaf426c6c7d7238d6b708cfe33b0a6 Mon Sep 17 00:00:00 2001 From: Umarov Ismoiljon Date: Fri, 29 Aug 2025 11:16:16 +0500 Subject: [PATCH 2/3] ci(changelog): Improve failure message for changelog verifier Signed-off-by: Umarov Ismoiljon --- .github/WORKFLOW_TROUBLESHOOTING.md | 45 ------------------------ .github/workflows/changelog_verifier.yml | 5 +++ CHANGELOG.md | 1 - 3 files changed, 5 insertions(+), 46 deletions(-) delete mode 100644 .github/WORKFLOW_TROUBLESHOOTING.md diff --git a/.github/WORKFLOW_TROUBLESHOOTING.md b/.github/WORKFLOW_TROUBLESHOOTING.md deleted file mode 100644 index fcf30ee2ae106..0000000000000 --- a/.github/WORKFLOW_TROUBLESHOOTING.md +++ /dev/null @@ -1,45 +0,0 @@ -# Troubleshooting Pull Request Checks - -This guide helps contributors understand and fix common automated checks that fail on Pull Requests (PRs). When a check fails, a red '❌' will appear next to it. You must click the **"Details"** link next to any failed check to see the full error log. - ---- - -### 1. DCO (Developer Certificate of Origin) -This is a legal requirement. Your PR cannot be merged without it. - -* **What it is:** A check that verifies you have legally "signed off" on your commits. -* **Why it Fails:** The error log will mention a missing `Signed-off-by` line. This happens when you forget to use the `-s` flag in your commit command. -* **How to Fix It:** To fix your most recent commit, run `git commit --amend --signoff`. Then, you must update your PR by running `git push --force-with-lease`. - ---- - -### 2. Changelog Verifier -This is a very common failure for new contributors. - -* **What it is:** This check makes sure you have included a note about your change in the main `CHANGELOG.md` file. -* **Workflow File:** `.github/workflows/changelog-verifier.yml` -* **Why it Fails:** The error message is usually `Error: No update to CHANGELOG.md found!`. -* **How to Fix It:** - 1. Open the `CHANGELOG.md` file at the root of the project. - 2. Find the `## [Unreleased]` section at the top. - 3. Under the correct category (e.g., `### Fixed`, `### Added`), add a new line describing your change. For example: ` - Created a troubleshooting guide for CI checks. See #12979.` - ---- - -### 3. Gradle Check -This is the largest and most complex check. Be patient when this one fails. - -* **What it is:** It builds the entire OpenSearch project and runs thousands of automated tests. -* **Workflow File:** `.github/workflows/gradle-check.yml` -* **Why it Fails:** The error is usually a generic `Process completed with exit code 1`. This can be caused by a bug in your code, a broken test, or a "flaky test" in the system that fails randomly. -* **How to Fix It:** Click the **"Details"** link to open the full log. Scroll to the bottom of the log to find the specific Java test that failed or the error that caused the crash. The fix depends entirely on that specific error message. If you believe the failure is unrelated to your changes, you can try closing and reopening your PR to re-run the checks. - ---- - -### 4. Backport -You may see this check fail if your change is marked for older versions. - -* **What it is:** An automated process that tries to copy your change to older release branches of the project. -* **Workflow File:** `.github/workflows/backport.yml` -* **Why it Fails:** It often fails if your code has conflicts with the older codebase. -* **How to Fix It:** Usually, a project maintainer will handle backport failures. If this check fails on your PR, you can often leave a comment asking for help, but it's best to ensure your primary PR for the `main` branch is passing all other checks first. \ No newline at end of file diff --git a/.github/workflows/changelog_verifier.yml b/.github/workflows/changelog_verifier.yml index 1d89b45f7e9e0..06d311800ff89 100644 --- a/.github/workflows/changelog_verifier.yml +++ b/.github/workflows/changelog_verifier.yml @@ -16,3 +16,8 @@ jobs: - uses: dangoslen/changelog-enforcer@v3 with: skipLabels: "autocut, skip-changelog" + changeIsMissingMessage: | + ❌ ERROR: No update to CHANGELOG.md found! + This project requires a changelog entry for every user-facing change. + Please add a note about your change to the 'Unreleased' section of the CHANGELOG.md file. + You can find the file here: https://github.com/opensearch-project/OpenSearch/blob/main/CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 82c24d6fe3675..9565af89cd65c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Use S3CrtClient for higher throughput while uploading files to S3 ([#18800](https://github.com/opensearch-project/OpenSearch/pull/18800)) - Add a dynamic setting to change skip_cache_factor and min_frequency for querycache ([#18351](https://github.com/opensearch-project/OpenSearch/issues/18351)) - Add overload constructor for Translog to accept Channel Factory as a parameter ([#18918](https://github.com/opensearch-project/OpenSearch/pull/18918)) -- Add a troubleshooting guide for CI/CD checks to help new contributors ([#12979](https://github.com/opensearch-project/OpenSearch/issues/12979)) ### Changed - Add CompletionStage variants to methods in the Client Interface and default to ActionListener impl ([#18998](https://github.com/opensearch-project/OpenSearch/pull/18998)) From 902ab5a2d2d5ce1afcf23c54cc38ec949d8a6be3 Mon Sep 17 00:00:00 2001 From: Umarov Ismoiljon Date: Sat, 6 Sep 2025 17:38:47 +0500 Subject: [PATCH 3/3] Update .github/workflows/changelog_verifier.yml Co-authored-by: Andrew Ross Signed-off-by: Umarov Ismoiljon --- .github/workflows/changelog_verifier.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/changelog_verifier.yml b/.github/workflows/changelog_verifier.yml index 06d311800ff89..d6d0c7a47f731 100644 --- a/.github/workflows/changelog_verifier.yml +++ b/.github/workflows/changelog_verifier.yml @@ -19,5 +19,5 @@ jobs: changeIsMissingMessage: | ❌ ERROR: No update to CHANGELOG.md found! This project requires a changelog entry for every user-facing change. - Please add a note about your change to the 'Unreleased' section of the CHANGELOG.md file. - You can find the file here: https://github.com/opensearch-project/OpenSearch/blob/main/CHANGELOG.md + Please add an entry to the changelog or ask a maintainer to add the skip-changelog label. + See https://github.com/opensearch-project/OpenSearch/blob/main/CONTRIBUTING.md#changelog for more details.