Skip to content

Commit 92d0611

Browse files
committed
[DOCS] Add docs versioning comment action
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
1 parent e06e447 commit 92d0611

File tree

1 file changed

+78
-0
lines changed

1 file changed

+78
-0
lines changed
Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: "Docs versioning comment"
2+
3+
on:
4+
pull_request_target:
5+
types: [opened, reopened]
6+
paths:
7+
- 'docs/**/*.md'
8+
9+
permissions:
10+
contents: read
11+
issues: write
12+
pull-requests: write
13+
14+
jobs:
15+
versioning-reminder:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Comment on docs changes about versioning requirements
19+
uses: actions/github-script@v7
20+
with:
21+
github-token: ${{ secrets.GITHUB_TOKEN }}
22+
script: |
23+
const pr = context.payload.pull_request;
24+
const prNum = pr.number;
25+
const owner = context.repo.owner;
26+
const repo = context.repo.repo;
27+
28+
const { data: files } = await github.rest.pulls.listFiles({
29+
owner, repo, pull_number: prNum
30+
});
31+
32+
const docsFiles = files.filter(f =>
33+
/^docs\/.*\.md$/i.test(f.filename) &&
34+
f.status !== 'removed'
35+
);
36+
37+
if (!docsFiles.length) return;
38+
39+
const { data: comments } = await github.rest.issues.listComments({
40+
owner, repo, issue_number: prNum
41+
});
42+
43+
const existingComment = comments.find(c =>
44+
c.user.type === 'Bot' &&
45+
c.body.includes("Important: Docs version tagging")
46+
);
47+
48+
if (existingComment) return;
49+
50+
const body = `## ℹ️ Important: Docs version tagging
51+
52+
👋 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.
53+
54+
We use [applies_to tags](https://elastic.github.io/docs-builder/syntax/applies) to mark version-specific features and changes.
55+
56+
<details>
57+
<summary>Expand for a quick overview</summary>
58+
59+
### When to use applies_to tags:
60+
✅ At the page level to indicate which products/deployments the content applies to (mandatory)
61+
✅ When features change state (e.g. preview, ga) in a specific version
62+
✅ When availability differs across deployments and environments
63+
64+
### What NOT to do:
65+
❌ Don't remove or replace information that applies to an older version
66+
❌ Don't add new information that applies to a specific version without an applies_to tag
67+
❌ Don't forget that applies_to tags can be used at the page, section, and inline level
68+
</details>
69+
70+
### 🤔 Need help?
71+
- Check out the [cumulative docs guidelines](https://elastic.github.io/docs-builder/contribute/cumulative-docs/)
72+
- Reach out in the [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel`;
73+
74+
await github.rest.issues.createComment({
75+
owner, repo,
76+
issue_number: prNum,
77+
body
78+
});

0 commit comments

Comments
 (0)