Version 6 roadmap (tracking issue)

[KillyMXI]

Goals for the version 6:

• bringing the package up to date (security fixes, replacing outdated dependencies);
• general cleanup, ensuring the package in a good shape and pleasing to work with;
• backwards compatibility (no client code has to be updated except the package version for this update, assuming it targets a fresh enough Node version);
• fix known formatting issues, in case there are good PRs.

Checklist:

• Bump dependencies to latest versions.
  • And again, before wrapping things up.
• Replace istanbul with nyc (done in my fork).
• Decide on the required Node version.
  • Review dependencies for their requirements.
• Make cli tests work on Windows (done in my fork).
• Readme cleanup, more readable options section (table).
• Fix ol formatting - merge fix(NestedLists): corrected prefix in ol #191, make that badge green again.
• Support multiline blockquote - merge Support multiline blockquote #193.
• Support linkHrefBaseUrl for images - merge use linkHrefBaseUrl for image src too #145.
  • Mention it in Readme.
• Deal with [DOS vulnerability fix] Limit how many DOM nodes get iterated upon #172 - can't merge it directly in the current state, some work required. I also got annoyed by some "Security Analyst" already.
  • OK, input string limit too.
  • Document new options.
• Fix broken example.
• Modernize ESLint rules, get linter happy. This will likely be a point of no return and remaining PRs will be closed. Not a bad thing though - many proposals need more thought applied.
  • Stage 1 - bulk of easy changes.
  • Stage 2 - rest of changes (refactor some ugliest parts).
• JSDoc documentation for exports and options.
• Export htmlToText() and deprecate fromString(). Existing code will keep working.
• Better options merge.
• Allow to define formatting for any tag.
  • Supply a formatter for block-level tags (Not going to change the tags mapping in this release, but at least spare people from defining the same function over and over.)
• Roman numerals support (up to 3999) and letters past z for ordered lists.
• Review coverage reports - there seems to be a couple of places to add tests.
• Review CodeClimate reports.
• Very first character of a converted file is a space character #205 - blocking issue. This requires to rework block/inline tags handling. No easy way around.
• Some visible whitespaces in browser are trimmed in the result #206 rightfully pointed at the mismatch with the way whitespaces are handled in HTML spec. While expanded set of whitespace characters is desired by some subset of users, others might prefer it to be close to spec. This has to be exposed in options, with the default reflecting the spec.
• Reorganize some options.
  • Provide compatibility layer for deprecated options where possible.
• Update docs
  • Changelog.
  • Readme.
  • Contributors and copyright.
  • Add a link to the changelog on top of the readme file.
• Move the repo to it's own org
  • Update internal links
  • Make sure badges still work
• Publish to NPM
  • Update package version before publish

Not included:

• Most of existing PRs. I think some things I initially merged into my fork actually need more thought to put into them. Also, one of the goals of this version is to clean up the code to give ways for more meaningful improvements.

Something for another time:

• Move CLI to a separate package.
• Switch to TypeScript? JSDoc alone is really crude tool and unable to meet the demands for contextual documentation.
• Add a browser example.
• I'm not happy about options.tables - the only tag-specific option left in global options. I have an idea for something that will replace it and help with other things too, but it's not a solid plan yet and can be left for later.

[KillyMXI]

Node requirements:

Dependencies:

package	version	Node version
he	1.2.0	unspecified
htmlparser2	4.1.0	unspecified
minimist	1.2.5	unspecified
lodash	4.17.15	>= 4.0.0

Dev dependencies:

package	version	Node version
chai	4.2.0	>= 4
eslint	6.8.0	^8.10.0 or ^10.13.0 or >=11.10.1
nyc	15.0.1	>= 8.9
mocha	7.11	>= 8.0.0

Node 8.x LTS maintenance ended not too far ago.

>= 8.10.0 looks like a reasonable target.

[minaseem]

Watching this space almost every day. Any plans on the release?

[KillyMXI]

The story since last commits:

