Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Bug]: MD024 linting rule (duplicate header) inconsistent with typical changelog structure #505

Open
lucaferranti opened this issue Oct 25, 2024 · 1 comment
Labels
bug Something isn't working

Comments

@lucaferranti
Copy link
Contributor

lucaferranti commented Oct 25, 2024

Description

Typically a changelog has a structure like

## v0.2.0

### Added

## v0.1.0

### Added

i.e. has duplicate headers, which causes the linting to fail.

One way to fix this is to set the parameter siblings_only: true as documented here. This is mentioned specifically for the changelog usercase.

Instead, I see e.g. this repository is bypassing the problem by manually adding : <!-- markdownlint-disable MD024 --> in the CHANGELOG.md. The problem I see with this is that BestieTemplate.jl does not generate any changelog file, hence the package author would need to know themselves to add that magic line to the file, which I think is pretty unlikely (I didn't know about it).

Possible solutions:

  1. use the siblings_only: true parameter
  2. generate an empty changelog file with that line (and a title)

The two solutions don't exclude each other, and a question about adding a changelog to the repo could be a nice addition to the template. Nevertheless, I think it would be good to set siblings_only: true anyway. Even outside changelogs, if I want to e.g. document in a tutorial how two types implement the same interface, the following structure doesn't seem bad practice to me

## Type1

### function `f`

## Type 2

### function `f`

Package Version

0.13.0

Julia Version

0.11

Reproduction steps

have the following markdown file

## v.0.1.0

### Added

- blah

## v0.2.0

### Added

- bluh

and run pre-commit run -a

Relevant log output

No response

Operating System

No response

@lucaferranti lucaferranti added the bug Something isn't working label Oct 25, 2024
@abelsiqueira
Copy link
Collaborator

Oh, I like this, I didn't know about sibling_only, let's definitely add it.

On creating a CHANGELOG.md, I agree. I actually have a wishlist for Changelog/version management. I created #55 for start, but I haven't put my whole wishlist anywhere yet

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

2 participants