`RDoc::Parser::ChangeLog` doesn't handle keep-a-changelog style CHANGELOG correctly
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- markdown, ruby
- Domain
- documentation
Research direction
Start at RDoc::Parser::ChangeLog and reproduce the rdoc command behavior with the provided CHANGELOG.md keep-a-changelog snippet. Compare the current GNU-style parsing with the expected Markdown links and determine whether one parser or a separate parser should support both styles. Done means links such as v3.0.0 render correctly and the desired inclusion of changelogs in generated documents is settled.
Written by the indexing model from the issue text.
Description
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">¶</a> <a href="#top">↑</a></span></h2>
<h3 id="label-IMPORTANT">IMPORTANT<span><a href="#label-IMPORTANT">¶</a> <a href="#top">↑</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.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 472
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 12
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ruby/rdoc
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
RDoc 8.0.0 gem omits `doc/rdoc/example.rb`, which is referenced by the packaged markup documentationPossibly taken @OskarEichler claimed this 80 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
markdown html excerpt includes link partsPossibly taken @anyingiit claimed this 26 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 66/100
Maintainers usually reply within 1 day
-
Regexp generated from unescaped input in #expand_classPossibly taken @jaynetics claimed this 39 days ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 25/100
Maintainers usually reply within 1 day
Similar issues
-
bug f:request-creation professional
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
mysociety/alaveteli#9733 · 1 comment ·
Maintainers usually reply within 1 day
-
needs verification
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 13 days
-
🐛 bug 👩💻 équipe CE 🧑🏭 entreprises
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
betagouv/conseillers-entreprises#4808 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100