From fa6f3948e52f2d0a9ac7202885e9cdd27f8b6637 Mon Sep 17 00:00:00 2001 From: lizroth <30636882+lizroth@users.noreply.github.com> Date: Tue, 21 Aug 2018 14:21:51 -0700 Subject: [PATCH 1/6] Add pull request template. --- .github/PULL_REQUEST_TEMPLATE.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..ab40d21d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,6 @@ +*Issue #, if available:* + +*Description of changes:* + + +By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. From 97a6f8aa80320926a7eb4e2a1213c19a5cb54a81 Mon Sep 17 00:00:00 2001 From: lizroth <30636882+lizroth@users.noreply.github.com> Date: Thu, 23 Aug 2018 13:44:38 -0700 Subject: [PATCH 2/6] Clarifications to versioning policy. * Explicit callout of version change behavior. * Explicit callout of Z notices for upcoming breaking changes. * Try to simplify language. --- VERSIONING.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/VERSIONING.rst b/VERSIONING.rst index 517d9f9b..dd00e53b 100644 --- a/VERSIONING.rst +++ b/VERSIONING.rst @@ -2,18 +2,24 @@ Versioning Policy ***************** -We will use a three-part X.Y.Z (Major.Minor.Patch) versioning definition with the following meanings. +We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition as follows: -* X (Major) version changes cover changes to the code-base that are expected to break backwards compatibility. -* Y (Minor) version changes cover moderate changes. These include significant (non-breaking) feature additions and might contain changes which break backwards compatability. If there are breaking changes, they will be explicitly stated in the release notes. -* Z (Patch) version changes cover small changes. They will not break backwards compatibility. +* **X (Major)** version changes are significant and expected to break backwards compatibility. +* **Y (Minor)** version changes are moderate changes. These include: + * Significant non-breaking feature additions. + * Potentially breaking changes. Any such changes will be explicitly stated in the release notes. + * Changes to our package's declared dependency versions. +* **Z (Patch)** version changes are small changes. They will not break backwards compatibility. + * Where possible, we will advise of upcoming breaking changes with warnings in a Z release. What this means for you ======================= -We definitely recommend always running on the most recent version of our code. This is how we recommend doing so. +We recommend running the most recent version. Here are our suggestions for managing updates: -* X changes will likely require dedicated time and work to incorporate into your code-base. -* Y changes are unlikely to require significant (or any) work to incorporate. If you have good unit and integration tests, they can likely be picked up in an automated manner. -* Z changes should not require any changes to your code and can be picked up in an automated manner. (Good unit and integration tests are always recommended.) +* Expect X changes to require effort to incorporate. +* Expect Y changes not to require significant effort to incorporate. + * If you have good unit and integration tests, these changes are generally safe to pick up automatically. +* Expect Z changes not to require changes to your code. Z changes are intended to be picked up automatically. + * Good unit and integration tests are always recommended. From e627724069f4026f31441bbde56ce90832fe5fc2 Mon Sep 17 00:00:00 2001 From: lizroth <30636882+lizroth@users.noreply.github.com> Date: Thu, 23 Aug 2018 13:50:20 -0700 Subject: [PATCH 3/6] Fixes to RST lists in VERSIONING. --- VERSIONING.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/VERSIONING.rst b/VERSIONING.rst index dd00e53b..960eeabf 100644 --- a/VERSIONING.rst +++ b/VERSIONING.rst @@ -6,10 +6,13 @@ We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition as follows: * **X (Major)** version changes are significant and expected to break backwards compatibility. * **Y (Minor)** version changes are moderate changes. These include: + * Significant non-breaking feature additions. * Potentially breaking changes. Any such changes will be explicitly stated in the release notes. * Changes to our package's declared dependency versions. + * **Z (Patch)** version changes are small changes. They will not break backwards compatibility. + * Where possible, we will advise of upcoming breaking changes with warnings in a Z release. What this means for you @@ -19,7 +22,10 @@ We recommend running the most recent version. Here are our suggestions for manag * Expect X changes to require effort to incorporate. * Expect Y changes not to require significant effort to incorporate. + * If you have good unit and integration tests, these changes are generally safe to pick up automatically. + * Expect Z changes not to require changes to your code. Z changes are intended to be picked up automatically. + * Good unit and integration tests are always recommended. From 366bd1bcae54604baca92d452abacba3f639efa8 Mon Sep 17 00:00:00 2001 From: lizroth <30636882+lizroth@users.noreply.github.com> Date: Thu, 23 Aug 2018 13:56:25 -0700 Subject: [PATCH 4/6] Small language consistency tweaks to VERSIONING. --- VERSIONING.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/VERSIONING.rst b/VERSIONING.rst index 960eeabf..0b9b6462 100644 --- a/VERSIONING.rst +++ b/VERSIONING.rst @@ -8,10 +8,10 @@ We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition as follows: * **Y (Minor)** version changes are moderate changes. These include: * Significant non-breaking feature additions. - * Potentially breaking changes. Any such changes will be explicitly stated in the release notes. + * Potentially backwards incompatible changes. Any such changes will be explicitly stated in the release notes. * Changes to our package's declared dependency versions. -* **Z (Patch)** version changes are small changes. They will not break backwards compatibility. +* **Z (Patch)** version changes are small changes. These changes will not break backwards compatibility. * Where possible, we will advise of upcoming breaking changes with warnings in a Z release. From 874b281dc05daf5bf58decbbcdc5caa145936a0e Mon Sep 17 00:00:00 2001 From: June Blender Date: Thu, 23 Aug 2018 14:24:44 -0700 Subject: [PATCH 5/6] Update VERSIONING.rst --- VERSIONING.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/VERSIONING.rst b/VERSIONING.rst index 0b9b6462..9f5b7372 100644 --- a/VERSIONING.rst +++ b/VERSIONING.rst @@ -2,30 +2,30 @@ Versioning Policy ***************** -We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition as follows: +We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition, as follows: * **X (Major)** version changes are significant and expected to break backwards compatibility. * **Y (Minor)** version changes are moderate changes. These include: * Significant non-breaking feature additions. - * Potentially backwards incompatible changes. Any such changes will be explicitly stated in the release notes. - * Changes to our package's declared dependency versions. + * Any change to the version of a package dependency. + * Possible backwards-incompatible changes. These changes will be noted and explained in detail in the release notes. * **Z (Patch)** version changes are small changes. These changes will not break backwards compatibility. - * Where possible, we will advise of upcoming breaking changes with warnings in a Z release. + * Z releases will also include warning of upcoming breaking changes, whenver possible. What this means for you ======================= We recommend running the most recent version. Here are our suggestions for managing updates: -* Expect X changes to require effort to incorporate. -* Expect Y changes not to require significant effort to incorporate. +* X changes will require some effort to incorporate. +* Y changes will not require significant effort to incorporate. * If you have good unit and integration tests, these changes are generally safe to pick up automatically. -* Expect Z changes not to require changes to your code. Z changes are intended to be picked up automatically. +* Z changes will not to require any changes to your code. Z changes are intended to be picked up automatically. * Good unit and integration tests are always recommended. From 363a881a2ad79047fb35dd380359fb153ef1132c Mon Sep 17 00:00:00 2001 From: lizroth <30636882+lizroth@users.noreply.github.com> Date: Thu, 23 Aug 2018 14:29:47 -0700 Subject: [PATCH 6/6] Additional minor tweaks/cleanup to VERSIONING.rst. --- VERSIONING.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/VERSIONING.rst b/VERSIONING.rst index 9f5b7372..cbca7763 100644 --- a/VERSIONING.rst +++ b/VERSIONING.rst @@ -8,12 +8,12 @@ We use a three-part X.Y.Z (Major.Minor.Patch) versioning definition, as follows: * **Y (Minor)** version changes are moderate changes. These include: * Significant non-breaking feature additions. - * Any change to the version of a package dependency. + * Any change to the version of a dependency. * Possible backwards-incompatible changes. These changes will be noted and explained in detail in the release notes. * **Z (Patch)** version changes are small changes. These changes will not break backwards compatibility. - * Z releases will also include warning of upcoming breaking changes, whenver possible. + * Z releases will also include warning of upcoming breaking changes, whenever possible. What this means for you ======================= @@ -25,7 +25,7 @@ We recommend running the most recent version. Here are our suggestions for manag * If you have good unit and integration tests, these changes are generally safe to pick up automatically. -* Z changes will not to require any changes to your code. Z changes are intended to be picked up automatically. +* Z changes will not require any changes to your code. Z changes are intended to be picked up automatically. * Good unit and integration tests are always recommended.