runtime(doc): Add a Development policy

closes: #18197

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 2d486b6ba9e1bf9f3575e7ff97c76b1325e0a445..50d9b04f6894ca679d48f8f5274ef91a14965588 100644 (file)
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -1,4 +1,4 @@
-*develop.txt*   For Vim version 9.1.  Last change: 2025 Sep 01
+*develop.txt*   For Vim version 9.1.  Last change: 2025 Sep 04
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -13,6 +13,7 @@ Vim.
 2. Design decisions    |design-decisions|
 3. Assumptions         |design-assumptions|
 4. Coding style                |coding-style|
+5. Policy              |design-policy|
 
 See the file README.txt in the "src" directory for an overview of the source
 code.
@@ -728,4 +729,35 @@ OK:            do
            while (cond);
 
 
+==============================================================================
+5. Policy      *design-policy* *new-features* *deprecated-features*
+
+The time between either a new minor (e.g. 9.2.0) or major (e.g. 10.0) version
+is released is called a development cycle.  Within the development cycle each
+single change to the C core will receive a new increased human-readable patch
+number in order to reference each specific patch release.  A typical
+development release cycle may last several years and accumulate about 1500 -
+2500 patch numbers.
+
+Before a release is made, a stability period will be announced. During this
+time, only clear bug fixes, security fixes, documentation changes, translation
+updates and runtime file updates will be accepted (provided they do not
+introduce backwards-incompatible changes), concentrating on polishing up the
+upcoming release.
+
+New features are accepted only within a development cycle, but not within the
+stability period.  During the cycle, new features may be developed and are
+allowed to change, but they must be settled before the cycle closes.
+
+Once a minor release has been made, features included in that release must not
+receive any backwards-incompatible changes.  Later patches are expected to
+preserve compatibility for the C core of Vim.  Runtime files are handled a bit
+more flexibly to give runtime files maintainers a chance to change old
+behaviour.
+
+Within a development cycle, features may be marked as deprecated. Deprecated
+features can be disabled at compile time through an appropriate switch. After
+a new release, deprecated features may be removed completely in a following
+cycle.
+
  vim:tw=78:ts=8:noet:ft=help:norl:

diff --git a/runtime/doc/tags b/runtime/doc/tags
index 3706ffc3a3ccc22cd966a4b982450ea6bfef21dc..7f73f05580e6c8337037cfddabbcffeaf857cfc0 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -6969,6 +6969,7 @@ delete-menus      gui.txt /*delete-menus*
 deletebufline()        builtin.txt     /*deletebufline()*
 deleting       change.txt      /*deleting*
 demoserver.py  channel.txt     /*demoserver.py*
+deprecated-features    develop.txt     /*deprecated-features*
 design-assumptions     develop.txt     /*design-assumptions*
 design-compatible      develop.txt     /*design-compatible*
 design-decisions       develop.txt     /*design-decisions*
@@ -6979,6 +6980,7 @@ design-improved   develop.txt     /*design-improved*
 design-maintain        develop.txt     /*design-maintain*
 design-multi-platform  develop.txt     /*design-multi-platform*
 design-not     develop.txt     /*design-not*
+design-policy  develop.txt     /*design-policy*
 design-speed-size      develop.txt     /*design-speed-size*
 desktop.vim    syntax.txt      /*desktop.vim*
 develop-spell  develop.txt     /*develop-spell*
@@ -9367,6 +9369,7 @@ new-diff-mode     version6.txt    /*new-diff-mode*
 new-encryption version5.txt    /*new-encryption*
 new-evim       version6.txt    /*new-evim*
 new-ex-commands-5.2    version5.txt    /*new-ex-commands-5.2*
+new-features   develop.txt     /*new-features*
 new-file-browser       version6.txt    /*new-file-browser*
 new-file-writing       version6.txt    /*new-file-writing*
 new-filetype   filetype.txt    /*new-filetype*

diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt
index 9e1cb3b17ad05bf43fa698eb9826ca96351fa6bb..1c5d7245b9efc0bbe2f7a7b6aede87cac90c5dd9 100644 (file)
--- a/runtime/doc/vi_diff.txt
+++ b/runtime/doc/vi_diff.txt
@@ -1,4 +1,4 @@
-*vi_diff.txt*   For Vim version 9.1.  Last change: 2025 Sep 02
+*vi_diff.txt*   For Vim version 9.1.  Last change: 2025 Sep 04
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar