Merge pull request twisted#1020 from twisted/9460-incremental-codings…

…tandard 9460 Update coding standard for incremental NEXT magic
zetahernandez · Jun 3, 2018 · 6ac6641 · 6ac6641
2 parents c551aa8 + 67aa160
commit 6ac6641
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 2 deletions.
diff --git a/docs/core/development/policy/coding-standard.rst b/docs/core/development/policy/coding-standard.rst
@@ -344,8 +344,37 @@ Versioning
 ----------
 
 The API documentation should be marked up with version information.
-When a new API is added the class should be marked with the epytext ``@since:`` field including the version number when the change was introduced.
-This version number should be in the form ``x.y`` (for example, ``@since: 15.1``).
+When a new API is added the class should be marked with the epytext `@since: field <http://epydoc.sourceforge.net/manual-fields.html#status>`_ to include the version number when the change was introduced.
+The placeholder string ``Twisted NEXT`` will be `replaced at release time <https://github.com/twisted/incremental#updating>`_ with the appropriate version number.
+For example:
+
+.. code-block:: python
+
+    def bar2baz():
+        """
+        Bazify a bar.
+
+        @since: Twisted NEXT
+        """
+
+The ``@since`` tag cannot be applied to arguments.
+When adding a new argument, indicate the version of introduction on a separate line.
+For example, if the ``swizzle`` keyword argument is added after the release of the above function in Twisted 18.5.0:
+
+.. code-block:: python
+
+    def bar2baz(swizzle=False):
+        """
+        Bazify a bar, with optional swizzling.
+
+        @param swizzle: Activate swizzling.
+
+            Present Since Twisted NEXT
+
+        @type swizzle: L{bool}
+
+        @since: Twisted 18.5.0
+        """
 
 
 Scripts

diff --git a/src/twisted/newsfragments/9460.doc b/src/twisted/newsfragments/9460.doc
@@ -0,0 +1 @@
+The Twisted Coding Standard now contains examples of how to mark up a feature as added in the next Twisted release.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The Twisted Coding Standard now contains examples of how to mark up a feature as added in the next Twisted release.