Update docs to clarify Node.js and browser support #1938

alasdairhurst · 2021-02-10T22:32:01Z

Marked version: 2.0.0

Markdown flavor: n/a

Description

Updates docs to describe Node.js support clearly, and clarify the strategy for dropping old versions of Node.js in relation to semver.

Expectation

More clear docs for consumers

Result

n/a

What was attempted

n/a

Contributor

Test(s) exist to ensure functionality and minimize regression (if no tests added, list tests covering this PR); or,
no tests required for this PR.
If submitting new feature, it has been documented in the appropriate places.

Committer

In most cases, this should be a different person than the contributor.

CI is green (no forced merge required).
Squash and Merge PR following conventional commit guidelines.

vercel · 2021-02-10T22:32:06Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/markedjs/markedjs/8wzuVhmbYaeYkB23Zj8TWXY7CgTq
✅ Preview: https://markedjs-git-fork-alasdairhurst-update-version-docs-markedjs.vercel.app

alasdairhurst · 2021-02-10T22:34:27Z

README.md

+
+**Node.js:** Only [current and LTS](https://nodejs.org/en/about/releases/) Node.js versions are supported. End of life Node.js versions may become incompatible with Marked at any point in time.
+
+**Browser:** Not IE11 :)


@UziTech Makes sense to also document the supported browsers but I can't seem to find them after a bit of light digging. Rollup doesn't seem to be using any specific browserlist for transpiling.

it compiles to es5 but some functions (like startsWith) might need polyfills for browsers that don't include them. Hence the note about IE11.

Let's just link to package.json so that can be the canonical place to determine which Node.js versions are supported.

We should also add this to the docs website, probably after the "Supported Markdown specifications" section.

It might be worth to a set a rule which browsers are supported and to enforce it using https://www.npmjs.com/package/eslint-plugin-compat

alasdairhurst · 2021-02-10T23:14:16Z

I noticed the version in component.json was out of sync. Not sure what this is used for or how it should be updated, but i'm guessing this should be matching the package.json version?
https://github.com/markedjs/marked/blob/master/component.json

UziTech · 2021-02-11T00:01:51Z

I noticed the version in component.json was out of sync

I'm not even sure what that is for. Looks like it was for something a long time ago. It should probably just be deleted.

alasdairhurst · 2021-02-11T00:10:14Z

I'm not even sure what that is for. Looks like it was for something a long time ago. It should probably just be deleted.

Had a little dig a bit further and it's this old tool
https://github.com/componentjs/component/blob/master/Readme.md
Deprecated and dead for quite a few years now

package.json

calculuschild · 2021-08-15T05:51:15Z

Is this something we can address as part of #2157 before the V3 update? This PR has been open for quite a long time, and seems like this would be the perfect time to either make this change or officially close it out since it relates to semver issues.

UziTech · 2021-08-15T14:38:17Z

We did update engines for v3 in #2157 so the rest of this PR is just docs changes.

calculuschild · 2021-08-15T17:43:39Z

Right. Just saying since we did change engines we might as well finish updating the related docs as part of the same Marked.js release.

UziTech · 2021-08-16T03:24:17Z

Yes @alasdairhurst if you would rebase this we could update the docs.

alasdairhurst · 2021-08-16T13:52:02Z

@UziTech @calculuschild Rebased.

UziTech

Thanks for sticking with it! 💯

styfle · 2021-08-16T14:20:05Z

docs/PUBLISHING.md

