v3 to v5 changelog and breaking changes

[Vadorequest]

Is there a changelog?

I need to update because of the node12 deprecation. UnlyEd/github-action-await-vercel#74
I'm not sure if I can safely update my action from:
- uses: paulhatch/semantic-version@v3.2.1
to:
- uses: paulhatch/semantic-version@v5.0.2

At https://github.com/UnlyEd/github-action-await-vercel/blob/main/.github/workflows/auto-git-release.yml#L21-L30

[PaulHatch]

Hey @Vadorequest,
Version 4 removed some features that were not behaving correctly, while version 5 was a from-scratch rewrite in TypeScript that added some of them back. The behavior of the inputs available in v3 was essentially unchanged and you should not run into any issues so long as you aren't using branches (as the behavior has changed a bit) or short tags (which were removed). Also note that the input format was changed to version_format.

Additionally, version tags are now sorted by the version itself to find the previous version instead of the order of the commit graph. This was done to improve the behavior of handling merges when using branches for versioning. If for some reason you tagged a repo with a lower version than an earlier tag, this could cause issues, but this is a weird thing to do and generally would be incorrect.

I'll work on including a change log in the near future. In the meantime the release notes also include descriptions of changes.

[Vadorequest]

Thanks for the detailed explanation, I'll see how update goes, it could be smoothly. 🤞

[Vadorequest]

@PaulHatch I tried to upgrade and ran into 2 issues:

• Builds are failing, but the error message isn't so clear as to why
• We rely on the branch option on other projects, and this feature has been removed (it was working well for our use-case, AFAICT)

Would it be possible to get the nodejs v16 upgrade into v3 as well? It shouldn't be an issue, and seem less complicated to do on our side to keep v3 rather than switching to v5, at least for now.

Here is the build error log:

Here is the code:
https://github.com/UnlyEd/github-action-await-vercel/blob/main/.github/workflows/auto-git-release.yml#L21-L33

[PaulHatch]

Hey @Vadorequest,
It looks to me like this line ${{join(steps.next_semantic_version.outputs.*, ' - ')}} is introducing an unescaped newline into your script. There is a new output available in v5 listing the authors of the release which includes newlines.

Branch support hasn't been removed, but the implementation is different now (it just swaps out the lookup to look for branches instead of tags rather than trying to find the merge base between the two). In general supporting branches is quite difficult because there are many different approaches people take when using branches, some of which allow merges from versioned branches back into the trunk for example, while others maybe building on a different branch than the release and still expect that to be reflected in the version.

After experimenting with several different strategies I've come to the conclusion that a single generic "branch mode" is not going to be sufficient to cover all the cases people use, as there are some fundamental conflicts between them. In a future release I'm planning to introduce multiple behavior modes, allowing you do to something like branch_mode: gitflow where there will be multiple strategies to choose from. Also with more explicit specification/documentation to describe how each mode, as right now there's really not much documented

There is an open ticket right now to discuss this feature. Ideas and contribution are welcome, especially since I myself do not currently maintain any projects using branch-based versioning.

Speaking of which, regarding upgrade to v3, probably the best thing to do if you want to keep using v3 for now is fork the repo as this one does not currently use version branches that would allow prior versions to receive updates. While it probably wouldn't be too bad just to throw a branch on to the side and tag it, I wouldn't have time to look at this until at least this weekend.

[Vadorequest]

It looks to me like this line ${{join(steps.next_semantic_version.outputs.*, ' - ')}} is introducing an unescaped newline into your script. There is a new output available in v5 listing the authors of the release which includes newlines.

I believe you're correct, I had the same assumption. I'm not sure how to fix that, besides removing that log.

Branch support hasn't been removed, but the implementation is different now (it just swaps out the lookup to look for branches instead of tags rather than trying to find the merge base between the two). In general supporting branches is quite difficult because there are many different approaches people take when using branches, some of which allow merges from versioned branches back into the trunk for example, while others maybe building on a different branch than the release and still expect that to be reflected in the version.

