`RDoc::Parser::ChangeLog` doesn't handle keep-a-changelog style CHANGELOG correctly

Offen
  • Stimmt etwas nicht?
#1,133 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
markdown, ruby
Bereich
documentation

Rechercherichtung

Beginne bei RDoc::Parser::ChangeLog und reproduziere das Verhalten des rdoc-Befehls mit dem bereitgestellten keep-a-changelog-Snippet aus CHANGELOG.md. Vergleiche die aktuelle GNU-Style-Analyse mit den erwarteten Markdown-Links und bestimme, ob ein Parser oder ein separater Parser beide Stile unterstützen sollte. Erledigt ist die Aufgabe, wenn Links wie v3.0.0 korrekt gerendert werden und die gewünschte Einbindung von Changelogs in generierten Dokumenten geklärt ist.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Background

This is not a "bug", because it says

This parser is meant to parse the MRI ChangeLog, but can be used to parse any # {GNU style ChangeLog}[http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html].

However, when we run rdoc command, it automatically parses CHANGELOG.md file and outputs some wrong results. This is done by default so it's not a desired behavior.

Problem

When parsing a markdown snippet like below:

## [3.0.0] 2023-10-11

### IMPORTANT

**This release contains an important bug fix that can cause data corruption.**
**If you're using Ruby 3, it's highly recommended to upgrade to [v3.0.0](https://rubygems.org/gems/alba/versions/3.0.0)**
**If you're using Ruby 2, please upgrade to [v2.4.2](https://rubygems.org/gems/alba/versions/2.4.2) that contains bug fix only as soon as possible.**

it should create a link for v3.0.0 since it's a valid markdown syntax (GitHub renders it as a link, for example, see https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md#300-2023-10-11).

However, the resulted HTML is:

<h2 id="label-5B3.0.0-5D+2023-10-11">[3.0.0] 2023-10-11<span><a href="#label-5B3.0.0-5D+2023-10-11">&para;</a> <a href="#top">&uarr;</a></span></h2>

<h3 id="label-IMPORTANT">IMPORTANT<span><a href="#label-IMPORTANT">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p><strong>This release contains an important bug fix that can cause data corruption.</strong> <strong>If you’re using Ruby 3, it’s highly recommended to upgrade to {v3.0.0}[https://rubygems.org/gems/alba/versions/3.0.0]</strong> <strong>If you’re using Ruby 2, please upgrade to {v2.4.2}[https://rubygems.org/gems/alba/versions/2.4.2] that contains bug fix only as soon as possible.</strong></p>

The link parts are not rendered correctly.

Solution

The comment in this parser says it's for GNU style changelog only, but I believe most projects use keep a changelog style. They don't look compatible.
So we have two ways. One is to improve the current changelog parser so that it can parse both styles. Another is to create another parser for keep-a-changelog style specific.

We can also discuss if including changelog into a resulted documents is desired or not. YARD doesn't include it, so maybe nobody wants it.

Vorherrschende Sprache
Ruby
Sterne
928
Forks
470
Ø Merge
2 T. 4 Min.
Gemergte PRs (30 T.)
13

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus ruby/rdoc

Alle Issues in ruby/rdoc

Ähnliche Issues

Weitere Issues zu Ruby

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.