Update CONTRIBUTING.md to mention creating a PR

[strawgate]

No description provided.

[github-actions]

Vale Linting Results

Summary: 1 warning, 2 suggestions found

⚠️ Warnings (1)

File	Line	Rule	Message
docs/extend/_publish_an_integration.md	55	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'for example' instead of 'e.g'.

💡 Suggestions (2)

File	Line	Rule	Message
CONTRIBUTING.md	12	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
CONTRIBUTING.md	12	Elastic.Wordiness	Consider using 'before' instead of 'prior to'.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[strawgate]

@claude let's review the PR Feedback and comments from the last 20 or so PRs (that have comments) and come up with a list of additional items we need to add to docs/extend/_publish_an_integration.md

We can have some hyper specific items (always run elastic-package format, elastic-package build, etc), but avoid hyper specific instructions that only occurred in one PR and focus on holistic and more general feedback like document breaking changes, etc.

[github-actions]

Claude finished @strawgate's task in 2m 33s —— View job

---

Analyzing PR Feedback for Documentation Improvements

• Gather repository context
• Read current docs/extend/_publish_an_integration.md
• Review recent PRs with comments (last ~20 PRs)
• Analyze common feedback patterns
• Compile list of recommended additions

---

Summary

Based on reviewing ~30 recent PRs with review comments, I've identified the following common feedback patterns that should be documented in docs/extend/_publish_an_integration.md:

---

Recommended Additions to the "Publish an Integration" Documentation

1. Run Pre-submission Checks (High frequency)

elastic-package format   # Format YAML files consistently
elastic-package build    # Build the package
elastic-package lint     # Lint the package
elastic-package check    # Run all checks

Note: CI will fail if files are not properly formatted. Run elastic-package format before committing.

---

2. Changelog Requirements (Very high frequency)

• Always include a link: field in changelog entries pointing to the PR
• Use the correct PR number (not a previous/related PR number)
• Use correct change type: enhancement, bug-fix, breaking-change, deprecation
• Example format:

- version: "1.2.3"
  changes:
    - description: Description of change
      type: enhancement
      link: https://github.com/elastic/integrations/pull/XXXXX

---

3. Update CODEOWNERS (Medium frequency)

• Add your package to .github/CODEOWNERS if creating a new integration
• Follow the format: packages/<package_name> @elastic/<team-name>

---

4. Documentation Consistency (High frequency)

• Avoid duplicating content between sections (e.g., "Supported use cases" and "Features")
• Use using instead of via (Elastic style guide)
• Reference upstream vendor documentation instead of duplicating it to avoid outdated information
• Include a "Configuration" section pointing to relevant upstream docs where applicable

---

5. Field Definitions (Medium frequency)

