Documentation Writers' Toolkit Contribute Contribute to What's new or release notes

Contribute to What’s new or release notes

This topic explains the decisions and actions associated with collecting, writing, and publishing What’s new content.

The information on this page can be used for Grafana products that use the What’s new or Content Management System (CMS) to publish notes about new and updated features. However, not every product uses the What’s new process for their release notes. For example, the release notes for Grafana Tempo are created within the Tempo repository. The Grafana Cloud Traces updates are published using the What’s new.

What’s new documentation development process

What’s new content is published to the website through the website content management system (CMS).

Because this platform is meant to be used by the entire organization, by default anyone can contribute and publish to What’s new, without the need for approval. Quality assurance is a conversation within and between contributing teams and internal stakeholders, but there are some best practice guidelines described in the last two sections of this topic.

What does “Published” mean?

It’s important to understand that, in the context of the CMS, the word “published” has a slightly different meaning than in general use:

• Published, but not Live: Your entry is complete and in Published status, but not visible on the What’s new in Cloud page.
• Published and Live: Your entry is complete and in Published status, and visible on the What’s new in Cloud page.

What’s new timing

Enter release notes into the CMS two to four weeks before the feature is available, depending on the size of the product or feature.

For Grafana versioned releases, have your release notes entered in the CMS by the cut-off date communicated by the delivery team.

This gives the Go To Market (GTM) team time for promotion and enablement. For more information, refer to the Record Announce Document Ship (RADS) guidelines.

Create a What’s new entry

When you’re ready to add a What’s new entry, complete the following steps:

1. Go to the What’s new collection of the website CMS and click New Feature at the top of the page.

2. Fill out the CMS fields.

3. Click Save. The entry is now in Draft status and the CMS opens a pull request in the grafana/website repository.

4. (Optional) Preview your entry on GitHub.

   While the CMS provides a preview of your entry, it doesn’t render video. Previewing your entry on GitHub lets you view videos and see your entry in the context of the website.

   • Release date in the past - Your entry will be visible in the website-generated preview.

   • Release date in the future - Your entry is only visible in the preview of the internal feed. To see it, in the deploy preview URL, replace /docs/grafana-cloud with the heading for your entry. For example: https://deploy-preview-18347-zb444pucvq-uw.a.run.app/whats-new/#create-subtables-in-table-visualizations.

5. If your entry is ready to publish, proceed to the next step. If your entry requires review, follow these steps:

   1. In the Status drop-down, select In review.
   2. Work with your team to review and finalize the generated pull request.

   Caution

   The Grafana Labs documentation team doesn’t automatically review these pull requests; teams that create What’s new entries are responsible for determining their own review process.

6. Publish your entry by the release date you’ve entered.

   • To publish from GitHub, merge your PR.
   • To publish from the CMS:
   1. In the Status drop-down, click Ready.
   2. In the Publish drop-down, click Publish now.

The entry appears in What’s new in Cloud on the release date you’ve entered. If the date is in the past, it appears immediately.

For Grafana versioned releases, the content you enter in the CMS is published in the versioned What’s new at a later date. To understand the process of creating release notes for Grafana versioned releases, refer to Create the versioned release notes.

CMS fields

Edit What’s new entries

Regardless of the status of your entry, it’s always best to use the CMS to make any changes. To make edits, follow these steps:

1. Navigate to the CMS.

   • If your entry is already in Published status, you can find it in the Contents section of the CMS under What’s New in Cloud.
   • If your entry is still in Draft or Review status, you can find it in the Workflow section of the CMS under the appropriate heading.

2. Update the fields that you need to change.

3. Click Save. The entry is now in Draft status.

4. Do one of the following:

   • If your entry is ready to publish, select Ready in the Status drop-down, and then Publish now in the Publish drop-down.
   • If your entry needs to be reviewed, select In review in the Status drop-down to open a review PR. For more information on managing review PRs, see step 3 in the Create a What’s new entry.

If your entry is already live in both What’s new in Cloud and it’s between the cut-off date for a versioned release and the release date, update the CMS and then reach out to the person responsible for creating the versioned release notes.

If your entry requires an update after it’s live in both the Cloud and self-managed What’s new, you’ll need to update both entries.

Features in a new release stage

If you’ve previously created a What’s new entry for a feature when it was in an early release stage and you want to announce that the feature has moved into a new release stage, create a new entry. For example, you published a What’s new entry when the feature was in public preview and now the feature is in general availability.

You don’t have to make the new entry as robust as the previous one. Instead, you can keep the new entry brief by referring to or linking to the previous entry.

Create the versioned release notes

The following instructions are for the person directly responsible for creating the versioned release notes. This is typically someone on the Technical Writing team.

1. After the cut-off date for What’s new entries has passed, cut a branch and create a draft pull request with an empty whats-new-in-vxx-x.md file to be populated with the What’s new content for the next release. This PR should include:

   • Updates to the whatsnew/_index.md
   • Update to the link and version number located on the What’s new tile of docs/sources/_index.md
   • The new upgrade guide
   • The new breaking changes page, if needed

2. Label the PR no-backport for now; this may change.

3. Have someone, typically the Tech Writing team build engineer, generate a Markdown file from the What’s new in Cloud with the following conditions:

   • Filtered by the relevant Grafana version
   • Includes front matter for each entry
   • Grouped by tags; entries with multiple tags should only be included once, grouped by their first tag alphabetically

