From 773e730d80aa5e590ca0fb0fa079a9b4f11d6403 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Fri, 24 Apr 2015 19:28:01 -0500 Subject: [PATCH 1/2] Add new release process to docs Closes #2569 --- docs/community/release-process.rst | 51 ++++++++++++++++++++++++++++++ docs/index.rst | 3 +- 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 docs/community/release-process.rst diff --git a/docs/community/release-process.rst b/docs/community/release-process.rst new file mode 100644 index 0000000000..5fad3f468d --- /dev/null +++ b/docs/community/release-process.rst @@ -0,0 +1,51 @@ +Release Process and Rules +========================= + +.. versionadded:: v2.6.2 + +Starting with the version to be released after ``v2.6.2``, the following rules +will govern and describe how the Requests core team produces a new release. + +Major Releases +-------------- + +A major release will include breaking changes. When it is versioned, it will +be versioned as ``vX.0.0``. For example, if the previous release was +``v10.2.9`` the next version will be ``v11.0.0``. + +Breaking changes are changes that break backwards compatibility with prior +versions. If the project were to change the ``text`` attribute on a +``Response`` object to a method, that would only happen in a Major release. + +Major releases may also include miscellaneous bug fixes and upgrades to +vendored packages. + +Minor Releases +-------------- + +A minor release will not include breaking changes but may include +miscellaneous bug fixes and upgrades to vendored packages. If the previous +version of Requests released was ``v10.2.9`` a minor release would be +versioned as ``v10.3.0``. + +Minor releases will be backwards compatible with releases that have the same +major version number. In other words, all versions that would start with +``v10.`` should be compatible with each other. + +Hotfix Releases +--------------- + +A hotfix release will only include bug fixes that were missed when the project +released the previous version. If the previous version of Requests released +``v10.2.9`` the hotfix release would be versioned as ``v10.2.10``. + +Hotfixes will **not** include upgrades to vendored dependences after +``v2.6.2`` + +Reasoning +--------- + +In the 2.5 and 2.6 release series, the Requests core team upgraded vendored +dependencies and caused a great deal of headaches for both users and the core +team. To reduce this pain, we're forming a concrete set of procedures so +expectations will be properly set. diff --git a/docs/index.rst b/docs/index.rst index 12b24c9e67..e5d07d53e6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -115,10 +115,11 @@ Requests ecosystem and community. community/faq community/recommended - community/out-there.rst + community/out-there community/support community/vulnerabilities community/updates + community/release-process API Documentation ----------------- From f74fc486be3ba16914a46df809ca33fbffb28629 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sat, 25 Apr 2015 09:29:40 -0500 Subject: [PATCH 2/2] Update version number examples. Strip whitespace Also I've included a bit more verbiage around why a major release would happen and some reassurances that they will be rare. --- docs/community/release-process.rst | 43 ++++++++++++++++-------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/community/release-process.rst b/docs/community/release-process.rst index 5fad3f468d..adb86d5c5d 100644 --- a/docs/community/release-process.rst +++ b/docs/community/release-process.rst @@ -3,49 +3,52 @@ Release Process and Rules .. versionadded:: v2.6.2 -Starting with the version to be released after ``v2.6.2``, the following rules +Starting with the version to be released after ``v2.6.2``, the following rules will govern and describe how the Requests core team produces a new release. Major Releases -------------- -A major release will include breaking changes. When it is versioned, it will -be versioned as ``vX.0.0``. For example, if the previous release was -``v10.2.9`` the next version will be ``v11.0.0``. +A major release will include breaking changes. When it is versioned, it will +be versioned as ``vX.0.0``. For example, if the previous release was +``v10.2.7`` the next version will be ``v11.0.0``. -Breaking changes are changes that break backwards compatibility with prior -versions. If the project were to change the ``text`` attribute on a +Breaking changes are changes that break backwards compatibility with prior +versions. If the project were to change the ``text`` attribute on a ``Response`` object to a method, that would only happen in a Major release. -Major releases may also include miscellaneous bug fixes and upgrades to -vendored packages. +Major releases may also include miscellaneous bug fixes and upgrades to +vendored packages. The core developers of Requests are committed to providing +a good user experience. This means we're also committed to preserving +backwards compatibility as much as possible. Major releases will be infrequent +and will need strong justifications before they are considered. Minor Releases -------------- -A minor release will not include breaking changes but may include -miscellaneous bug fixes and upgrades to vendored packages. If the previous -version of Requests released was ``v10.2.9`` a minor release would be +A minor release will not include breaking changes but may include +miscellaneous bug fixes and upgrades to vendored packages. If the previous +version of Requests released was ``v10.2.7`` a minor release would be versioned as ``v10.3.0``. -Minor releases will be backwards compatible with releases that have the same -major version number. In other words, all versions that would start with +Minor releases will be backwards compatible with releases that have the same +major version number. In other words, all versions that would start with ``v10.`` should be compatible with each other. Hotfix Releases --------------- -A hotfix release will only include bug fixes that were missed when the project -released the previous version. If the previous version of Requests released -``v10.2.9`` the hotfix release would be versioned as ``v10.2.10``. +A hotfix release will only include bug fixes that were missed when the project +released the previous version. If the previous version of Requests released +``v10.2.7`` the hotfix release would be versioned as ``v10.2.8``. -Hotfixes will **not** include upgrades to vendored dependences after +Hotfixes will **not** include upgrades to vendored dependences after ``v2.6.2`` Reasoning --------- -In the 2.5 and 2.6 release series, the Requests core team upgraded vendored -dependencies and caused a great deal of headaches for both users and the core -team. To reduce this pain, we're forming a concrete set of procedures so +In the 2.5 and 2.6 release series, the Requests core team upgraded vendored +dependencies and caused a great deal of headaches for both users and the core +team. To reduce this pain, we're forming a concrete set of procedures so expectations will be properly set.