How to get fully automated releases, tags, changelog and version numbers for your module (or ProcessWire project).

[bernhard]

TL;DR

Just copy this folder to your module and get fully automated releases, tags, changelog and with one additional line of code (see note below!!) also fully automated version numbers for your PW modules!

Background/long story:

@dotnetic asked me some time ago to use conventional commits for my modules. It was totally new to me, here is the link: https://www.conventionalcommits.org/en/v1.0.0/

I've since adopted that workflow to most of my modules, as it is really just copy and pasting the .workflow folder (and you can simply copy that folder from RockFrontend: https://github.com/baumrock/RockFrontend/tree/main/.github/workflows)

This workflow is great, because

• It will create new releases automatically for you: https://github.com/baumrock/RockMigrations/releases
• It will create new tags automatically for you: https://github.com/baumrock/RockMigrations/tags (This is something that I always forgot and someone was asking for it long time ago, because tags are important if someone uses composer to manage their modules, as far as I understood. Now I can't forget them any more ? )
• It will create a changelog for you automatically: https://github.com/baumrock/RockMigrations/blob/main/CHANGELOG.md
• And last but not least: It will create version numbers automatically for you.

One thing that has always been annoying though is that you have to make sure that the version number that is automatically created matches the version number that you set in your modules .module.php or .info.php file. I have always tended to have everything in my .module.php file, but I just recently noticed that this can lead to problems if you are using PHP8 syntax in your module and the website still runs on PHP version <8 --> You end up getting a fatal error whenever the module is loaded, which totally breaks ProcessWires module backend.

The solution is easy though: Just split your module config into two files - the .module.php with all the module's logic and the .info.php file with only the array that defines the module's info array. Thx for that reminder @BitPoet! Here is the HelloWorld's info.php file with some helpful comments: https://github.com/ryancramerdesign/Helloworld/blob/master/Helloworld.info.php

I did that today for RockMigrations and I realised that you can even fully automate the version numbering of your module, because the conventional commit workflow creates a package.json file that holds the version number in a json string: https://github.com/baumrock/RockMigrations/blob/main/package.json

All you have to do is to grab that json string and write that version into your module's info.php file: https://github.com/baumrock/RockMigrations/blob/92a33ba4e7146a69fb1f52d5b67270b66d9f1e54/RockMigrations.info.php#L5-L9

Afraid of a performance penalty? You don't have to. The module's info is cached by PW and only updated on modules::refresh!

Maybe other module authors like @adrian or @Robin S or @kongondo or @teppo or @netcarver or @Macrura or @flydev want to adopt that workflow as well.

Thx for reading and have a great weekend ? 

[flydev]

Hey, thats great, going to look at this while drinking the coffee. I remember I was using a variable in Duplicator to get the last version number updated automatically but it wasn’t updated/grabbed on the module’s directory. 
 I think it was a constant, not a variable.

Anyway, I try it this morning as I will update some modules, and there is also something that could interest some of you. There is a tool which write commits and keep a sort of standard for it, using OpenAI GPT3 model. 
=> https://github.com/shanginn/git-aicommit.

thanks @bernhard

Edited March 18, 2023 by flydev
tool url

[bernhard]

Hey @flydev great to hear that ? Unfortunately there is an issue with my approach of reading the version number from the json. It will break the version number in the PW modules directory (as you mentioned).

I've asked Ryan to make the modules directory grab the version from package.json if it does not find a version in the info file/method. Hopefully he will add that. The workflow is a huge time and brain saver for me every day. See https://github.com/processwire/processwire-issues/issues/1690

I'm also using this approach now not only for my modules but also for the project's main repository. It's great. I push to dev and github deploys the site to staging. I push to main and github creates a new release and then pushes that release to production ?

[flydev]

Thanks for the reply, I was going to push and see if the modules dir was grabbing the version. Reverting it ? 

To Ryan: please let’s the modules dir taking care of the field `version` of the package.json file, if present.

And just sayin, it will also be a time saver for some profiles using npm at the same time ?

[bernhard]

Two great news!!

1) The module directory now reads module version numbers from package.json files!! Now when using automated workflows like shown above your module's version in the modules directory will automatically be in sync with your module ?

2) Microsoft has just released the github actions extension for VSCode that helps developing and debugging github actions directly from within your IDE!! https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions

[gebeer]

18 minutes ago, bernhard said:

Microsoft has just released the github actions extension for VSCode that helps developing and debugging github actions directly from within your IDE!! https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions

You are making use of this for your deployment workflow with RockMigrations, right?

[flydev]

gud news ?

[bernhard]

I've only just installed it, but it's really nice to have this in my IDE rather than having to go to github. I'm just now realising how often I've done that in the past. Now I have everything I need in VSCode ? 

[wbmnfktr]

On 4/3/2023 at 10:15 AM, bernhard said:

Now I have everything I need in VSCode ? 

How do you sync this whole setup over to a new machine?
The built-in sync or do you reinstall each and everything on another machine?

[bernhard]

I've recently had to switch to a new machine and it was no issue. If I remember correctly I did not sync anything. Sometimes a refresh is a good thing to throw away things that you once installed and never needed again. Things that I'm missing I will realise immediately and just reinstall.

But VSCode recently introduced Profiles (https://code.visualstudio.com/docs/editor/profiles) which would do exactly what you are asking for.

[BrendonKoz]

Maybe another ProcessWire.rocks video soon? ?

[bernhard]

There are so many things that I want to show on video, but it's a lot of work ? And I'm quite busy working on another surprise ? 

But I'm happy when people let me know what they think would be interesting... The camera doesn't talk a lot ? 

[bernhard]

Ok learning from the last 2 days: The action that I'm using uses the "angular" preset which has a slightly different syntax than what is listed on https://www.conventionalcommits.org/en/v1.0.0/

Using the conventionalcommits would be possible (https://github.com/TriPSs/conventional-changelog-action/issues/217), but that would mean we had to "npm install" some dependencies, which is not what I want, as the nice thing with this setup is that everything works out of the box with just adding one file to your repo.

Memo: Breaking changes need to be written with a "BREAKING CHANGE: ..." footer to trigger a major version bump. The exclamation mark syntax like "feat!: ..." does not work.

Thx @dotnetic for your help!

[dotnetic]

8 minutes ago, bernhard said:

Thx @dotnetic for your help!

You are welcome. Thank you very much for your continued work on RockMigrations.

[bernhard]

On 6/2/2023 at 11:45 AM, bernhard said:

Memo: Breaking changes need to be written with a "BREAKING CHANGE: ..." footer to trigger a major version bump. The exclamation mark syntax like "feat!: ..." does not work.

Using version 5.1.0 we can use the conventionalcommits preset without any other dependencies ? 

This is what I'll use from now on in all my modules:

name: Releases
on:
  push:
    branches:
      - main

jobs:
  changelog:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: conventional Changelog Action
        id: changelog
        uses: TriPSs/conventional-changelog-action@v5.1.0
        with:
          preset: "conventionalcommits"
          github-token: ${{ secrets.github_token }}

      - name: create release
        uses: actions/create-release@v1
        if: ${{ steps.changelog.outputs.skipped == 'false' }}
        env:
          GITHUB_TOKEN: ${{ secrets.github_token }}
        with:
          tag_name: ${{ steps.changelog.outputs.tag }}
          release_name: ${{ steps.changelog.outputs.tag }}
          body: ${{ steps.changelog.outputs.clean_changelog }}