Skip to content

Commit 777c913

Browse files
committed
added release notes guidelines
1 parent 14ee4ff commit 777c913

File tree

1 file changed

+90
-1
lines changed

1 file changed

+90
-1
lines changed

docs/workflows/infrastructure-group/publish-tfe-docs.md

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ If you need to update any existing documentation, or if you need to apply exclus
4747

4848
Review and merge any other PRs opened against the release branch.
4949

50-
Review and merge the `TFE Release <milestone>.<major>.x` release notes PR. The release engineer is responsible for merging the PR. The release engineer also prepares the release notes section of the docs.
50+
Review and merge the `TFE Release <milestone>.<major>.x` release notes PR. The release engineer is responsible for merging the PR. The release engineer also prepares the release notes section of the docs. Refer to [Release notes guidance](#release-notes-guidance) for assistance.
5151

5252
## On the day of the release
5353

@@ -134,3 +134,92 @@ description: >-
134134
tfc_only: true
135135
---
136136
```
137+
138+
### Release notes guidance
139+
140+
Releasen notes should help readers understand what has changed, why, and what actions they need to take as a result. It's rarely ever appropriate to include a changelog entry without any edits in the release notes.
141+
142+
#### Include important and impactful updates
143+
144+
The release notes are an opportunity to explain and advertise changes that significantly impact the user experience. Our changelog records every single change, but the release notes should only contain updates that do the following:
145+
146+
- Address a salient user concern, such as security fixes
147+
- Let users do something new
148+
- Significantly improve the user experience, such as major UI updates and performance improvements
149+
- Require or recommend that users take action, such as deprecated functionality and recommended upgrades
150+
151+
Omit minor UI changes and internal changes that don't directly affect the experience.
152+
153+
#### Focus on features
154+
155+
Start the update with a complete sentence that describes what part of the system has been changed. Don’t start with "Added", "Fixed", or "Changed", which is implied by the section title.
156+
157+
**Needs work**:
158+
159+
```
160+
Added Prometheus format for usage metrics.
161+
```
162+
163+
**Better**:
164+
165+
```
166+
Usage metrics are available in Prometheus format.
167+
```
168+
169+
#### Explain what and why
170+
171+
Practitioners may not understand new Terraform-specific feature names or internal jargon. Newer users may also need help understanding the impact of a new feature. Explain new features and their value in plain language. If you must include Terraform-specific jargon, explain the terminology.
172+
173+
For bug fixes, you may need to compare the fix to pain points in the previous version. Where possible, link to related documentation or tutorials.
174+
175+
**Needs work**:
176+
177+
```mdx
178+
Added support for cloud integration when using the CLI.
179+
```
180+
181+
**Better**:
182+
183+
```
184+
You can now use the [Terraform CLI integration](/terraform/cli/cloud) to run Terraform Enterprise from the command line. We recommend using this native integration for Terraform versions 1.1 or later because it provides an improved user experience and various enhancements.
185+
```
186+
187+
188+
**Needs Work**:
189+
190+
```
191+
Added variable sets.
192+
```
193+
194+
**Better**:
195+
196+
```
197+
You can now define sets of variables and reuse them across multiple workspaces. For example, you could define a set of variables that contain provider credentials and automatically apply it to all of the workspaces that use the provider. Refer to [Variable sets](/terraform/cloud-docs/workspaces/variables) for more information.
198+
```
199+
200+
201+
#### Group related updates
202+
203+
When applicable, combine content about the same part of the system into a single entry. Chunking related updates makes it easier for users to understand everything that has changed in components they care about.
204+
205+
**Needs work**:
206+
207+
```
208+
Added warning to notify users of older provider documentation.
209+
Added an outline to the public provider documentation page.
210+
```
211+
212+
**Better**:
213+
214+
```
215+
The private registry UI now displays a warning message for old versions of provider documentation with a link to the latest version. The UI includes an outline for provider documentation that lets you navigate more quickly between sections.
216+
```
217+
218+
#### Refer to the reader as "you"
219+
220+
Per the style guide, [address the reader as "you"](../../style-guide/general/point-of-view.md#address-the-reader-as-you).
221+
222+
223+
#### Format single updates as a paragraph
224+
225+
A list with one item isn’t a list. If there is only one update in a section, format it as a paragraph.

0 commit comments

Comments
 (0)