From bfda9ec31946d2d587e41f3d969e4f6056e2f99d Mon Sep 17 00:00:00 2001 From: Pablo Hoffman Date: Tue, 12 Jul 2011 19:53:23 -0300 Subject: [PATCH] added clarification about scrapy versioning including the recently adopted odd/even versioning scheme --HG-- rename : docs/api-stability.rst => docs/versioning.rst --- docs/api-stability.rst | 34 ------------------------------ docs/index.rst | 4 ++-- docs/versioning.rst | 47 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 49 insertions(+), 36 deletions(-) delete mode 100644 docs/api-stability.rst create mode 100644 docs/versioning.rst diff --git a/docs/api-stability.rst b/docs/api-stability.rst deleted file mode 100644 index f415bd8fa..000000000 --- a/docs/api-stability.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _api-stability: - -============================ -Versioning and API Stability -============================ - -API stability is one of Scrapy major goals. - -Versioning -========== - -When Scrapy reaches 1.0, each release will consist of three version numbers: - - * major - big, backwards-incompatible changes - * minor - new features and backwards-compatible changes - * micro - bug fixes only - -Until Scrapy reaches 1.0, minor releases (0.7, 0.8, etc) will follow the same -policy as major releases. - -Sometimes the micro version can be omitted, for brevity, when it's not -relevant. - -API Stability -============= - -Methods or functions that start with a single dash (``_``) are private and -should never be relied as stable. Besides those, the plan is to stabilize and -document the entire API, as we approach the 1.0 release. - -Also, keep in mind that stable doesn't mean complete: stable APIs could grow -new methods or functionality but the existing methods should keep working the -same way. - diff --git a/docs/index.rst b/docs/index.rst index 65621eaa6..779647030 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -221,13 +221,13 @@ All the rest :hidden: contributing - api-stability + versioning experimental/index :doc:`contributing` Learn how to contribute to the Scrapy project. -:doc:`api-stability` +:doc:`versioning` Understand Scrapy versioning and API stability. :doc:`experimental/index` diff --git a/docs/versioning.rst b/docs/versioning.rst new file mode 100644 index 000000000..cbe670b35 --- /dev/null +++ b/docs/versioning.rst @@ -0,0 +1,47 @@ +.. _versioning: + +============================ +Versioning and API Stability +============================ + +Versioning +========== + +Scrapy uses the `odd-numbered versions for development releases`_. + +There are 4 numbers in a Scrapy version: *A.B.C.D* + +* *A* is the major version. This will rarely change and will signify very + large changes. So far, only zero is available for *A* +* *B* is the release number. This will include many changes including features + and things that possible break backwards compatibility. Even Bs will be + stable branches, and odd Bs will be development. +* *C* is the bugfix release number, but it has been recently deprecated of + favor of using the revision number (*D*) +* *D* is the revision number of the Mercurial repo from where the release was + taken + +For example: + +* *0.12.0.2542* is the stable release *12* at revision *2542* (safe to use in + production) +* *0.13.0.2691* is the development release *13* at revision *2691* (use with + care in production) + +API Stability +============= + +API stability is one of Scrapy major goals for the *1.0* release, which doesn't +have a due date scheduled yet. + +Methods or functions that start with a single dash (``_``) are private and +should never be relied as stable. Besides those, the plan is to stabilize and +document the entire API, as we approach the 1.0 release. + +Also, keep in mind that stable doesn't mean complete: stable APIs could grow +new methods or functionality but the existing methods should keep working the +same way. + + +.. _odd-numbered versions for development releases: http://en.wikipedia.org/wiki/Software_versioning#Odd-numbered_versions_for_development_releases +