ChangeLog

[confused-Techie]

I've recently started a PR to address and expand our changelog format over on pulsar.

This has sparked a bit more discussion than I had anticipated. So thought it was a smart idea to expand more on here.

With this new ChangeLog format, here are my personal priorities, which seem to be shared by the team:

• Make it easy to see what changes are present in each version, not only of Pulsar, but of all of it's core packages.
• Include an easy to digest (for end users) list of the most notable changes.
• Ensure the best way possible to give proper credits to every contributor.

With that in mind below is the basic format I thought we could write these ChangeLogs in would look like the following:

# ChangeLog 

- Format inspired by [Keep a ChangeLog](...)
- Format defined in [Pulsar Change Log Format](...)
- Project adheres to [Semantic Versioning](...)

## [Unreleased]

- This section could contain the major improvements for end users.
- As a bullet point list, right at the top of the version
- With this version as 'Unreleased' since it has not yet been released. But once it has...
- We would change 'Unreleased' to the version and start a new 'Unreleased' section at the top

### Pulsar
- Removed: Change Tagline [@contributor](link-to-pr)
- Fixed:
- Added:
- Bumped:
- Decaffeinate:
    * With small sections
- Tests:
    * With small sections
- Rebrand:
     * With small sections

Basically each component of the editor would be listed under ### with a bullet point list for the different types of changes listed above.

Then the larger changes that aren't as feature specific, would get the 'With small sections' type syntax.

From there each old version goes below it.

Now for what others have added in the original PR, a big issue is automation of this.

Now it would be somewhat easy to have an action that gets the different PR's with their user and link and add it to it.

The Change Tagline could then be based on the PR title, but that would mean that these titles have to be well written, which won't always be the case.

As I'd love for these Change Taglines to be human readable, I'd instead propose we have a special section at the top of our PR's something like [changelog]("Add support for awesome feature!")\n

This of course could be changed, but would ensure it's always human readable, and if not human readable (one is provided) then it could default to just the contributor and a link to their PR, which we could then manually edit as needed.

The other big hurdle of automatically grabbing these and modifying our CHANGELOG.md is how would we do this for every single repo?

But I'd be happy to hear your comments further from anyone over on PR#166

[confused-Techie]

@sertonix has written a great parsing guide for this, which I think is nearly exactly what I was thinking. So if we all like this format we can include that more so.

And really just now thinking, if we wanted to, we could have the ChangeLog listed on our Org page, and include changes for basically everything, as nearly everything is a core package

[sertonix]

There is currently a small problem.
The changes of the packages are not always in the core yet.
Therefore I suggest that when a version of a package is bumped the changlogs are added to the core changlogs.
Maybe we can add a script for bumping that would automatically include the changlogs.

[sertonix]

So when my specifications are met this script should parse the logs.

Code:

const rawChanglogs = "<changlogs>";
if (!/^# (?>.+)\n(?>\n- .+)+\n\n\n(?>## (?>.+)\n(?>\n- .+(?>(?!:).|:\n  \* .*(?>\n  \* .+)*))+(?>\n\n### .+(?>\n- [A-Z][a-z]*: .+(?>(?!:).|:\n  \* .*(?>\n  \* .+)*))+)*(?>$|\n\n\n))*$/.test(rawChanglogs)) throw new Error("Invalid syntax");
rawChanglogs.split("\n\n\n").slice(1).map( rawVersionChanges => {
  const [rawVersion,rawOverview,...rawPackages] = rawVersionChanges.split("\n\n");
  return {
    version: rawVersion.substring(2).trim(),
    overview: rawOverview.split(/\n(?=-)/g).map( line => {
      const [rawDescription,...rawList] = line.split("\n");
      return rawDescription.endsWith(":") ? {
        description: rawDescription.substring(1,rawDescription.length-1).trim(),
        list: rawList.map( rawListEntry =>
          rawListEntry.trim().substring(1).trim(),
        ),
      } : {
        description: rawDescription.substring(1).trim(),
      };
    }),
    packages: rawPackages.map( rawPackage => {
      const [rawHeading,...rawChanges] = rawPackage.split("\n");
      return {
        name: rawHeading.substring(3).trim(),
        changes: rawChanges.join("\n").split(/\n(?=-)/g).map( line => {
          const [rawDescription,...rawList] = line.split("\n");
          const rawDescription2 = rawDescription.substring(1).trim();
          const type = rawDescription2.split(":",1)[0].trim().toLowerCase();
          return rawDescription.endsWith(":") ? {
            description: rawDescription2.substring(type.length+1,rawDescription2.length-1).trim(),
            list: rawList.map( rawListEntry =>
              rawListEntry.trim().substring(1).trim(),
            ),
            type,
          } : {
            description: rawDescription2.substring(type.length+1).trim(),
            type,
          };
        }),
      };
    }),
  }
});

Example:

For example these changlogs

# Changlog

- General info


## version 3

- overall summary
- and more

### first part
- Fixed: something
- Decaffeinate: longer list:
  * normally reference but could be something different
  * and more

### second project
- Fix: a small fix


## version more

- overall summary
- and more

### first part
- Fixed: something
- Decaffeinate: longer list:
  * normally reference but could be something different
  * and more

### second project
- Fix: a small fix

parse to this:

{
  "version": "version 3",
  "overview": [
    {
      "description": "overall summary"
    },
    {
      "description": "and more"
    }
  ],
  "packages": [
    {
      "name": "first part",
      "changes": [
        {
          "description": "something",
          "type": "fixed"
        },
        {
          "description": "longer list",
          "list": [
            "normally reference but could be something different",
            "and more"
          ],
          "type": "decaffeinate"
        }
      ]
    },
    {
      "name": "second project",
      "changes": [
        {
          "description": "a small fix",
          "type": "fix"
        }
      ]
    }
  ]
}

[Daeraxa]

If a PR closes an issue then maybe we should also add a link to the issue (after the PR link)?

[confused-Techie]

Oh yeah that's an awesome idea

[sertonix]

Could we use this project?