I understand.
In our case, we use it branches to deploy "alpha" releases and we don't really care if they're not considered after merging those branches back into the main one. We use other branches than "main" because we want each branch to have its own versioning, mostly for the sake of easier tracking on which branch was each release made (we include the branch's name in the release name for non-main branches)
So, this change shouldn't affect us, as far as I understand. It should still work the same way, is that correct?

[PaulHatch]

I haven't really looked too deep into this but the GitHub documentation as I recall always maps values to environment variables, then uses the environment variable for whatever reason(s), and doing that seems to fix your issue:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3.2.0
        with:
          fetch-depth: 0
      - name: Version
        id: version
        uses: paulhatch/semantic-version@v5.0.2
      - name: This Works
        run: |
          echo $INPUTS
        env:
          INPUTS: ${{join(steps.version.outputs.*, ' - ')}}
      - name: This Fails
        run: |
          echo ${{join(steps.version.outputs.*, ' - ')}}

Regarding branches, right now if you have a branch pointing to a commit that is an ancestor of the current head the version will be picked up:

test('Branch Example 1', async () => {
    const repo = createTestRepo({ tagPrefix: '', useBranches: true, versionFormat: "${major}.${minor}.${patch}" });

    repo.makeCommit('Initial Commit');
    repo.makeCommit('Second Commit');
    repo.exec('git checkout -b 1.0.0');
    repo.exec('git checkout master');
    repo.makeCommit('Third Commit');
    repo.makeCommit('fourth Commit');
    const result = await repo.runAction();

    expect(result.formattedVersion).toBe('1.0.1');

}, 15000);

// This also works:

test('Branch Example 2', async () => {
    const repo = createTestRepo({ tagPrefix: '', useBranches: true, versionFormat: "${major}.${minor}.${patch}" });

    repo.makeCommit('Initial Commit');
    repo.makeCommit('Second Commit');
    repo.exec('git checkout -b 1.0.0');
    repo.makeCommit('Fixed Something');
    repo.exec('git checkout master');
    repo.exec('git merge 1.0.0');
    repo.makeCommit('Third Commit');
    repo.makeCommit('fourth Commit');
    const result = await repo.runAction();

    expect(result.formattedVersion).toBe('1.0.1');

}, 15000);

However, if this branch is not connected, it will not:

test('Branch Example 3', async () => {
    const repo = createTestRepo({ tagPrefix: '', useBranches: true, versionFormat: "${major}.${minor}.${patch}" });

    repo.makeCommit('Initial Commit');
    repo.makeCommit('Second Commit');
    repo.exec('git checkout -b 1.0.0');
    repo.makeCommit('Fixed Something'); // moves the branch off master
    repo.exec('git checkout master');
    repo.makeCommit('Third Commit');
    repo.makeCommit('fourth Commit');
    const result = await repo.runAction();

    expect(result.formattedVersion).toBe('0.0.1'); // 1.0.0 was not detected

}, 15000);

This is the behavior change compared to the v3, so if you're doing this you'll run into trouble with the current version.

Just looking at this example I think the possible issues here become evident because there's not a single obvious answer to what this pattern means. If you are doing something like this, maybe that fix commit is supposed to be 1.0.1, while "third commit" should actually be 1.1.0 or even 2.0.0, or hand maybe you publish that fix commit as 1.0.0-hotfix1 and use 1.0.1 as the release number for third commit. On the other hand maybe the 1.0.0 is the start of the release. The action is going to need more information added to the configuration to define what to do here.

I think the best solution here is going to be to have a selection of somewhat opinionated branch behaviors to choose from along with prescriptive documentation and examples of the necessary configuration. I am planning to add some initial documents to issue #76 over the weekend that might be useful.

[Vadorequest]

Thanks, I managed to fix my issues thanks to your help.

Here is my PR, for anybody who would like to take a peek.