[WIP]: Update contributing #1096

joshbruce · 2018-02-28T04:58:00Z

Marked version: 0.3.17

Description

Moving this comment from @intcreator here to continue the broader conversation on helping new contributors get up to speed with marked.

Contributor

Test(s) exist to ensure functionality and minimize regresstion (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.

Draft GitHub release notes have been updated.
cm_autolinks is the only failing test (remove once CI is in place and all tests pass).
All lint checks pass (remove once CI is in place).
CI is green (no forced merge required).
Merge PR

joshbruce · 2018-02-28T05:03:28Z

@intcreator: If you would like to talk privately, we can find a different venue, but you're one of the first to ask regarding new contributor on-boarding; so, wanted to acknowledge that and get to know the issues you're having a bit more. We can also try something other than text-based communication, if you would prefer.

intcreator · 2018-02-28T07:29:04Z

That looks like a good start.

Browser compatibility: We should probably support modern browsers (Chrome, Firefox, Edge, and Safari current and previous two versions) and (sigh) IE 11. As far as I know twice as many people still use IE as Edge. I think that set of browsers is pretty standard. Vue and React support that same set of browsers except they go back to IE 9. If anyone really wants to, we can make it happen, but IE 11 is probably ~~painful~~ far enough.

Node support: I know less about what versions of Node are currently in widespread use. Perhaps we can support the oldest version supported by Node.js itself? Node 4 will be in maintenance until April so I wouldn't mind passing it by. Node 6 will enter maintenance in April and continue until April 2019 so maybe we can start there.

joshbruce · 2018-02-28T13:47:51Z

@intcreator: Thanks!

I updated the Submitting PRs continued section to account for where we are right now. Let me know your reaction to that.

Also added the The marked architecture section. For that one, if you had to guess, how would you describe each of the parts that have the ellipses (...)?

Tagging @styfle as well for situational awareness and silent partner for now.

UziTech · 2018-02-28T14:16:49Z

Right now I'm pretty sure marked works all the way back to IE8 (some people just don't have enough XP) and our travis-ci runs node 0.10. I think those are good limits for 0.x

Node 6 is the first to support 99% of ES6. I agree with following the lifecycle of node.

I would say that starting with 2.x we only support the latest evergreen browsers (i.e. not IE) and follow node lifecycles (so probably Node 6)

styfle · 2018-02-28T14:28:19Z

