Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Aug 16, 2021
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ Also read about:
* [Options](https://marked.js.org/#/USING_ADVANCED.md)
* [Extensibility](https://marked.js.org/#/USING_PRO.md)

## Compatibility

**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 :)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

@UziTech UziTech Feb 11, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Installation

**CLI:** `npm install -g marked`
Expand Down
2 changes: 1 addition & 1 deletion docs/PUBLISHING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

Copy link
Contributor Author

@alasdairhurst alasdairhurst Aug 16, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

2. **Minor:** There is at least one new feature added to the public API.
3. **Patch:** Changes that move Marked closer to spec compliance or change a public API that does not break backwards compatibility.