Skip to content

Latest commit

 

History

History
99 lines (67 loc) · 4.02 KB

Versioning and changelog.md

File metadata and controls

99 lines (67 loc) · 4.02 KB

Versioning and changelog

The changelog is prepared manually immediately before a release, by moving changelog entries from UNRELEASED.md to CHANGELOG.md, under a new heading for the version number.

Use the Skip Changelog label to ignore a failing changelog check in your pull request if you feel the code changes do not warrant a changelog entry.

How to write a changelog entry:

  • Use a positive, conversational tone (for example, use “support” over “allow” and other authoritative verbs)
  • Avoid redundancy when possible (try to phrase a bug fix entry without the word “bug”)
  • Use sentence case
  • Use plain language

Component name formats:

When referring to the concept of a component: use sentence case and include a space. For example, write “text field” instead of “TextField”. This format helps non-developers with documentation comprehension.

When referring to an actual React component:

  • Refer to components by their React name (singular).
    • Do: Banner, Tabs, ResourceList
    • Don’t: Banners, Avatars, resource list.
  • Components: use upper CamelCase, also known as PascalCase, wrapped in backticks. For example, TextField.
  • Props: use lower camelCase, wrapped in backticks. For example primaryAction.
  • Putting it all together: “Added a primaryAction prop to TextField”.

Change log entry descriptions should be brief but descriptive and follow this structure:

## 2.0.0 - 2018-05-07

### Breaking changes

- Past tense verb + brief issue/enhancement description in `ComponentName` ([#100](https://github.com/shopify/polaris-react/pull/100))

Contributed from the community:

- Past tense verb + brief issue/enhancement description in `ComponentName` ([#100](https://github.com/shopify/polaris-react/pull/100)) (thanks [@username](https://github.com/username) for the [original issue](issue link)) and/or (thanks [@username](https://github.com/username) for the [pull request](pull request link))

The possible groups in which to categorize changes are:

  • Breaking changes
  • New components
  • Enhancements (new variations, accessibility improvements, etc.)
  • Design updates (non-breaking design changes implemented in code)
  • Bug fixes
  • Documentation
  • Dependency upgrades
  • Development workflow (new yarn commands or changes to existing commands)
  • Code quality (non-trivial changes to code which effect the private API)
  • Deprecations

Out of scope for CHANGELOG.md

Generally, changes related to these topics can be omitted:

  • Style guide (update the “What’s new” page instead)
  • UI Kit (unless noteworthy)
  • Dev dependencies upgrades
  • Chores (infrastructure, release process…)

Unreleased changes

Unreleased changes must go under in the UNRELEASED.md file:

### Bug fixes

- Fixed something ([#100](https://github.com/shopify/polaris-react/pull/100))

Entries must be moved from UNRELEASED.md to CHANGELOG.md at each release.

Versioning scheme

Because we expose both React components (for which the markup, including class names, is an implementation detail) and static CSS/Sass builds, the versioning scheme for Polaris is somewhat unusual. The following sections detail what kinds of changes result in each of major, minor, and patch version bumps:

Major

  • Removal of a component
  • Removal of a prop from a component
  • Change to the type accepted for a prop
  • Breaking changes to minimum version of dependencies
  • Breaking changes to public Sass variables, functions and mixins

Minor

  • New component
  • New prop for a component
  • Additional type accepted for a prop
  • Deprecation of a component, prop, public Sass variable, function, or mixin (ahead of its removal in the next major version)

Patch

  • Breaking change to the HTML generated by a component, including addition, removal, or renaming of classes
  • Changes that do not impact public APIs
  • Non-breaking changes to minimum version of dependencies
  • Breaking changes to private Sass variables, functions, and mixins