search

axodotdev / cargo-dist

📦 shippable application packaging
https://axodotdev.github.io/cargo-dist/
Apache License 2.0
1.47k stars 66 forks source link

Perform line un-wrapping on Markdown release notes #218

Open jwodder opened 1 year ago

jwodder commented 1 year ago

Many authors of CHANGELOG.md/RELEASES.md files (including the maintainers of cargo-dist itself!) insert newlines in long paragraphs in order to wrap them at 80-ish columns. When GitHub renders such Markdown when a user views an .md file in a repository, the newlines are converted into spaces, and wrapping is handled by the user's browser, as we all expect. However, when GitHub renders Markdown in the body of a GitHub release (or in an issue/PR comment or a few other places), the intra-paragraph newlines are rendered as hard line breaks. As a result, a CHANGELOG section like the below:

# v1.2.3 (2023-04-16)

- Foo all the bars, and make sure the gnusto is no longer cleesh.
  Fixes [#1](https://github.com/octocat/Spoon-Knife/issues/1) via
  [PR #2](https://github.com/octocat/Spoon-Knife/pull/2)
  (by [@some-user](https://github.com/some-user))

ends up looking like this in the release that cargo-dist creates:

  • Foo all the bars, and make sure the gnusto is no longer cleesh. Fixes #1 via PR #2 (by @some-user)

I think we can agree this is suboptimal.

I therefore request that cargo-dist either unwrap or be given an option to unwrap Markdown paragraphs when generating release notes.

Gankra commented 1 year ago

Solid idea! cargo-dist currently has no understanding of markdown, but other tools we're working on use comrak for that kind of stuff; hopefully it has something simple for that kind of remapping.

perlun commented 1 year ago

@jwodder Thanks for raising this. Has this bug been reported as well to GitHub? :thinking: I came here since I noted it in completely different, unrelated project...

jwodder commented 1 year ago

@perlun I have not reported it to GitHub, and I am not aware of any such reports, but given that GitHub does this in several places, I'd suspect it's intentional on their end.