search

vweevers / remark-changelog

Lint or fix a changelog written in markdown, following Keep A Changelog. Superseded by remark-common-changelog.
MIT License
6 stars 0 forks source link

False positive for latest-definition-first #17

Open jrfnl opened 2 years ago

jrfnl commented 2 years ago

Given the following changelog:

# Changelog

All notable changes to this project will be documented in this file.

This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses [Semantic Versioning](http://semver.org/).

## [Unreleased]

_Nothing yet._

## [1.0.0-alpha3] - 2022-04-01

Some notes.

### Added

* Something added.

## [1.0.0-alpha2] - 2022-03-01

### Changed

* Something changed.

## 1.0.0-alpha1 - 2022-02-01

Introduction.

### Added

Summary of what is included in the initial release.

[Unreleased]:   https://github.com/jrfnl/bug-report-reproduction-scenarios/compare/1.0.0-alpha3...HEAD
[1.0.0-alpha3]: https://github.com/jrfnl/bug-report-reproduction-scenarios/compare/1.0.0-alpha2...1.0.0-alpha3
[1.0.0-alpha2]: https://github.com/jrfnl/bug-report-reproduction-scenarios/compare/1.0.0-alpha1...1.0.0-alpha2

[Plugin]: https://github.com/Some/repo

[`ClassName`]: https://link-to-external.com/documentation.html

I'm receiving the following warning:

CHANGELOG.md
  1:1-45:1  warning  Definitions must be sorted latest-first  latest-definition-first  remark-changelog

While I expected

No warning.

It looks like the analysis gets confused over additional links after the definition links for the releases, though I'm not sure what exactly it's getting confused over. Removing one or the other of the links after the definition links removes the error, but that's clearly not a solution.

How to reproduce

I've set up a reproduction scenario in this repo/branch: https://github.com/jrfnl/bug-report-reproduction-scenarios/tree/remark-changelog/latest-definition-first

Relevant commit: https://github.com/jrfnl/bug-report-reproduction-scenarios/commit/3f37a8d81cdf96dadc681ecb16525142a0841dc7

The issue can also be seen in the GitHub Actions run transcript.

vweevers commented 2 years ago

Run it with the fix: true option, then we can see what the expected order is. The other definitions (anything that's not a semver-valid version) should be sorted lexicographically.

PS. I'm likely to deprecate this module in favor of remark-common-changelog.

jrfnl commented 2 years ago

Run it with the fix: true option, then we can see what the expected order is.

Just did and weirdly enough... that says there are no errors to fix and the git diff shows nothing either.

Commit: https://github.com/jrfnl/bug-report-reproduction-scenarios/commit/82c6721b516de5c671c6213b8d307fcffefc87cd

Run transcript (you will need to fold out the "Run with fixing" and "git diff" sections as they don't fail): https://github.com/jrfnl/bug-report-reproduction-scenarios/runs/6055739351?check_suite_focus=true

The other definitions (anything that's not a semver-valid version) should be sorted lexicographically.

Sorry, I don't know what that means (and googling it didn't help, i.e "the practice of dictionary making" - what does that mean in practice ?).

The other definitions in the changelog for the project where I noticed this and where those links are below the version release links, are ordered in three groups (which make sense to me):

  1. Links to external projects.
  2. Links to specific pages in the documentation website for this codebase.
  3. Links to GitHub profiles for contributors.

Within those subsections, the links are ordered, either alphabetically or for [2] based on the documentation order.

PS. I'm likely to deprecate this module in favor of remark-common-changelog.

I've just been reading through the Common Changelog website, especially the "Differences with Keep a Changelog" section. While I like some of the improvements, I don't like others (like no longer having a Deprecated section), so that actually strengthens my request in #18 to have an option to ignore individual rules.

I'd much prefer to use an actively maintained package versus an archived package, but would only be able to switch over if I could (selectively) ignore particular rules.

vweevers commented 2 years ago

Just did and weirdly enough... that says there are no errors to fix and the git diff shows nothing either.

OK, that's starting to sound like a real bug. I'll have a look later (thanks for the repro scenario, that will be very helpful).

While I like some of the improvements, I don't like others

It's still a draft and always open to suggestions. Feel free to open issues in https://github.com/vweevers/common-changelog so we can discuss them. For example, I'm not opposed to restoring Deprecated, I just never used it myself which means I wouldn't be able to describe it properly.

jrfnl commented 2 years ago

While I like some of the improvements, I don't like others

It's still a draft and always open to suggestions. Feel free to open issues in https://github.com/vweevers/common-changelog so we can discuss them. For example, I'm not opposed to restoring Deprecated, I just never used it myself which means I wouldn't be able to describe it properly.

Well, if the remark checker would allow for the ability to selectively ignore specific rules, the standard doesn't need to be changed 😇 😉