You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/instructions/content.instructions.md
+15-29Lines changed: 15 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -95,17 +95,23 @@ Examples:
95
95
96
96
## Versioning
97
97
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.
99
99
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
103
101
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 inthe frontmatter.
105
103
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 %}`.
107
105
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
109
115
110
116
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.
111
117
@@ -127,26 +133,6 @@ Use these strategies instead of `{% ifversion %}`, depending on the level of con
127
133
* End list items with "({% data variables.product.prodname_ghe_cloud %} only)", "({% data variables.product.prodname_dotcom_the_website %} only)", etc.
128
134
* 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.
129
135
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
150
137
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