Add option to control prefix of version in compare urls

[egil]

When creating a release, I like to use tags with the name vX.Y to indicate an release. In my changelog, I prefer just to have [X.Y] - YYYY-MM-DD as the heading for each release.

That means the current logic for generating the compare urls wont work for me. So I think something like this is needed:

 const unreleasedCompareUrl = `https://github.com/${owner}/${repo}/compare/${compareUrlVersionPrefix}${newVersion}...HEAD`; 
 const previousVersionCompareUrl = previousVersion 
   ? `https://github.com/${owner}/${repo}/compare/${compareUrlVersionPrefix}${previousVersion}...${compareUrlVersionPrefix}${newVersion}` 
   : `https://github.com/${owner}/${repo}/compare/${compareUrlVersionPrefix}${genesisHash}...${compareUrlVersionPrefix}${newVersion}`; 

instead of this:

keep-a-changelog-new-release/src/updateChangelog.ts

Lines 238 to 241 in 9f6c16b

	const unreleasedCompareUrl = `https://github.com/${owner}/${repo}/compare/${newVersion}...HEAD`;
	const previousVersionCompareUrl = previousVersion
	? `https://github.com/${owner}/${repo}/compare/${previousVersion}...${newVersion}`
	: `https://github.com/${owner}/${repo}/compare/${genesisHash}...${newVersion}`;

Its been a very long time since I last played with TypeScript, but ill give this a go if you want a PR on this :)

[thomaseizinger]

Thanks for opening this issue!

We have in fact ran into this problem ourselves but just worked around it by stopping to put v in front of the tag :P

Given that this is indeed quite the common practice, I think a viable solution would be to just add special support for tags that are v prefixed.

I don't know of any other commonly used prefix so I don't think it needs to be configurable.
Additionally, the changelog spec clearly states that the version number needs to be semver which is always without a v prefix.

I'd like to keep the configuration surface small so I'd like everything to be handled internally within the action. Not sure about all the corner cases though. Can you share a bit more about your overall usecase in how you use this action?

[egil]

Thanks for your help.

My usecase is nothing special, update the change log before release. Having a way to toggle v prefix on and off is fine with me. The prefix doesn't have to be configurable, but it should probably be the default since it is the recommended practice to add the v prefix to tags.

[thomaseizinger]

Having a way to toggle v prefix on and off is fine with me.

Ideally, I would want things to "just work" in either case without any additional configuration.

Thinking out loud: if the user passes a version with a v prefix, then we need to strip that for the version number but keep it for the URL. The "weird" part about this solution is that it is no longer just the version then. Shall we rename the input to next_tag / tag? Thinking this further, if we make things tag specific, we could even make the current input optional and read it from the GitHub event that triggered the workflow!

Back to this particular issue 😀

I would be very happy if we can come up with a minimal solution that solves your usecase but at the same time doesn't extend the configuration surface.
If we can't make that happen, we'd have to discuss what a sensible configuration option could look like.

[egil]

If you change the option to next tag then you are assuming that folks will always be creating a tag when they update their changelog. I am not sure that assumption will hold always. To me these are two different concerns, so I think an additional option is worth it.

[thomaseizinger]

Yes, I thought so too (hence my question of how exactly you are using this action).

Happy to roll with a dedicated configuration option for now although I like the above stated idea of adding special support to this action for common usecases like when being triggered through a new tag for example.

If there would only be more time in a single day :)

[egil]

My exact use of the action is this: https://github.com/bUnit-dev/workflows/blob/main/.github/workflows/release.yml

Basically updating the change log before releasing a new version of a lib.

[thomaseizinger]

then you are assuming that folks will always be creating a tag when they update their changelog. I am not sure that assumption will hold always.

Thinking more about this, we already assume that because we are updating the diff URLs at the end of the changelog and therefore assume that whatever is passed in is a tag. I think it is also considered best practice to have a tag per version and the action is called keep-a-changelog-new-release which means it is specifically designed for being used as part of a release workflow and not to generally update the changelog.

Hence, I think the best way forward would be to:

• add a new input named tag
• print a deprecation warning if someone still uses version (but still forward usages of version to tag)
• adjust the code to parse a semver out of the tag (It would be good if users could make tags like v0.1.2-my-component. We had that a couple of times where a single repo tracks multiple things.)

[egil]

Sounds good to me.

[thomaseizinger]

Cool, thanks for bearing with me :D

Are you still open to send a PR for this?

[egil]

I am not hurting right not, since my workaround...

      - name: 🛠️ Update changelog compare URLs
        shell: bash
        run: |
          sed -i -E "s/compare\/([0-9]+\.[0-9]+\.[0-9]+)\.\.\.([0-9]+\.[0-9]+\.[0-9]+)/compare\/v\1...v\2/" CHANGELOG.md
          sed -i -E "s/compare\/([0-9]+\.[0-9]+\.[0-9]+)\.\.\.HEAD/compare\/v\1...HEAD/" CHANGELOG.md

works.

However, I would love to contribute. Is it possible you can outline what changes in which files I need to make them, then I'll give it a go when I have time. I do a regular twitch show, so it might be an good topic to dive into... "contributing to an github action" :)

[thomaseizinger]

However, I would love to contribute. Is it possible you can outline what changes in which files I need to make them, then I'll give it a go when I have time. I do a regular twitch show, so it might be an good topic to dive into... "contributing to an github action" :)

Sure!

I think you will need touch a few parts:

Here is where we parse the inputs. This is where we need to add tag and do all of the parsing. Probably best to keep this functional so we can add nice tests for it here.

This function kicks off the actual changelog transformation, so you will need to pass the new inputs into there.

Overall, I would recommend starting by defining test-cases here. They are used by this test harness. That should give you a nice TDD-style playground to work with :)

[egil]

Thanks. Ill put it on my todo list for one of the upcoming streams :)

[egil]

Thanks for getting this done, and apologies for the radio silence from me.