4. Add the content of this Markdown file to the whats-new-in-vxx-x.md file using the tags data to group items.

   If internal enablement videos are listed for entries, but the associated YouTube videos aren’t in the body text of those entries yet, you’ll need to add them later. To do this, generate another Markdown file from the What’s new in Cloud closer to the release date and make updates in whats-new-in-vxx-x.md from the newly generated file.

5. A week before the release date, change the PR status from Draft to Ready for Review to signal to other stakeholders that the PR is now ready for any further review.

   Reviews must not include any copy edits unless there are inaccuracies or typos, because all copy edits should happen when entries are added in the What’s new in Cloud. If there are any inaccuracies, those need to be corrected in both the Cloud and versioned What’s new.

6. Have the PM review the content to adjust the order, if needed.

7. Work with the PM to make final adjustments to the upgrade guide or breaking changes page.

8. Add a backport label to the PR, if needed.

9. Two days before the release, get a final generated Markdown file from the What’s new in Cloud and make any needed additions to the whats-new-in-vxx-x.md file.

10. On the day before release day, merge the What’s new branch into main.

The What’s new is live in the “next” docs. When the release branch is promoted to GA, the What’s new will also be part of the “latest” doc set.

How to determine if content belongs in What’s new

Grafana publishes a What’s new documentation page and blog post along with every minor and major release.

These posts are popular, and a good way for users to learn about the exciting new things Grafana has released. What’s new also drives go-to-market enablement: it’s used to train the field and make videos on the topics in What’s new.

However, unlike a comprehensive CHANGELOG, What’s new is curated. If it contained every update and a detailed What’s new post for every little bug fix, it would be too noisy for people to read.

So how do you decide whether to write a What’s new post for your latest improvement?

Add a What’s new for anything that could excite or concern a customer

What’s new content should address changes that have some kind of material impact on the user experience.

• Include changes that affect customers, whether they’re new features to try out or important, long-requested bug fixes.
  • Most visualization changes and most additions to the UI should be in the What’s new document, even when they seem small.
• Almost every change or addition associated with Prometheus and Loki is of interest, too.
• What’s new content should also include changes that require customers to do something, like change their API keys to Service Accounts, or stop using a deprecated API or plugin.
• A What’s new page should include announcements —- things for customers to notice and try out. These could also be notable community contributions to thank a contributor.

When in doubt, ask your nearest Product Manager (PM) or Engineering Manager (EM). Err on the side of yes, put it in What’s new.

Examples of what to include in What’s new

• A new Transformation: Partition by values.
  • This is one of many transformations, but it’s also brand-new functionality that a user might not notice if they didn’t read the What’s new document. What’s new is also a low-effort place to describe some nice use cases and examples for the feature so that users adopt it.
• The new Candlestick visualization.
  • This was a beta feature, but still listed in What’s new to get the word out and encourage users to try it.
• All-new Swagger docs for the API.
  • This is significant because it makes Grafana documentation much easier to use, and it’s a new place for users to go for help when using the API.
• Removing beta labels from several panels, which makes then generally available.
  • This is a small change code-wise, but a big statement with big customer impact. Customers now know that those plugins are fully supported and recommended for use in production.
• New keyboard shortcut
  • This is a small change, but it brings attention to a feature that has been improved recently and that most people don’t know about.
• Search improvement for Flame graphs
  • Fuzzy search. Has to be in the blog post.
• Changes to the Prometheus query editor
  • These are query patterns for the data source that most users use.

Examples of what not to include in What’s new

These are important improvements, but are better placed in the CHANGELOG than What’s new:

• A documentation update
  • This update doesn’t require customers to change their behavior—they’ll simply see better instructions the next time they use the docs.
• A bug fix related to migrations
  • This is a bug fix that doesn’t require customer action.
• A usability improvement to an existing transformation
  • Nice fix, but very detailed. Should be in the CHANGELOG but not What’s new.
• Change regular expression to accommodate a new branching strategy in Enterprise
  • This change is invisible to customers.

Guidelines for What’s new content

Follow these guidelines to ensure that your What’s new or release notes content is clear, helpful, and easy to understand.

• Directly address your users.

  Address them using the imperative or as “you”.

  Example: Shorten your communication time when reporting issues and requesting help from Grafana Labs by grabbing a panel’s query response data and panel settings.

• Make use of active voice or present tense.

  Example: Enable a configuration option to skip user organization and roles synchronization with your Security Assertion Markup Language (SAML) provider.

• Don’t refer to the release version, for example, “In Grafana 9, we " or “As of now, we”.

  The What’s new or release notes are understood to be providing information for a specific release, so there is no need to repeat this information.

• Provide high-level descriptions.

  Tell customers what goal they can accomplish or what problems they can solve with the feature. Describe the business value. Don’t go into details about how the feature works, or configuration steps.

  Use paragraphs and not bullet points. The website summarizes content using the first two paragraphs and won’t summarize bullet points.

  Link out to topics in the documentation that provide more detailed information or steps.

  Example: Use custom branding to make Grafana your observability tool by adding your own sign-in page, help links, logo, application name, and more.

• Don’t refer to how the feature used to work.

  For example, don’t say “Previously, alert rules changed state when the rule was facing an error or a timeout. Now, the state doesn’t update.”

• For changes or updates to features, provide brief descriptions.

• You can use first person plural, such as “we”.

  Our style normally prefers second person (“you”) and avoids first person (“I”/“we”). Release notes, like blog posts, use a more conversational tone and often use first person plural: “We’ve made multi-tenant queries available.”

  If you receive an error messages from Vale linter, you can use Skip rules to ignore checks for the Grafana.We rule. You can use this check at the beginning of your file after the front matter: <!-- vale Grafana.We = NO -->