I would say that starting with 2.x we only support the latest evergreen browsers (

Which browsers should be supported for 1.x then?

UziTech · 2018-02-28T14:43:23Z

same as 0.x

joshbruce · 2018-02-28T14:56:37Z

This is interesting to me from the perspective of the CLI (not a browser)...we're not really dependent on the browsers per se, yeah? Instead we are dependent on the JS engine running marked (browsers just happen to come with an engine), just a thought (could totally be wrong, if I am let me know).

UziTech · 2018-02-28T15:07:45Z

You are correct. The browser/node version just comes with a certain JS engine that runs marked.

That is why browsers started auto updating so we can just say we support the latest stable version of each browser.

Wouldn't it be awesome if node started auto updating 🤣

intcreator · 2018-02-28T15:19:03Z

I think it would also be a good idea to mention which Markdown specifications Marked will adhere to and whether or not Marked can add features with flags or maintain itself as an easily extensible base.

The README mentions that both CommonMark and GFM are supported, but I would go into a little more detail on the mechanics. For example, these questions come to mind:

Do we always start to adhere to the latest version of the spec immediately or wait to adopt it at a certain version/milestone?
What happens when a user uses CommonMark vs GFM under the hood?
Do we have plans for supporting other flavors/dialects of Markdown?

Edit: I just discovered USAGE_EXTENSIBILITY.md, which may be a better home for some of this information.

joshbruce · 2018-02-28T15:25:22Z

@UziTech: Funny story. I'm on a project where the platform automatically updated Node for security - broke all our stuff...so, not sure I can come with you on the autoupdate; unless we're strictly speaking about the JS engine. 😝

@intcreator: Let's put a pin in that. Gonna create an issue.

joshbruce · 2018-02-28T15:38:44Z

@intcreator: Just to make sure this was seen and is covered (we sometimes get sidetracked and lose a request in the excitement of the conversation and collaboration).

Also added the The marked architecture section. For that one, if you had to guess, how would you describe each of the parts that have the ellipses (...)?

styfle · 2018-02-28T15:42:05Z

same as 0.x

@UziTech If we're not dropping support for anything in 1.0.0 then what is the breaking change? And what is the timeline to release 1.0.0?

UziTech · 2018-02-28T15:53:52Z

what is the breaking change?

Most likely a bunch of stuff

A lot of projects that I have seen depend on marked use a specific version (i.e. "0.3.17") because something could easily break while everything is changing (spec support, etc.)

The idea behind v1.x is that dependents can finally use "^1.0.0" and not have to worry about us deciding that we are or aren't going to support a spec.

intcreator · 2018-02-28T15:56:04Z

The first two FAQs in Semantic Versioning suggest to me that 1.0 doesn't require breaking change but rather signifies a stable release/API.

Nevertheless, I'm sure if we get Marked where we want by 1.0, it will break something. It's software after all...

@joshbruce I'm kind of at a dead end on architecture. I really don't understand what's going on, so I think it would be invaluable to have a previous contributor or two write and inspect that section for accuracy.

joshbruce · 2018-02-28T16:28:29Z

@intcreator: Fair. Thanks for everything so far. Keep going!

@UziTech and @styfle: Anyone we can ask (or beg)? Maybe @Nalinc from #746

Just to make it easier to see the ask:

What is the single responsibility or purpose of the things identified with ellipses (...)??

joshbruce · 2018-02-28T22:39:47Z

All right @intcreator, @UziTech, @styfle, and @davisjam - My guesses on what the single responsibility of the objects do is in...am I wrong, do you think. See also #1102

Gonna be done for the day. Need to catch up on some things. Let me know if something explodes. 😂

intcreator · 2018-03-01T05:16:50Z

CONTRIBUTING.md

+3. `edit()`: ...
+4. `resolveUrl()`: ...
+5. `noop()`: ...
+6. `merge():` Merges one or more objects to create a new object. (Why not use Object.assign??)


Object.assign is an ES6 feature according to MDN, so it'll have to wait until 2.0

styfle

This is failing with merge conflicts since we moved our docs.

styfle · 2018-02-28T17:37:42Z

CONTRIBUTING.md

+
+However, marked has also been around for several years and is still one of the most popular Markdown parsers we're aware of. Therefore, we can't ethically just change everything out from under our users before making things right.
+
+### Release 0.x.x (no known issues)


I'm not sure that CONTRIBUTING is the place to talk about releases.
That could be in a wiki roadmap...see TS Roadmap

Additionally, the description of the milestone should actually live on the milestones

joshbruce · 2018-03-26T03:05:48Z

@styfle: Gonna close and make a note to update it later. Thinking Roadmap will be part of the docs?? Trying to minimize the places a developer has to go to learn about all the things.

joshbruce · 2018-03-26T04:53:55Z

See #1162

joshbruce added good first issue Something easy to get started with proposal labels Feb 28, 2018

joshbruce mentioned this pull request Feb 28, 2018

Coding standards #1089

Closed

Beginnings of JS, browsers, and node versions

fe94c14

Josh Bruce added 3 commits February 28, 2018 08:40

Add roadmap + marked architecture

2e61bf2

add var

b1ae1d1

Consistently use backtick to display part of marked

36cc4ad

Missed node versions for post 0.x.x

ede8bdf

Update browser and node versions for 0.x

2487889

joshbruce mentioned this pull request Feb 28, 2018

Markdown flavors #1097

Closed

0.x.x should not change API, 1.0 notifies users of deprecation

974de08

joshbruce mentioned this pull request Feb 28, 2018

Auto-linking - cm_autolinks test #1092

Closed

joshbruce and others added 3 commits February 28, 2018 12:43

Merge branch 'master' into update-contributing

75d6aec

Reorder objects based on processing sequence

555975f

Add merge() definition and question

6197226

Josh Bruce added 2 commits February 28, 2018 17:34

Hypotheses for Objects

b0c5481

block - not inline

7ab383f

intcreator reviewed Mar 1, 2018

View reviewed changes

joshbruce mentioned this pull request Mar 4, 2018

[Architecture]: Capture high-level as-is class diagram #1130

Closed

styfle self-requested a review March 25, 2018 22:34

styfle requested changes Mar 25, 2018

View reviewed changes

joshbruce closed this Mar 26, 2018

joshbruce deleted the update-contributing branch March 26, 2018 03:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP]: Update contributing #1096

[WIP]: Update contributing #1096

joshbruce commented Feb 28, 2018

joshbruce commented Feb 28, 2018

intcreator commented Feb 28, 2018

joshbruce commented Feb 28, 2018

UziTech commented Feb 28, 2018

styfle commented Feb 28, 2018

UziTech commented Feb 28, 2018

joshbruce commented Feb 28, 2018 •

edited

UziTech commented Feb 28, 2018

intcreator commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018

styfle commented Feb 28, 2018 •

edited

UziTech commented Feb 28, 2018

intcreator commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited

intcreator Mar 1, 2018

styfle left a comment

styfle Feb 28, 2018

joshbruce commented Mar 26, 2018

joshbruce commented Mar 26, 2018


		However, marked has also been around for several years and is still one of the most popular Markdown parsers we're aware of. Therefore, we can't ethically just change everything out from under our users before making things right.

		### Release 0.x.x (no known issues)

[WIP]: Update contributing #1096

[WIP]: Update contributing #1096

Conversation

joshbruce commented Feb 28, 2018

Description

Contributor

Committer

joshbruce commented Feb 28, 2018

intcreator commented Feb 28, 2018

joshbruce commented Feb 28, 2018

UziTech commented Feb 28, 2018

styfle commented Feb 28, 2018

UziTech commented Feb 28, 2018

joshbruce commented Feb 28, 2018 • edited

UziTech commented Feb 28, 2018

intcreator commented Feb 28, 2018 • edited

joshbruce commented Feb 28, 2018 • edited

joshbruce commented Feb 28, 2018

styfle commented Feb 28, 2018 • edited

UziTech commented Feb 28, 2018

intcreator commented Feb 28, 2018 • edited

joshbruce commented Feb 28, 2018 • edited

joshbruce commented Feb 28, 2018 • edited

intcreator Mar 1, 2018

Choose a reason for hiding this comment

styfle left a comment

Choose a reason for hiding this comment

styfle Feb 28, 2018

Choose a reason for hiding this comment

joshbruce commented Mar 26, 2018

joshbruce commented Mar 26, 2018

joshbruce commented Feb 28, 2018 •

edited

intcreator commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited

styfle commented Feb 28, 2018 •

edited

intcreator commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited

joshbruce commented Feb 28, 2018 •

edited