From 7e603f8c78e83204e4183107275ea0fd6eee74cc Mon Sep 17 00:00:00 2001 From: Bill Easton Date: Thu, 12 Feb 2026 07:54:22 -0600 Subject: [PATCH 1/6] Update CONTRIBUTING.md to reference Publish an Integration is for PR Creation --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba067e229a2..0e73434bd39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,3 +8,5 @@ Ready to dive into the world of integrations? See the [Integrations Developer Gu * [Test an integration](https://www.elastic.co/guide/en/integrations-developer/current/testing.html) * [Publish an integration](https://www.elastic.co/guide/en/integrations-developer/current/_publish_an_integration.html) * [Developer workflows](https://www.elastic.co/guide/en/integrations-developer/current/developer-workflows.html) + +To improve your chances of getting your Pull Request merged, ensure you follow all of the steps outlined in [Publish an integration](https://www.elastic.co/guide/en/integrations-developer/current/_publish_an_integration.html) prior to making your Pull Request. From a86d256eebddc75f900937c07f66893148b9e960 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 12 Feb 2026 14:11:11 +0000 Subject: [PATCH 2/6] Add pre-submission checklist items to publish docs Adds concise guidelines for: - Running pre-submission checks (elastic-package check/format) - Changelog requirements (link field, types) - CODEOWNERS updates for new integrations - Test coverage (elastic-package test, sample_event.json) - Version bumping guidance - Breaking changes documentation - Ingest pipeline error handling - PR title and description best practices Co-Authored-By: Bill Easton --- docs/extend/_publish_an_integration.md | 33 +++++++++++++++----------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/extend/_publish_an_integration.md b/docs/extend/_publish_an_integration.md index c66ff990884..7cdc0f97b9d 100644 --- a/docs/extend/_publish_an_integration.md +++ b/docs/extend/_publish_an_integration.md @@ -8,24 +8,29 @@ mapped_pages: When your integration is done, it’s time to open a PR to include it in the integrations repository. Before opening your PR, make sure you have: -1. Pass all checks -Run: -```bash -elastic-package check -``` +1. **Run pre-submission checks** +Run `elastic-package check` to validate formatting, build, and linting. Run `elastic-package format` if files need reformatting. -This command validates that your package is built correctly, formatted properly, and aligned with the specification. Passing this `check` is required before submitting your integration. +2. **Add a changelog entry** +Include a `link:` field pointing to your PR. Use the correct type: `enhancement`, `bug-fix`, `breaking-change`, or `deprecation`. -2. Added a new entry into `changelog.yml` -Update the package’s `changelog.yml` with a clear description of your changes for the new version. +3. **Update CODEOWNERS** (new integrations only) +Add your package to `.github/CODEOWNERS` with the format: `packages/ @elastic/`. -3. Bumped the package version -If you are releasing new changes, increment the version in your manifest.yml file. This is required for the package to be published. +4. **Include test coverage** +Run `elastic-package test` before submitting. Generate `sample_event.json` using `elastic-package test system --generate`. -4. Wrote clear PR title and description -- Use a concise, descriptive title (e.g., `[New Integration] Add Acme Logs integration`). -- In the PR description, summarize what your integration or change does, list key features or fixes, reference related issues, and provide testing instructions. -- Ensure your documentation, sample events, and tests are included and up to date. +5. **Bump the package version appropriately** +Use minor version bumps for documentation-only changes and patch bumps for small fixes. + +6. **Document breaking changes** +Use `breaking-change` type in changelog and clearly describe impact on existing users. Field type changes (e.g., keyword to long) require a major version bump. + +7. **Add error handling to ingest pipelines** +Include `tag` fields on processors and use `on_failure` handlers. Follow the standard error message format with `_ingest.on_failure_*` fields. + +8. **Write a clear PR title and description** +Use a concise, descriptive title (e.g., `[New Integration] Add Acme Logs integration`). Summarize changes, reference related issues, and ensure documentation is up to date. ::::{tip} A well-written PR with clear documentation, versioning, and testing instructions will speed up the review and publishing process! From fe6956d5f8290c5cd22fae38f47401deca8d836b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 12 Feb 2026 14:21:41 +0000 Subject: [PATCH 3/6] Add comprehensive list of breaking change examples to publish docs Expands documentation to include specific types of changes that require a major version bump and breaking-change changelog type: - Field type changes (mapping conflicts) - Field removal/renaming - ECS field collisions - Event value changes - Configuration changes - Data stream restructuring - Transform destination changes - Default behavior changes Co-authored-by: Bill Easton --- docs/extend/_publish_an_integration.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/extend/_publish_an_integration.md b/docs/extend/_publish_an_integration.md index 7cdc0f97b9d..eef60e5eaf6 100644 --- a/docs/extend/_publish_an_integration.md +++ b/docs/extend/_publish_an_integration.md @@ -24,7 +24,19 @@ Run `elastic-package test` before submitting. Generate `sample_event.json` using Use minor version bumps for documentation-only changes and patch bumps for small fixes. 6. **Document breaking changes** -Use `breaking-change` type in changelog and clearly describe impact on existing users. Field type changes (e.g., keyword to long) require a major version bump. +Use `breaking-change` type in changelog and clearly describe impact on existing users. Breaking changes require a major version bump. + + The following changes are considered breaking: + + - **Field type changes**: Changing a field's data type (e.g., `keyword` to `long`, `long` to `keyword`) causes mapping conflicts for existing users + - **Field removal**: Removing fields that users may depend on in dashboards, alerts, or queries + - **Field renaming**: Renaming fields breaks existing references (dashboards, saved queries, detection rules) + - **ECS field collisions**: Removing non-ECS fields from ECS namespaces or changing ECS field mappings + - **Event value changes**: Changing standardized values (e.g., `event.outcome` from `"Succeeded"` to `"success"`) + - **Configuration changes**: Requiring new credentials, changing authentication methods, or modifying required settings + - **Data stream changes**: Splitting, merging, or restructuring data streams + - **Transform destination changes**: Modifying transform destination indices (requires updating `fleet_transform_version`) + - **Default behavior changes**: Changing defaults that alter data collection (e.g., deduplication settings, data stream datasets) 7. **Add error handling to ingest pipelines** Include `tag` fields on processors and use `on_failure` handlers. Follow the standard error message format with `_ingest.on_failure_*` fields. From 52bce77b29e7f67fb9435fed91ffcb278df74931 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:26:42 +0000 Subject: [PATCH 4/6] Add guidance for minimizing breaking change risk Add a new section under 'Document breaking changes' with guidance on how to minimize risk when introducing breaking changes: - Search for dependent content in the repository - Check security_detection_engine package for affected rules - Coordinate with other teams - Consider deprecation periods - Update dependent assets in the same PR Co-authored-by: Norrie Taylor --- docs/extend/_publish_an_integration.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/extend/_publish_an_integration.md b/docs/extend/_publish_an_integration.md index eef60e5eaf6..5edf6d1884d 100644 --- a/docs/extend/_publish_an_integration.md +++ b/docs/extend/_publish_an_integration.md @@ -38,6 +38,16 @@ Use `breaking-change` type in changelog and clearly describe impact on existing - **Transform destination changes**: Modifying transform destination indices (requires updating `fleet_transform_version`) - **Default behavior changes**: Changing defaults that alter data collection (e.g., deduplication settings, data stream datasets) + **Minimizing risk from breaking changes:** + + Breaking changes can affect content inside and outside this repository. Before introducing a breaking change: + + - **Search for dependent content in this repository**: Use `grep` or search tools to find dashboards, transforms, and other assets that reference the fields you're changing. + - **Check the `security_detection_engine` package**: Security detection rules may depend on your integration's fields. Search in `packages/security_detection_engine/` for references to affected fields. + - **Coordinate with other teams**: Other Elastic repositories (e.g., `detection-rules`, `kibana`) may contain content that depends on your integration's fields. Reach out to relevant teams before merging breaking changes. + - **Consider deprecation first**: Instead of immediately removing or renaming fields, consider a deprecation period where both old and new fields are populated, giving users time to migrate. + - **Update dependent assets**: If dashboards or other assets in this repository reference changed fields, update them in the same PR or coordinate the changes. + 7. **Add error handling to ingest pipelines** Include `tag` fields on processors and use `on_failure` handlers. Follow the standard error message format with `_ingest.on_failure_*` fields. From 18178fd44d08eaede36b52053178c2b84b357f9d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 12 Feb 2026 17:45:43 +0000 Subject: [PATCH 5/6] Address review feedback: fix changelog type and versioning guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix changelog type: bug-fix → bugfix (no hyphen) - Remove 'deprecation' type (not used in existing changelogs) - Fix versioning guidance: patch for bug fixes and doc-only changes, minor for new features Co-authored-by: Bill Easton --- docs/extend/_publish_an_integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/extend/_publish_an_integration.md b/docs/extend/_publish_an_integration.md index 5edf6d1884d..3a47157b441 100644 --- a/docs/extend/_publish_an_integration.md +++ b/docs/extend/_publish_an_integration.md @@ -12,7 +12,7 @@ Before opening your PR, make sure you have: Run `elastic-package check` to validate formatting, build, and linting. Run `elastic-package format` if files need reformatting. 2. **Add a changelog entry** -Include a `link:` field pointing to your PR. Use the correct type: `enhancement`, `bug-fix`, `breaking-change`, or `deprecation`. +Include a `link:` field pointing to your PR. Use the correct type: `enhancement`, `bugfix`, or `breaking-change`. 3. **Update CODEOWNERS** (new integrations only) Add your package to `.github/CODEOWNERS` with the format: `packages/ @elastic/`. @@ -21,7 +21,7 @@ Add your package to `.github/CODEOWNERS` with the format: `packages/ Date: Thu, 12 Feb 2026 22:47:04 +0000 Subject: [PATCH 6/6] Fix CODEOWNERS path format to use leading slash Update the CODEOWNERS guidance to use the correct absolute path format (/packages/) to match the actual file conventions. Co-authored-by: Bill Easton --- docs/extend/_publish_an_integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/_publish_an_integration.md b/docs/extend/_publish_an_integration.md index 3a47157b441..7c270d7fb71 100644 --- a/docs/extend/_publish_an_integration.md +++ b/docs/extend/_publish_an_integration.md @@ -15,7 +15,7 @@ Run `elastic-package check` to validate formatting, build, and linting. Run `ela Include a `link:` field pointing to your PR. Use the correct type: `enhancement`, `bugfix`, or `breaking-change`. 3. **Update CODEOWNERS** (new integrations only) -Add your package to `.github/CODEOWNERS` with the format: `packages/ @elastic/`. +Add your package to `.github/CODEOWNERS` with the format: `/packages/ @elastic/`. 4. **Include test coverage** Run `elastic-package test` before submitting. Generate `sample_event.json` using `elastic-package test system --generate`.