Skip to main content

Writing guidance

Jump to

Release notes​

There are two types of release notes: What's new and Fixed bugs.

Sometimes judgment is required to determine if a fixed bug is better presented as a What's new item or vice versa. Move the item in the file accordingly.

What’s new

Compare two source mart versions side by side before promoting a change.complete sentencepresent tense

Fixed bug

Forge Service returns an error when refreshing a large data martworded as if still brokenterse, no period

The same work item produces a different style of note depending on its type.

What's new​

Features and product backlog work items become What's new items at the top of the notes.

  • They represent new functionality that is not a bug fix.
  • They are advertisements of why an organization should upgrade.
  • They are formed as complete sentences.
  • They have a heading. This is generated from the title of the work item.

See Writing guidance.

Fixed bugs​

Bug work items are at the bottom of the notes under a Fixed bugs section.

  • They are worded as if the bug is unfixed:
    • This convention is because the content in Bug work items is scraped directly into the content of bugs in the notes. When a team creates a Bug, the author doesn't word the release note content of the work item as if the bug was fixed. Neither do they update the release note content when they close a bug.
    • Correct: Verification Service returns an error
    • Incorrect: Verification Service used to return an error
  • They are formed in present tense:
    • Correct: Verification Service returns an error
    • Incorrect: Verification Service returned an error
  • They are formed as incomplete sentences:
    • Correct: Verification Service returns an error
    • Incorrect: Verification Service returned an error. This is now fixed.
  • They are worded as a short, terse phrase, ideally one line only:
    • Correct: Non-persisted entities visible in the Custom Entities list
    • Correct: Rerunning a batch does not remap TableHistoryID on BindingHistories
    • Correct: ODBC driver fails when refreshing metadata
  • They don't start with articles when possible:
    • Correct: Verification Service returns an error
    • Incorrect: The Verification Service returns an error
  • They don't state the product name unless the note is ambiguous without it (notes are already grouped by product)

If a release note absolutely requires an explanation that expands beyond one line (ideally very few require this), add it in an italicized Details complete sentence after the note:

**TableID could not be mapped to an EntityID** errors occur | *Details: Logic is updated to reduce instances of the errors.*

Known issues​

Known issues are published separately on Clearpath Community on a page for each Classic edition version.

See writing guidance for Fixed bugs.

Critical and high bugs​

Critical and high bugs are published on Clearpath Community separately on a page for each Classic edition version.

See writing guidance for Fixed bugs.

Formatting​

Names of elements visible on a screen are bolded, like interface elements (headings, buttons, links), table components, errors, etc.

Examples​

Entity and binding descriptions are listed in the entity and binding lists of the Data Mart Details pages of the Data Catalog

Streaming jobs erroneously remain in Processing state when the Data Processing Engine fails to connect to the Realtime queue

When users create an app using the Legacy Forge user interface, only the ModifiedDTS and ModifiedUserNM system columns are created | Details: The CreatedDTS and CreatedUserNM system columns are now created.

Reference