Releaes and release tags

[buhtz]

I try to understand your section about releases. https://common-changelog.org/#22-release I am not sure why the version is surrounded by brackets [ ... ]. Is it because Microsoft GitHub will render this as a link to the release tag if it exists?

But it doesn't work in my repo. I tried. See the beginning of the readme. https://github.com/bit-team/backintime/tree/buhtz-experiment

I also tried this with a repo at a forgjo (gitea) hoster. The tag is not rendered as a link. https://codeberg.org/buhtz/hyperorg/src/branch/latest/CHANGELOG.md

[vweevers]

That's a markdown feature. See https://daringfireball.net/projects/markdown/syntax#link ("reference-style links").

Example: https://raw.githubusercontent.com/Level/transcoder/main/CHANGELOG.md

[buhtz]

I am not sure if I got your point. Your example:

# Changelog

## [1.0.1] - 2021-11-26

[1.0.1]: https://github.com/Level/transcoder/releases/tag/v1.0.1

Does this mean I always need this last line so that the markdown renderer knows what link is behind [1.0.1]?

The problem is that your common-changelog docu do not mention this or show it in its example. The section I was pointing to also is not congruent. It shows a syntax with <version> but an example with [1.0]. It is confusing.

[vweevers]

Does this mean I always need this last line so that the markdown renderer knows what link is behind [1.0.1]?

Yes, unless you use inline links, like so:

## [1.0.1](https://github.com/Level/transcoder/releases/tag/v1.0.1) - 2021-11-26

Which will be rendered the same as:

## [1.0.1] - 2021-11-26

[1.0.1]: https://github.com/Level/transcoder/releases/tag/v1.0.1

The problem is that your common-changelog docu do not mention this

Right. I will add a link to a Markdown guide to address this, and I will also mention in the Prerequisites section that some familiarity with Markdown is assumed (because explaining Markdown itself is out of scope).

It shows a syntax with <version> but an example with [1.0]. It is confusing.

Roger. AFAIK there is no universally agreed-upon (human) notation for the placeholders in ## <version> - <date>. Perhaps ## VERSION - DATE would be less confusing because it avoids introducing new tokens.

[buhtz]

From my perspective as a "user" it would help if you wouldn't mention the reference links. As you said it is optional and up to the maintainer if it is used or not. It is not an element of the "Common Changelog" standard. Maybe you could separate that into another section or document. Tips & Tricks setion. There you could also explain a bit more your "hallmark" tool. I have read its docu and now better understand your workflow. It makes more sense now.

[vweevers]

It is not an element of the "Common Changelog" standard.

I'm not sure about that yet. Markdown syntax (and its many variations and opinions) isn't part of Common Changelog, but readability should be, and reference links help with that IMO.

[buhtz]

Then you should show this linking (inline or as reference) in the example to make that clear. It was not clear to me because I didn't knew about the reference links feature before. I am using inline link usually in markdown files.

[vweevers]

https://github.com/vweevers/common-changelog/pull/14