• /
  • Log in

Create release notes

This page is for release notes for downloadable software. For product announcements, see What's new style guidelines.

New release note

To add a release note to the docs site:

  1. Find the most recent release note for your agent, and make a copy of it in the same folder.
  2. When you rename your copy, avoid potential version naming conflicts by using a - separator in your file name. For example, instead of agent-123, use agent-1-2-3 for version 1.2.3 and agent-12-3 for version 12.3.
  3. Fill in the subject, releaseDate, and version. If applicable, include the downloadLink field.
  4. Using our standard headings for New features, Improvements, and Bug fixes, add enough summary information in these sections to make a great release note. Link to docs or other resources where they can learn more.
  5. Commit your changes and submit a pull request. If your release is date-sensitive, make a note in your PR.

A Tech Docs hero will review your release note content and approve your PR to get it published. You can also request others on your team to review your PR.

We build and deploy the docs site a few times a day, and sometimes builds can take a few hours to complete. If your release is time-sensitive, ensure you've planned for enough time to get your docs live.

What makes a great release note?

Great release notes help users quickly become familiar with your important update, so they know why it matters. Great release notes also help our support and security teams.

By encouraging users to keep current with your latest release, this reduces support time to solve problems on outdated versions. It also mitigates risks if any potential vulnerabilities have been resolved with your latest version.

To write a great release note, be as specific as possible. For example:

  • Briefly describe new functionality. Give an example of the value it provides, and link to more detailed information.
  • Don't use vague wording such as "various bug fixes." Instead, clearly state what has been improved, so readers will know if an issue they’ve experienced has been resolved.

New release notes category

This information is primarily for the Tech Docs team's use.

To add a new release notes category, update the following areas of the docs site. (You do not need to update the releaseNote.js or releaseNoteLandingPage.js files in the nav/templates folder.) Before you submit your pull request to the GitHub docs site, check that the landing pages and placeholder release note build correctly in your localhost.

Category landing page

In /src/content/docs/release-notes, add the following:

  • A folder for your new release notes category. The RSS feed link, page format, and date order for release notes listed on this page are generated automatically. For example, see the C SDK category landing page format.
  • An index.mdx file in your new folder containing the subject. The subject is the name that will appear on the Release notes landing page.
  • A placeholder release note in this folder for the agent team to fill out. If used, the downloadLink field in the release note will be formatted automatically in the published release note.

Before the new category goes live, check with the team's Product Marketing Management (PMM) rep whether they want to include the link in an upcoming What's new post.

Landing page

In /src/content/docs/release-notes/index.mdx, add a new tile section in alphabetical order for your release notes category.

Example:

<TechTile
name="Logs"
icon="logo-newrelic"
to="/docs/release-notes/logs-release-notes"
/>

Logos come from @newrelic/gatsby-theme-newrelic/icons/logo/. If a logo does not already exist for the new agent, use the standard logo-newrelic icon or an image in @newrelic/gatsby-theme-newrelic/icons/feathers.js. If you need other options, talk to the team's designer.

Add a link to your new release notes category in the agent's documentation, typically in its Get started category. For more information, see our documentation about docs in multiple menus.

Optional: Add a link in the agent's landing page text by updating the index.mdx file in its taxonomy.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.