I thought I'm almost done and only have to update Markdown files.
But the issue #205 had shown that there is a serious issue that was missing from the tests, and it was a last straw, leaving no hope to to avoid significant refactoring. master should be considered broken at this point, and there is no more rug to hide the technical debt any longer.
This was quite depressing. There are a lot of moving parts...
I keep working on it almost daily but only in small steps. At this moment most of the tests are passing again.
Before I can fix the last tests, I figured I have to address #206 first, because it is very related. This revealed another significant chunk of work to do.

Never ever I felt any closer to this:

But I believe the result will worth the wait time.

I can provide a ko-fi link, but I'm not sure it will buy me enough time from other tasks.

[KillyMXI]

At this moment most of the tests are passing again.

This is quite funny now. Soon after that comment I realized I'm walking in circles again and had to get back to drawing board.

It was the most massive rework but fortunately it did work out fine this time. Although I had to introduce a bit more breaking changes than I would've hoped. (Changelog. Nothing should actually break so the update is safe, but output will differ in some situations.)

Significantly updated code is in repo now.

@mlegenhausen, your participation is needed:

• I've noticed an issue with copyright. There are two copies that are not agree with each other. Better update and leave a single source of truth;
• Since you are not a single major contributor now - consider underlining this fact (in copyright and in readme);
• Consider moving the project to a separate organization;
• Delete #208 since it is clearly used for advertisement purposes. I don't have required rights;
• Once all parties happy and no new issues reported - this can be published to npm. (I also have no control over this. This can be addressed in multiple ways.)

[mlegenhausen]

@KillyMXI first of all thanks for your amazing work and keeping this project alive! I have increased your access level to Admin so you can configure the project as you like. Feel free to remove the werk85 copy right. This project was always intended to be free to use and customize, we never intended to make a business product out of this project. If you can provide me your npmjs.org username I will add you as contributor so you can publish the package by yourself.

[KillyMXI]

@mlegenhausen thank you. It's killy.mxi.

Deciding on the copyright is PitA. At a closer look, just referring to All contributors (https://github.com/werk85/node-html-to-text/graphs/contributors) and relying on a platform tools doesn't seem an acceptable practice. And maintaining a list of all contributors, big or small, within the repository doesn't seem meaningful.

I'd really like the following to become an acceptable practice:

Portions Copyright (c) 2012-2019 werk85 <malte@werk85.de>
Portions Copyright (c) 2020 KillyMXI <https://github.com/KillyMXI>

But I'll put a more conventional email.

Upd: Oh, and looks like extra move is required before I will be able to delete that issue: https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/deleting-an-issue
This is unless I transfer the repository to a separate organization. If no objections on that matter then I will try to transfer the repo to it's own organization.

[KillyMXI]

@mlegenhausen thank you once again. I got the access to npm package.

In case you missed my update (it haven't got an email notification), I'd like to have a verbal confirmation that it is OK to move the repo to it's own organization.

The plan is to have separate repositories for CLI and some web demo later. Plus I still don't have some control over this repository while it is under werk85.

(How the new organization should be named though? It will be "html-to-text" most likely, unless there is a better alternative.)

[mlegenhausen]

@KillyMXI thanks for the clarification of the permission system from github. Yeah seems reasonably to move the project to a new organization to get this flexibility. Thats the OK from me. Do you mind if I create the organization? Even if I don't find the time to maintain the project anymore I feel the need to do this last step 😉

I see that html-to-text is already taken as organization name but it has no members? Is that yours?

[KillyMXI]

Yes, I've created it just before posting the comment. Maybe it was worthless precaution. That's strange that I'm not shown as a member. And I can't see any settings related to this.

Any particular reason you wanted to create the organization? Can we proceed with the one I've created? I've sent you an invite with owner rights.

[mlegenhausen]

Just a sentimental one 😉 but never mind. Thanks!

[KillyMXI]

And I just found the visibility switch in plain sight, lol 🤦‍♂️

[KillyMXI]

Version 6.0.0 is live!