@@ -10,6 +10,6 @@ Marked uses [semantic-release](https://github.com/semantic-release/semantic-rele

 We follow [semantic versioning](https://semver.org) where the following sequence is true `[major].[minor].[patch]`:

-1. **Major:** There is at least one change to the public API or a break from the [CommonMark](https://spec.commonmark.org/current/) or [GFM](https://github.github.com/gfm/) spec.
+1. **Major:** There is at least one change to the public API or a break from the [CommonMark](https://spec.commonmark.org/current/) or [GFM](https://github.github.com/gfm/) spec. Only [current and LTS](https://nodejs.org/en/about/releases/) Node.js versions are supported at any point in time.  A drop in support for a Node.js version may not result in a semver major bump to Marked.


I don't think we plan to do this.

We should do semver major when dropping a version of Node.js and bump the engines field

marked/package.json

Line 87 in e781b18

"node": ">= 12"

Would be great if that happened but I wasn't able to convince everyone on the team :)

I may have missed something though. Not been paying too much attention recently and noticed the 3.0.0 release with the documented breaking change dropping node 10.

@styfle Currently we test Node v12, Node lts (v14), and Node latest (v16). When Node LTS changes to v16 we will be testing Node v12, Node lts (v16), and Node latest (v17), so Node v14 will no longer be tested. If we had a team of people working on this every day I think we could task someone with updating that, but realistically there are three-ish people working on marked, whenever we have extra time.

I think it is good to set the expectations low. Ideally we won't break Node versions that aren't tested and we we will only update the engines field on semver major releases but I still like saying, realistically, we could break older node versions in patches since only lts and latest are guaranteed to be tested and the best fix might be for you to update Node.

github-actions · 2021-08-23T18:49:36Z

🎉 This PR is included in version 3.0.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

vercel bot deployed to Preview February 10, 2021 22:32 View deployment

alasdairhurst commented Feb 10, 2021

View reviewed changes

alasdairhurst changed the title ~~update docs~~ Update docs to clarify Node.js and browser support Feb 10, 2021

UziTech reviewed Feb 11, 2021

View reviewed changes

package.json Outdated Show resolved Hide resolved

UziTech added the category: docs Documentation changes label Feb 11, 2021

UziTech requested review from calculuschild, davisjam, joshbruce and styfle February 11, 2021 00:16

styfle reviewed Feb 12, 2021

View reviewed changes

package.json Outdated Show resolved Hide resolved

styfle linked an issue Apr 7, 2021 that may be closed by this pull request

marked@2.0.0 throws SyntaxError: Invalid regular expression #1937

Closed

This was referenced Jun 16, 2021

Breaking change in 2.1.0 #2106

Closed

fix: fix node v12 #2109

Merged

rebase

4ba3f6f

alasdairhurst force-pushed the update-version-docs branch from ab92e54 to 4ba3f6f Compare August 16, 2021 13:50

vercel bot deployed to Preview August 16, 2021 13:50 View deployment

calculuschild approved these changes Aug 16, 2021

View reviewed changes

UziTech approved these changes Aug 16, 2021

View reviewed changes

UziTech merged commit 6fa4842 into markedjs:master Aug 16, 2021

styfle reviewed Aug 16, 2021

View reviewed changes

github-actions bot added the released label Aug 23, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs to clarify Node.js and browser support #1938

Update docs to clarify Node.js and browser support #1938

alasdairhurst commented Feb 10, 2021 •

edited

vercel bot commented Feb 10, 2021 •

edited

alasdairhurst Feb 10, 2021

UziTech Feb 11, 2021 •

edited

styfle Feb 12, 2021

realityking Apr 12, 2021

alasdairhurst commented Feb 10, 2021

UziTech commented Feb 11, 2021

alasdairhurst commented Feb 11, 2021

calculuschild commented Aug 15, 2021

UziTech commented Aug 15, 2021

calculuschild commented Aug 15, 2021 •

edited

UziTech commented Aug 16, 2021

alasdairhurst commented Aug 16, 2021

UziTech left a comment

styfle Aug 16, 2021

alasdairhurst Aug 16, 2021 •

edited

UziTech Aug 16, 2021

github-actions bot commented Aug 23, 2021


		Node.js: Only [current and LTS](https://nodejs.org/en/about/releases/) Node.js versions are supported. End of life Node.js versions may become incompatible with Marked at any point in time.

		Browser: Not IE11 :)

Update docs to clarify Node.js and browser support #1938

Update docs to clarify Node.js and browser support #1938

Conversation

alasdairhurst commented Feb 10, 2021 • edited

Description

Expectation

Result

What was attempted

Contributor

Committer

vercel bot commented Feb 10, 2021 • edited

alasdairhurst Feb 10, 2021

Choose a reason for hiding this comment

UziTech Feb 11, 2021 • edited

Choose a reason for hiding this comment

styfle Feb 12, 2021

Choose a reason for hiding this comment

realityking Apr 12, 2021

Choose a reason for hiding this comment

alasdairhurst commented Feb 10, 2021

UziTech commented Feb 11, 2021

alasdairhurst commented Feb 11, 2021

calculuschild commented Aug 15, 2021

UziTech commented Aug 15, 2021

calculuschild commented Aug 15, 2021 • edited

UziTech commented Aug 16, 2021

alasdairhurst commented Aug 16, 2021

UziTech left a comment

Choose a reason for hiding this comment

styfle Aug 16, 2021

Choose a reason for hiding this comment

alasdairhurst Aug 16, 2021 • edited

Choose a reason for hiding this comment

UziTech Aug 16, 2021

Choose a reason for hiding this comment

github-actions bot commented Aug 23, 2021

alasdairhurst commented Feb 10, 2021 •

edited

vercel bot commented Feb 10, 2021 •

edited

UziTech Feb 11, 2021 •

edited

calculuschild commented Aug 15, 2021 •

edited

alasdairhurst Aug 16, 2021 •

edited