Skip to content

Commit 4caa729

Browse files
authored
Update Copilot versioning instructions (#61829)
1 parent 5e11ea3 commit 4caa729

1 file changed

Lines changed: 15 additions & 29 deletions

File tree

.github/instructions/content.instructions.md

Lines changed: 15 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -95,17 +95,23 @@ Examples:
9595

9696
## Versioning
9797

98-
Avoid `{% ifversion fpt %}`, `{% ifversion ghec %}`, and `{% ifversion fpt or ghec %}` in content files whenever possible. Instead of suggesting or adding version-gating within an article:
98+
Follow one of these sets of instructions, depending on how articles are versioned in the frontmatter. Articles may be versioned for FPT and GHEC, for GHES only, or for all three. Articles may also be versioned using feature-based versioning defined in `data/features`. Feature-based versioning allows centralized control of when content appears for specific GHES releases.
9999

100-
* Write content that applies to all versions the article is versioned for
101-
* If content is truly version-specific, consider whether it is low-harm to show it to all readers (e.g., an enterprise-only row in a reference table)
102-
* Only use `{% ifversion %}` as a last resort when content would be actively misleading for readers on a different version
100+
### FPT/GHEC-only articles
103101

104-
**FPT and GHEC content**: When dotcom content applies to both products, version the page for `fpt` and `ghec` in the frontmatter. Do NOT use in-article Liquid versioning. Do NOT suggest adding `{% ifversion fpt or ghec %}` blocks as a fix for content that mentions a dotcom-only feature. Instead, suggest rewriting the content using the alternatives to inline versioning options listed below.
102+
All articles that are ONLY for FPT and GHEC should be versioned for these versions in the frontmatter.
105103

106-
**GHES content**: If versioning is necessary for GitHub Enterprise Server content, use feature-based versioning (FBV). GHES content should rely on feature flags defined in `data/features/` rather than inline `{% ifversion ghes %}` blocks. Feature flags allow centralized control of when content appears for specific GHES releases.
104+
For such content, DO NOT use in-article Liquid versioning such as `{% ifversion fpt %}`, `{% ifversion ghec %}`, and `{% ifversion fpt or ghec %}`.
107105

108-
### Alternatives to inline versioning
106+
### GHES-only articles
107+
108+
All articles that are ONLY for GitHub Enterprise Server (GHES) should be versioned in the frontmatter using feature-based versioning defined in `data/features/`.
109+
110+
### FPT, GHEC, GHES articles
111+
112+
All articles that are versioned for all of FPT, GHEC, and GHES in the frontmatter MAY require certain blocks of content to be versioned using in-article Liquid versioning. Before recommending this, check if this is really the case.
113+
114+
#### Check in-article versioning is required
109115

110116
Before resorting to in-article versioning, first consider whether the content is actually different across versions. Often procedures can be simplified to work at both levels.
111117

@@ -127,26 +133,6 @@ Use these strategies instead of `{% ifversion %}`, depending on the level of con
127133
* End list items with "({% data variables.product.prodname_ghe_cloud %} only)", "({% data variables.product.prodname_dotcom_the_website %} only)", etc.
128134
* Specify if the feature is not available for GHES with "NAME-OF-FEATURE is not available for {% data variables.product.prodname_ghe_server %}", "... (not available in {% data variables.product.prodname_ghe_server %})", etc.
129135

130-
### Example
131-
132-
When documenting a feature that only applies to dotcom (not GHES):
133-
134-
❌ Don't wrap content in version blocks:
135-
136-
```markdown
137-
{% ifversion fpt or ghec %}
138-
139-
## Immutable subject claims
140-
141-
Repositories created after July 15, 2026 now use an immutable default subject format.
142-
143-
{% endif %}
144-
```
145-
146-
✅ Do use prose to indicate availability:
147-
148-
```markdown
149-
## Immutable subject claims
136+
#### If in-article versioning is required
150137

151-
Repositories created after July 15, 2026 now use an immutable default subject format. This rollout does not include {% data variables.product.prodname_ghe_server %}.
152-
```
138+
In-article versioning is required if a block of content in an article is definitely ONLY relevant for GHES, but the article itself is otherwise versioned in the frontmatter for all of FPT, GHEC, and GHES. In this situation, use feature-based versioning (FBV) wherever possible, using `{% ifversion FBV %}` blocks, where FBV is defined in `data/features/`. If it's not possible to use FBV, use {% ifversion ghes %} blocks, which will version the content block for all versions of GHES.

0 commit comments

Comments
 (0)