Skip to content
This repository was archived by the owner on Jul 9, 2018. It is now read-only.
This repository was archived by the owner on Jul 9, 2018. It is now read-only.

Add CHANGELOG.md files for each package #118

Closed

Description

@ntwb

A Slack discussion last week raised the issue of creating CHANGELOG.md for each package.

Lerna can help with that https://github.com/lerna/lerna#--conventional-commits

$ lerna publish --conventional-commits (Can also be set in lerna.json)

When run with this flag, publish will use the Conventional Commits Specification to determine the version bump and generate CHANGELOG files for each package automatically.

Conventional Commits can be fully customized, a common implementation of this seen in widespread use thoughout GitHub is Angular implementation, prefixing commits with docs:, fix:, ci:, chore: and so on, when working with scoped packages the format takes on the package name as the scope, e.g. docs(i18n):, docs(a11y):, docs(is-shallow-equal): etc

Even though the Angular format above is quite common Conventional Commits is fully customizable and there are a numerous configurations available to be used from projects such as ESLint, Atom, jQuery to name but a few.

One of particular note is the jQuery preset where commits should look like:

Component: Short Description

Optional Long Description

Fixes #xxx
Closes gh-yyy
Ref #zzz

This matches quite closely the WordPress commit message format documented in our handbook:

Component: Brief summary.

Longer description with more details, such as a `new_hook` being introduced with the context of a `$post` and a `$screen`.

More paragraphs can be added as needed.

Props person, another.
Fixes #30000. See #20202, #105.

By mixing the scope package names with our own WordPress Conventional Commit Preset we could have our CHANGELOG.md files generated using a format common to existing WordPress processes which would be benfecial if the packages repo is to get merged into SVN.

Activity

  1. atimmer commented on May 1, 2018

    @atimmer
    Member

    Like I said int he #core-js meeting this week, I think this ties into @pento's proposal to only use squash commits when merging PRs on WordPress GitHub repositories. The squash pull request merge UI allows one to change the title and message of the squash commit:

    screen shot 2018-05-01 at 15 48 09

    That would remove the burden on new contributors completely. All maintainers would then make sure that this format is followed on the packages repository.

  2. ntwb commented on May 8, 2018

    @ntwb
    MemberAuthor

    Instead of hacking on changelogs here in this repo, I've just created https://github.com/ntwb/lerna-playground to work on implementing a "Conventional Commits Specification".

    If you'd like access to push, pull, and hack on that repo please ping me here or in Slack and I'll add you.

  3. gziolo commented on May 10, 2018

    @gziolo
    Member

    I would be happy to see something like this helping with changelog files. 👍

  4. aduth commented on May 23, 2018

    @aduth
    Member

    This should also be codified in CONTRIBUTING.md. Also mention of when CHANGELOG.md edits should be made (as part of proposed changes, or prior to release).

    Related discussion: https://github.com/WordPress/packages/pull/128/files#r190238611

  5. ntwb commented on Jul 9, 2018

    @ntwb
    MemberAuthor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions