kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-23 20:55:18 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(MAINTAIN): update deprecation policy (#24619)

Browse Source 
docs(MAINTAIN.md): update deprecation policy

Refine a deprecation policy and add another deprecation period in which
a feature is only deprecated via documentation and does not issue a
warning.
This commit is contained in:
Lewis Russell 2023-08-09 16:49:52 +01:00 committed by GitHub
parent c43c745a14
commit 977f9659a7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
MAINTAIN.md
View File

@ -71,16 +71,36 @@ inform users of the change.
In general, when a feature is slated to be removed it should:
1. Be marked deprecated in the _next_ release
- This includes a note in the release notes (include a "Deprecation Warning"
section just below "Breaking Changes")
- Lua features can use `vim.deprecate()`
1. Be _soft_ deprecated in the _next_ release
- Use of the deprecated feature will still work.
- This means deprecating via documentation and annotation (`@deprecated`) only.
- Include a note in `news.txt` under `DEPRECATIONS`.
2. Be _hard_ deprecated in a following a release in which it was soft deprecated.
- Use of the deprecated feature will still work but should issue a warning
(typically via `vim.deprecate()` for Lua features).
- Features implemented in Vimscript or in C will need bespoke implementations
to communicate to users that the feature is deprecated
2. Be removed in a release following the release in which it was marked
deprecated
3. Be removed in a release following the release in which it was hard deprecated
- Usually this will be the next release, but it may be a later release if a
longer deprecation cycle is desired
- If possible, keep the feature as a stub (e.g. function API) and issue an error
when it is accessed.
Example:
```
Deprecation Removal
┆ ┆ ┆
┆ Soft ┆ Hard ┆
┆ Deprecation ┆ Deprecation ┆
┆ Period ┆ Preiod ┆
────────────────────────────────────────────────────────────
Version: 0.10 0.11 0.12
────────────────────────────────────────────────────────────
Old code Old code Old code
+ +
New code New code New code
```
Feature removals which may benefit from community input or further discussion
should also have a tracking issue (which should be linked to in the release