feat(tools): automate theme changelogs and versioning

[mikachan]

Changes proposed in this Pull Request:

This PR is a proposal to start using conventional commits in our repo, in order to use the format as a way to automate changelog creation and version bumping. It uses Lerna to manage all of the themes as packages, and commitlint to ensure all our commits follow the correct format.

Integration with deploy script

We should integrate this with our current deploy script. My thinking at the moment is that we should do something like this:

• Versioning and changelog updates happen on PR merge via GitHub action (as per changes in this PR)
• Deploy script doesn’t handle version bumps but continues as is otherwise

Or...

• Deploy script calls the new command in this PR (update-themes) instead of the current version bump scripts (we'd need to use conventional commits on all commits in this case I think, as it skips the GH action on PR merge)

Changes to our process

We'd need to start using conventional commits, but we can customise the format if we want to. These are used to determine which changelogs are updated, what’s included in the changelogs, and to facilitate the SemVer version bumping. It's also useful for consistently highlighting breaking changes.

It's actually only the PR title that needs to follow the conventional commit format, so we could just use it there rather than all commits if preferred.

How this will work with the new GitHub action:

• Start a new branch and ideally commit all changes using npm run commit, to catch breaking changes and correct labeling (chore, feat, docs, etc). We can commit manually rather than using this command if preferred.
• Create a PR
• Squash and merge
• Make sure PR title follows conventional commit format (PR title will be linted to ensure it follows this format using this action)
• GitHub action should automatically update changelogs and version bump the themes relating to the changeset in a new commit (the commit will be attributed to the Github actions bot)

Testing

To test locally:

• In lerna.json, remove "allowBranch": "trunk" in order to test on this branch
• Make a change to a theme (e.g. change a readme file)
• Commit these changes following the conventional commit format (e.g. ‘docs(blockbase): update readme’). There's a new command for this: npm run commit, which walks you through the format (instead of needing to remember it)
• Run npm run update-themes
• This should update the changed themes with a new version number and an updated changelog, and then create a new commit with these changes

Questions

• Should we use conventional commits on all commits or just for PR titles? I think I'm leaning towards just using it in PR titles, that way we can remove commitlint and commitizen, and only lint the PR titles. We could add extra instructions to our PR templates to help out with title naming. This also feels like a less significant change to our workflow.
• Consider other ways we could use other Lerna features if we went down this route (managing the link between parent and child themes, running scripts across multiple themes)

[scruffian]

Should we use conventional commits on all commits or just for PR titles?

I think just PR titles is fine, but can that work if we change multiple themes at the same time?

[scruffian]

It looks like the changes go into CHANGELOG.md. Is it possible to change that so they go into readme.txt?

[scruffian]

I prefer this option:

Versioning and changelog updates happen on PR merge via GitHub action (as per changes in this PR) Deploy script doesn’t handle version bumps but continues as is otherwise

I don't think that a deploy script is an ideal place for version numbering - doing it when then code changes is preferable

[scruffian]

Squash and merge Make sure PR title follows conventional commit format (PR title will be linted to ensure it follows this format using this action)

Would it make more sense to prevent merging until the PR title was in the correct format?

[pbking]

I don't think that a deploy script is an ideal place for version numbering - doing it when then code changes is preferable

I don't agree with that.

It's perfectly reasonable for there to be multiple changes to a project (theme) that are encompassed in a single change of version. One changes ~== one version bump.

It could be that a change is delayed and while you THINK it might be deployed in 1.2.3 because reasons might not actually be deployed until 1.2.5. Expecting the version to be changed in the "functionality change" means that further changes to the work are needed STRICTLY for version control; adding overhead to changes that shouldn't belong in that step.

Making changes to the functionality, and changes to the version stamped on a deploy should be discreet actions.

I don't see a better time to determine version number changes than during the deploy action is happening.

Edit: I'm not sure that "on deploy" is best... I'm still moving through and understanding the changes. "on merge" might be the camp I'm in. Just not "on change".

[MaggieCabrera]

Making changes to the functionality, and changes to the version stamped on a deploy should be discreet actions.

I don't see a better time to determine version number changes than during the deploy action is happening.

I agree with you, Jason. When I last made a change in the wpcomsh repo they had a script that was in charge of building the zip for deploy and it would ask you the version you were creating. I think that may be interesting since not always the change is going to be just a patch version bump. Ideally, when you run the deploy script at some point you see what changes are being included and you get a prompt asking if it's a patch, minor or major version bump, and then the version changes accordingly on a per theme basis, since not all changes on the same deploy may be affecting all themes in the same way (though I think that may be a rare exception)

[mikachan]

I think just PR titles is fine, but can that work if we change multiple themes at the same time?

It should do, that's how it's been working in my testing but I've only been testing with all commits as conventional commits (I jumped into doing them everywhere straight away!). I'll test with just the PR titles and see how well it works.

It looks like the changes go into CHANGELOG.md. Is it possible to change that so they go into readme.txt?

Yeah that's right. I hadn't thought too much about this yet other than thinking we could script copying the CHANGELOG.md content into the readme.txts.

Would it make more sense to prevent merging until the PR title was in the correct format?

Yes! I think we could do this with a GH setting, I'll test it out. At the moment it runs the linting when a PR is opened and when the title is edited, but I think it'll still let you merge if the linting fails.

Re when the versioning happens - I think my preference is 'on merge', as that's when we've decided the changes can join the codebase, therefore triggering a new version. But I'm not too opinionated and it's good to see how other projects handle this, like wpcomsh. I'll have a look at some more examples and try some different things out.