Skip to content

[DOCS] Add docs versioning comment action #132257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed

Conversation

leemthompo
Copy link
Contributor

@leemthompo leemthompo commented Jul 31, 2025

Adds a friendly automated reminder on PRs that modify documentation files to help enforce our cumulative documentation guidelines.

  • Triggers when a PR is opened or reopened that modifies .md files in the docs/ directory
  • Posts a single comment explaining cumulative docs and applies_to tagging requirements
  • Provides collapsible details with quick do's and don'ts for version tagging
  • Never comments more than once on the same PR (checks for existing comments first)
  • Includes links to full documentation and where to get help

As we've transitioned to cumulative documentation where all 9.x versions share a single page, contributors need clear guidance on properly tagging version-specific content rather than replacing information for older versions.

Uses github-script to:

  1. Filter PRs containing .md file changes in docs/ directory
  2. Check for existing bot comments to prevent duplicates
  3. Post a standardized reminder with expandable details section

Preview

The comment will look like this when rendered:

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Adds a friendly automated reminder on PRs that modify documentation files to help enforce our cumulative documentation guidelines.

- Triggers when a PR is opened or reopened that modifies `.md` files in the `docs/` directory
- Posts a single comment explaining cumulative docs and `applies_to` tagging requirements
- Provides collapsible details with quick do's and don'ts for version tagging
- Never comments more than once on the same PR (checks for existing comments first)
- Includes links to full documentation and where to get help

As we've transitioned to cumulative documentation where all 9.x versions share a single page, contributors need clear guidance on properly tagging version-specific content rather than replacing information for older versions.

Uses `github-script` to:
1. Filter PRs containing `.md` file changes in `docs/` directory
2. Check for existing bot comments to prevent duplicates
3. Post a standardized reminder with expandable details section
@leemthompo
Copy link
Contributor Author

closing in favor of elastic/docs-builder#1667

@leemthompo leemthompo closed this Aug 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants