search

jacksmith15 / changelog-cmd

Tool for managing a changelog in the style of Keep a Changelog.
MIT License
2 stars 0 forks source link

Multiline entries make it fail or are improperly handled #2

Open Mulugruntz opened 3 years ago

Mulugruntz commented 3 years ago

When trying to add a multiline entry with an empty line, it will be inserted correctly. But then, subsequent entries will always fail. Because inserted entries do not need to pass the parser (and also because the parser does not handle multilines correctly).

See like so:

$> changelog init
Please specify the format for release links. For example:

"https://github.com/user/repo/compare/{previous_tag}..{tag}"

Optionally may contain the following vars for substitution:

{tag},{previous_tag}

: https://github.com/user/repo/compare/{previous_tag}..{tag}
Changelog initialised at '/.../CHANGELOG.md'
$> changelog entry -b  changed -m 'This is a **multiline** message

                                                          There\'s even a line 2!'
$> changelog entry -b  changed -m 'This is a normal message!'

ERROR: Could not parse changelog: Invalid changelog at line 18: "    There's even a line 2!"

And the resulting changelog. We can see that the 2nd entry was not inserted.

```markdown # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING ``` How it's rendered (the line is correctly interpreted by markdown):
# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING

Another funny behaviour is with multiline that do not have empty lines (for markdown, that's just plain continuation, almost all the time, with some exceptions).

$> changelog init
Please specify the format for release links. For example:

"https://github.com/user/repo/compare/{previous_tag}..{tag}"

Optionally may contain the following vars for substitution:

{tag},{previous_tag}

: https://github.com/user/repo/compare/{previous_tag}..{tag}
Changelog initialised at '/.../CHANGELOG.md'
$> changelog entry -b  changed -m 'This is a **multiline** message
                                                      <!-- -->
                                                          There\'s even a line 2!'

This time, the line is not empty, as usual the insert worked. And the line is correctly interpreted by markdown.

```markdown # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING ```
# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING

And now, if I add another entry (let's same the same one). It seems successful. However, the existing multiline entries just got rewritten on a single line. And of course, markdown will no longer consider it multiline.

$> changelog entry -b  changed -m 'This is a **multiline** message
                                                      <!-- -->
                                                          There\'s even a line 2!'
```markdown # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING ```
# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning]. Types of changes are: * **Security** in case of vulnerabilities. * **Deprecated** for soon-to-be removed features. * **Added** for new features. * **Changed** for changes in existing functionality. * **Removed** for now removed features. * **Fixed** for any bug fixes. ## [Unreleased] ### Changed * BREAKING This is a **multiline** message There's even a line 2! * BREAKING This is a **multiline** message There's even a line 2! [Unreleased]: https://github.com/user/repo/compare/initial..HEAD [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/ [Semantic Versioning]: http://semver.org/spec/v2.0.0.html [_release_link_format]: https://github.com/user/repo/compare/{previous_tag}..{tag} [_breaking_change_token]: BREAKING

I hope this is more or less clear.

jacksmith15 commented 3 years ago

Thanks for the bug report - I have not added multiline support yet (only single line, with sub entries on subsequent lines).

I think that your above examples will not produce a multiline list item in standard markdown, as an explicit line break is necessary (i.e. two spaces at the end of the first line, or <br>). Either way the tool doesn't currently support this!

And the line is correctly interpreted by markdown.

What tool are you using to parse the markdown?

Mulugruntz commented 3 years ago

@jacksmith15 If you click on details you can see that GitHub's MD correctly interprets it. :-)

jacksmith15 commented 3 years ago

Understood, I want to avoid being specific to GFMD. The breakpoints can be added automatically by the command line however