Marked Extensions Versioning

[TheSeg]

Marked version: 12.0.0

Describe the bug
Each time marked is updated, this and all other official marked extensions have peer dependency issues. I then have to file an issue per-extension to highlight each extension.

To Reproduce
Steps to reproduce the behavior:

1. Update marked to version 12.0.0 via NPM.
2. Attempt to update any official Marked extension (marked-xhtml, marked-mangle, marked-gfm-heading-id, etc)
3. Confirm various WARN ERESOLVE overriding peer dependency notices.

Expected behavior
I appreciate and understand how development progress with the main project can effect the extensions. The need for strict dependency version check is warranted.

However, there is a lag when official marked extensions support a new version. So this issue is speaking more to the development process of marked. Can the development process incorporate testing and developing the official extensions for coordinated releases? I don't think it's in everyone's best interest to keep making issues per extension project per update. This should be part of the development process.

[UziTech]

Yes! I would love that. If you know how to automate that a PR would be very much appreciated. 😁👍

[TheSeg]

Yes! I would love that. If you know how to automate that a PR would be very much appreciated. 😁👍

With all due respect, I don't think you understand my request. The extensions should be updated in tandem with the core marked release, not an afterthought.

My request is that the part of the process in developing and releasing marked includes paying attention to the extensions. It's guaranteed that when the version number bumps, it immediately invalidates every extension hosted by the marked project, as designed.

To put it another way, official releases of marked are technically release candidates until the extensions are updated to work with the new core marked.

[UziTech]

Marked releases are automated by semantic release. I don't think a good solution is to have a human try to remember to update all extensions. That is the current solution and it is definitely not working.

A much better solution would be to automate the process.

The biggest problem with either of those options is that all extensions are not controlled by one person. I am able to update any for marked and my extensions but there are many extensions made by third parties that we have no control over.

So far the best solution I have is to write a comment on any extension that does not allow the latest and/or create a PR to update the peer dependency and tests when you notice an extension is out of date. This seems to be the current solution of any libraries that allow third party extensions.

[webketje]

Most of the last 4 semver-major releases probably don't even affect most extensions (eg dropping Node.js 16 support or changing some deep internals). Depending on how the release automation is configured, one way to limit the versioning issues is to batch breaking changes in a major release branch instead of immediately pushing them to master and have them auto-release.

I get the automation provides a lot of value to maintainers, but there has to be some concern for user DX and stability, especially when there is no changelog and the git history is full of dependabot bumps and the value marked provides is greatly augmented by the compatibility of third-party extensions. In marked-gfm-heading-id half of the releases just change the marked peerDep and the ratio of human/bot commits is 5/95%.

Easy fix for extensions? "peerDependencies": { "marked": ">= x.x" }. Though this may break in a more distant major version, at least it would avoid millions of "false positives" of users wondering how to solve a (usually non-)issue going through a lengthy investigation only to find there is currently no solution. Not saying this is good, but combined with more thoughtful, batched major version releases and attention for backwards-compat with plugins, it would result in a lot less of user time lost.

[UziTech]

batch breaking changes in a major release branch

Not releasing breaking fixes when they are ready doesn't seem like a good solution. We do already try to include many breaking changes in a major release if they are ready or can wait.

especially when there is no changelog

There is a change log in the releases section

at least it would avoid millions of "false positives"

A false positive (non-breaking changes not automatically introduced) is easy to fix with a PR and no harm but a little extra work. A false negative (breaking change automatically introduced) can be catastrophic and not easily fixed. I would rather err on the side of the former.

[webketje]

To put things into perspective, below is a summary of the last 5 major releases with all of their breaking changes:

2023-09-03 v8 - remove deprecated options
2023-09-09 v9 - remove built files from git repo
2023-11-11 v10 - drop support for node v16
2023-11-29 v11 - Lexer.rules object has been changed for proper typing. Some intermediate rules removed
2024-02-03 v12 - substantial commonmark updates

That's 1 major release/ month. None of these look like they couldn't have waited for a month or 3 to all be batched into 1 or 2 releases, especially since the first 3 just remove functionality. So "We try to include many breaking changes in a major release" is simply not true and voided by the subjective interpretation of "if they are ready or can wait." anyway.

I respect you call the shots here. I needed a clear signal to decide what to do next with @metalsmith/markdown (now trailing marked@latest by 8 major versions in 1 year) - I was in the process of upgrading but our fundamental disagreement on everything maintainer-ship-related from concern for user DX and backward-compatibility vs breaking changes (cf also marked-smartypants issues), to the amount of release automation and the importance of having a clean main branch git history and a versioned changelog file or dist included in the package force me to reconsider. I don't hope to influence the process, I just hope to bring more awareness to its impact.

My 2 cents on the issue at hand was: save yourself AND your users extra work by batching majors - which was rejected.
So next productive suggestion please 😄

[UziTech]

None of these look like they couldn't have waited for a month or 3

I agree but there were users that wanted each of those. We also didn't have a good reason to wait for any of those fixes. And didn't know there would be more breaking changes within 1-3 months.

Keep in mind this is an open source project that is not backed by any company, so everyone that works on this does so in their free time.

now trailing marked@latest by 8 major versions in 1 year

Sorry about that. We do try to limit the amount of breaking changes. This year was a big push to get rid of unnecessary options so the amount of breaking changes will be lower and spread into the extensions.

As far as I know there are no more breaking changes coming soon.

My 2 cents on the issue at hand was: save yourself AND your users extra work by batching majors

We do try to batch breaking changes, if we know there are multiple coming soon. The problem is that we usually don't know about any until they need to be fixed.