• Ensure field format matches the data type (e.g., don't use format: bytes for packet counts)
• For percentage fields, use scaled_float with unit: percent consistently
• Check for typos in field descriptions

---

6. Ingest Pipeline Best Practices (Medium frequency)

• Include tag fields on processors for error traceability
• Add on_failure handlers for processors that can fail (convert, date, json)
• Use a consistent global error handler pattern with _ingest.on_failure_processor_tag

---

7. Test Coverage (High frequency)

• Include system tests where possible
• Generate sample_event.json using elastic-package test system --generate
• For policy tests, include .expected files to verify rendered output
• Ensure test variable names match manifest variable names

---

8. Version Bumping (Medium frequency)

• Use minor version bumps for documentation-only changes
• Use patch version bumps for small bug fixes
• Update Kibana version constraints according to guidelines

---

9. YAML/Template Best Practices (Medium frequency)

• Files should end with a trailing newline
• Use explicit string tags (!!str) for IDs that might be coerced by YAML
• Avoid unreachable template code (e.g., else branches when a default is always provided)

---

10. Dashboard and SLO Consistency (Medium frequency)

• Ensure field names in SLOs/dashboards match actual Elasticsearch field names
• Verify field prefixes (e.g., metrics.apache.request.time vs apache.request.time)

---

11. Breaking Changes (General guidance)

• Document breaking changes clearly in the changelog with type breaking-change
• Consider backwards compatibility when removing or renaming fields
• Update documentation to reflect deprecated features

---

Items NOT Recommended (Too specific/one-off)

These items appeared only once and are too specific to include:

• Specific processor ordering for individual integrations
• Single integration-specific field mappings
• One-time CI workarounds

---

|

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@claude let's add very concise statements for 1, 2, 3, 7 , 8, and 11.

After that please review another 20 or so PRs, maybe from 6 months or a year ago and see if there are additional concise items we should add

[github-actions]

Claude finished @strawgate's task in 3m 40s —— View job

---

Adding Pre-submission Guidelines to Documentation

• Read current docs/extend/_publish_an_integration.md
• Add concise statements for items 1, 2, 3, 7, 8, and 11
• Review ~20 PRs from 6-12 months ago for additional patterns
• Compile any additional recommendations

---

Summary

I've updated docs/extend/_publish_an_integration.md with concise pre-submission checklist items based on your request and my analysis of ~30+ older PRs.

Items Added (8 total):

1. Run pre-submission checks - elastic-package check and elastic-package format
2. Add a changelog entry - Include link: field with correct type
3. Update CODEOWNERS - For new integrations only
4. Include test coverage - elastic-package test and sample_event.json generation
5. Bump the package version appropriately - Minor for docs, patch for fixes
6. Document breaking changes - With breaking-change type and major version bumps
7. Add error handling to ingest pipelines - tag fields and on_failure handlers (from older PR analysis)
8. Write a clear PR title and description

Additional Patterns from Older PRs (Not Added - but notable):

From reviewing PRs from March-August 2025, I found these recurring patterns:

• Field type consistency: Avoid changing field types without major version bumps (PRs Mapping of Gigamon Metadata Attributes to ECS fields #14692, [Jamf Protect 3.1.0] New pipelines added and enhancements #14750)
• ECS compliance: Use external: ecs for ECS fields to pick up correct descriptions/types
• Trailing newlines: Files should end with newlines
• Description formatting: Ensure descriptions are complete sentences and consistent (end with periods, consistent capitalization)
• Test samples: Add new test samples rather than replacing existing ones when expanding functionality

These were less universal than the items I added, so I left them out to keep the checklist concise.
|

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@claude let's review older PRs for things that were flagged as breaking changes and let's include a list of things that are clearly breaking changes (like your Field type consistency: Avoid changing field types without major version bumps) example

[github-actions]

Claude finished @strawgate's task in 3m 2s —— View job

---

Researching Breaking Changes in PR History

• Gather repository context
• Read current docs/extend/_publish_an_integration.md
• Review older PRs for breaking change discussions
• Compile list of breaking change examples
• Update documentation with breaking change guidance

---

Summary

I analyzed 50+ PRs and changelog entries across the integrations repository to identify patterns of breaking changes. I've updated docs/extend/_publish_an_integration.md with a comprehensive list of changes that are considered breaking and require a major version bump.

Breaking Changes Added to Documentation

Based on real examples from PR reviews and changelogs:

1. Field type changes - Changing data types (e.g., keyword to long) causes mapping conflicts (ti_anomali #13909, gigamon #14692)

2. Field removal - Removing fields breaks dashboards, alerts, and queries (wiz #16892, docker changelog)

3. Field renaming - Renaming fields breaks existing references (sentinel_one #15931, beyondinsight_password_safe changelog)

4. ECS field collisions - Removing non-ECS fields from ECS namespaces (box_events #15947)

5. Event value changes - Changing standardized values like event.outcome (azure changelog)

6. Configuration changes - Requiring new credentials or authentication methods (ti_abusech changelog, akamai changelog)

7. Data stream changes - Splitting or restructuring data streams (entityanalytics_ad changelog)

8. Transform destination changes - Modifying transform destinations requires updating fleet_transform_version (ti_anomali #13909 review)

9. Default behavior changes - Changing defaults for data collection (crowdstrike changelog)

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
|

[norrietaylor]

@claude, if there are breaking changes in the integration, it is possible that dashboards, rules and other content in this repo (and maybe others) would be broken.

Let's add some guidance to minimize that risk.

[github-actions]

Claude finished @norrietaylor's task in 1m 49s —— View job

---

Adding Guidance for Minimizing Breaking Change Risk

• Gather repository context
• Read current documentation on breaking changes
• Research how breaking changes can affect dashboards, rules, and other content
• Add guidance to minimize breaking change risk
• Push changes

---

Summary

Added a new "Minimizing risk from breaking changes" section to the publish documentation. The guidance includes:

• 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
• Coordinate with other teams: Other Elastic repositories (e.g., detection-rules, kibana) may contain content that depends on your integration's fields
• Consider deprecation first: Instead of immediately removing or renaming fields, consider a deprecation period where both old and new fields are populated
• Update dependent assets: If dashboards or other assets in this repository reference changed fields, update them in the same PR or coordinate the changes

Changes pushed in commit 52bce77.

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[github-actions]

The expanded documentation provides helpful guidance for contributors, but needs corrections to align with existing project conventions.

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@claude please address

[github-actions]

Claude finished @strawgate's task in 45s —— View job

---

Addressing Review Feedback

• Read the current documentation file
• Fix changelog type: bug-fix → bugfix
• Fix versioning guidance to align with established conventions
• Push changes

---

Summary

I've addressed both review comments:

1. Fixed changelog type (line 15): Changed bug-fix to bugfix (no hyphen) and removed deprecation which isn't used in the codebase
2. Fixed versioning guidance (line 24): Updated to match established conventions - patch releases for bug fixes and documentation-only changes, minor releases for new features

Changes pushed in commit 18178fd.

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[github-actions]

🔍 Preview links for changed docs

• docs/extend/_publish_an_integration.md

[elastic-vault-github-plugin-prod]

🚀 Benchmarks report

Package bluecoat 👍(0) 💚(0) 💔(1)

Expand to view

Data stream	Previous EPS	New EPS	Diff (%)	Result
director	40000	23809.52	-16190.48 (-40.48%)	💔

To see the full report comment with /test benchmark fullreport

[strawgate]

@claude please address feedback and do one last review to make sure we didnt miss anything!

[github-actions]

Claude finished @strawgate's task in 1m 41s —— View job

---

Addressing Feedback and Final Review

• Gather repository context
• Review existing review comments and feedback
• Address the CODEOWNERS path feedback (missing leading slash)
• Final review of all changes
• Push changes

---

Summary

I've addressed the remaining feedback and completed a final review of the documentation changes.

Feedback Addressed

• CODEOWNERS path format: Added the missing leading slash to match the repository's actual format (/packages/<package_name> instead of packages/<package_name>)

Final Review Verification

I verified the documentation accuracy against the actual codebase:

• ✓ Changelog types (enhancement, bugfix, breaking-change) - confirmed against existing changelogs
• ✓ Versioning guidance (patch for fixes/docs, minor for features, major for breaking) - confirmed against docs/extend/quick-start.md:372-374
• ✓ CODEOWNERS format with leading slash - confirmed against .github/CODEOWNERS
• ✓ elastic-package commands are accurate

Changes pushed in commit 2d0dbf7.

--- |

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[github-actions]

The previous review concerns about changelog types and versioning guidance have been addressed. The one remaining issue (missing leading slash in CODEOWNERS path at line 18) is still unresolved. Once that low-severity fix is applied, this PR is ready to merge.

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[axw]

Looks good, just one query about changing values for well-defined fields. Changing from a non-compliant value to a compliant one seems like it should be considered a bug fix, though I guess you could argue it's like one of those load-bearing bugs.

[axw]

This wouldn't be considered a bug fix?

[strawgate]

A breaking bug fix 😂

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 63e124c

History

• 💔 Build #38126 failed 2d0dbf7
• 💔 Build #38117 failed e495767
• 💔 Build #38111 failed 18178fd