Document process for Semver Major Changes and Deprecation Policy

[MylesBorins]

It would be a good idea for us to document a policy for how Semver Major changes are landed and how deprecations are handled.

@isaacs has offered to write some copy, which I think should live in our collaborator guide

@nodejs/ctc please chime in with your thoughts on this.

[evanlucas]

+1 from me. I think that we should have this better documented. We seem to have run into issues a few times now related to breaking changes.

[jasnell]

Having a documented policy would be definitely be good. We do need to make sure, however, that it includes the flexibility for us to make certain necessary semver-major changes without requiring a full deprecation cycle, however, as that would simply make things far too difficult to manage over time.

As a related aside,
One key thing that I would like to see is for every semver-major to be tagged to a specific milestone, and for there to be some mechanism of actively calling special attention to semver-major commits that land in master. Perhaps this can be done via more commit metadata? Currently, in order to know if a commit is semver-major without generating the changelog we have to click through to the underlying PR, which gets a bit tedious. Perhaps the semver-iness of any particular commit can be specified explicitly in the commit metadata itself:

e.g.

Semver: major | minor
PR-URL: ...
Reviewed-By: ...

[ChALkeR]

+1 to both of those — documenting the process and commit comments.

Currently, in order to know if a commit is semver-major without generating the changelog we have to click through to the underlying PR, which gets a bit tedious.

That can also result in false positives, if a «semver-major»/«semver-minor» PR includes several commits, only part of which are actually semver-major/semver-minor. E.g. #7562 was the case.

[MylesBorins]

Changed title as it appears we have documentation for deprecation policy now

edit: lol nvm that was the old issue.