Skip to content

Latest commit

 

History

History
61 lines (50 loc) · 6.08 KB

writing-the-cypress-changelog.md

File metadata and controls

61 lines (50 loc) · 6.08 KB
Raw

Cypress App - Managing the Release Changelog

Cypress prefers hand tailored release notes over auto generated release notes, primarily, user experience is highly valued at Cypress. åWhile Cypress is a dependency installed via a package manager, the changelog should be more akin to other desktop products like VS Code or Notion.

When to Add an Entry

The changelog should include anything that was merged into the develop branch of the cypress repo that are user affecting changes. These include:

  • breaking - A breaking change that will require a MVB
  • dependency - A change to a dependency that impact the user
  • deprecation - A API deprecation notice for users
  • feat - A new feature
  • fix - A bug fix or regression fix.
  • misc - a misc user-facing change, like a UI update which is not a fix or enhancement to how Cypress works
  • perf - A code change that improves performance

Writing Guidelines

  1. The changelog is formatted like the following. If there is not a pending changelog for the next release, add these sections.
## <RELEASE_VERSION>

_Released <RELEASE_DATE> (PENDING)_

**<CHANGE_SECTION:**

- <CHANGELOG_ENTRY>
  1. Each changelog entry is written and merged with the associated user-facing code change in cli/CHANGELOG.md.
  2. The changelog entry should be added the associated change section. The supported change sections for the changelog (that should be listed in the order below) are:
change type (by order of impact) change section details
-- Summary A description of the overall changes. This is usually only provided for breaking changes or large features. This should be written in coordination with Cypress's marketing and match the language used around the release. It may also link to relevant blogs. Example
breaking Breaking Changes Link to the Migration Guide (if any) at the beginning of this section. For each one explain the change, how it affects them, and how the can mitigate the effects of the change (unless it's covered in the Migration Guide). Example
deprecation Deprecations Explain each deprecation and that it will be removed in a future release. Example
perf Performance Example
feat Features Example
fix Bugfixes Example
misc Misc We don't use this section as much as we used to, but perhaps there was a change that is not necessarily a feature or a bugfix, it would go here. (Like the design of the browser picker changed). Example
dependency Dependency Updates A list of dependencies that were updated, downgraded, or removed as well as the version it was changed from. Example
  1. You may have several changes around a feature that make sense to group. Feel free to do so to make more sense to users consuming the changelog. Example
  2. Do not refer to 'we' when writing a changelog item. We want to phrase the changelog in a way that emphasizes how the user is impacted. Additionally 'we' may not have addressed the issue, an outside contributor may have.
    • Example: Instead of 'We fixed a situation where a cross-origin errors could incorrectly throw in Chrome' write 'Cross-origin errors will no longer incorrectly throw in Chrome in certain situations'.
  3. Be as direct as possible in explaining the changes, but with enough clarity that the user understands the full impact. Users should never have to click on the link to the issue/PR to understand the change that happened and absolutely never have to look at the code to understand the change. If you cannot yourself understand the change from the Changelog entry, add more context.
  4. Order the changelog items in order of impact. The most impactful features/bugfixes should be ordered first.
  5. If a changelog item is a regression, the description should start with Fixed a regression in [9.1.0](#9-1-0) with a link to the release that introduced it.
  6. For each changelog item, there should be a link to the issue(s) it addresses (or the PR that it was addressed in if there is no corresponding issue(s)). See phrasing below
    • For bugfixes:

      Fixes #12

    1. For other issues: "Addresses #12"
    2. When no issues, but PR: "Addressed in #12"
    3. When multiple issues: "Fixes #12, #13 and #14."

Release

At the time of the release, the releaser will:

  • remove the (PENDING) verbiage next to the perspective release date and adjust the date if needed
  • ensure the Changelog is coherent
  • ensure the change sections are in the correct order
  • ensure that the entries are ordered by impact

Each Cypress release results in a new changelog file being added to the cypress-documentation repository to be published on the doc site. Example pull request adding changelog to the repository.