Defining a policy for support for old TypeDoc versions

[Gerrit0]

As much as I'd like people to always upgrade to the newest TypeDoc version when it's released, or shortly after, this isn't always feasible for some projects, which are either stuck on old TypeScript versions or don't have enough dedicated time to resolve any breaking changes.

My policy for support for old versions has always been "upgrade or perish", but despite that, there are a significant number of projects using an old version of TypeDoc. Here's the data from npm for this past week.

In the interest of not totally leaving old projects to die, lots of projects will do security updates for older versions for some period of time. I've said before that I don't have the time to maintain old versions, which remains true, but I'm open to creating a branch for one or maybe two prior minor versions, which will accept patches to fix security vulnerabilities only.

My concerns:

1. Continuing to support older versions will lead to an increase of bug reports for unsupported versions.
2. Accepting patches for security issues will be construed to mean that vulnerabilities will be fixed on discovery for old versions by a maintainer.
3. Partial support for old versions will encourage people to remain on older versions even when an upgrade is available.

It is also worth mentioning here that TypeDoc is (almost always) a development dependency. A vulnerability in it will not affect a production version of your application. A "high severity" vulnerability in Marked (GHSA-rrrm-qjm4-v8hf) can only actually cause you problems if you're running TypeDoc on code which re-exports elements from modules not under your control.

Comments? Mitigation strategies? Things I've missed?

Ref: #1854, cc @bennycode

[bennycode]

Thank you for taking care of my issue. It's super cool that you take it as an example to develop a process for upcoming security fixes. I suggest that you do it like the Node.js team which supports fixes for their latest major version (currently v17.x) and the one prior (currently v16.x).

I suggest that TypeDoc should also make a v1.0 and signal breaking changes by bumping the major version to v2.0 because I was not expecting to see breaking API changes between v0.21 & v0.22. Having this concept of major version / breaking changes would also make it easy to distinguish which versions to get security patches: the latest major & the one from before.

[Gerrit0]

I was not expecting to see breaking API changes between v0.21 & v0.22.

SemVer says:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

TypeDoc is somewhat stricter than this - I avoid breaking changes for patch versions, and only plan to make them for minor versions.

I've avoided going to 1.0 so far because basically everything I've wanted to do has been a breaking change... and am still rather unhappy with the public API. It's getting a lot closer though, probably two to three more rounds of breaking changes and it'll be at a state where breaking changes should become far less necessary to make new features.