From ba793fa36a1c044ee20021f5c3d2f12a38958c7c Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 15:46:57 +0100 Subject: [PATCH 1/9] added phased deprecation policy --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2254e4cc9..954a6a3719 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,8 @@ - [Please Do's](#please-dos) - [Test against Postgres](#test-against-postgres) - [Postgres with Docker](#postgres-with-docker) +- [Change and Removal of Existing Features](#change-and-removal-of-existing-features) + - [Phased Deprecation Policy](#phased-deprecation-policy) - [Feature Considerations](#feature-considerations) - [Security Checks](#security-checks) - [Add Security Check](#add-security-check) @@ -164,6 +166,26 @@ RUN chmod +x /docker-entrypoint-initdb.d/setup-dbs.sh Note that the script above will ONLY be executed during initialization of the container with no data in the database, see the official [Postgres image](https://hub.docker.com/_/postgres) for details. If you want to use the script to run again be sure there is no data in the /var/lib/postgresql/data of the container. +## Change and Removal of Existing Features + +We want to avoid sudden breaking changes which has been often been pointed out in community feedback. Therefore we intend to follow the [Phased Deprecation Policy](#phased-deprecation-policy) when changing or removing existing features. + +Please consider that Parse Server is just one component in a stack for many developers. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: +- "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change +- less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers +- less feedback on feature, slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on + +### Phased Deprecation Policy + +If you change or remove an existing feature that would lead to a breaking change, consider the following: +1. Only urgent changes with security relevance are allowed to be sudden breaking changes. +2. Use a phased deprecation pattern for all other changes: + - Make the new feature or change optional, if necessary with a new Parse Server option parameter. + - Use a default value that falls back to the existing behavior. + - Add a warning log message to the Parse Server options validation in [Config.js](https://github.com/parse-community/parse-server/blob/master/src/Config.js) that the option value will be deprecated in the future: + > `Warning: The option : will be deprecated in a future release. Use : instead which will become the new default.` +3. Breaking changes are to be collected into the next major release of Parse Server. + ## Feature Considerations ### Security Checks From ef59e2d5ffab56d4b2378620271e3128f5b01522 Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 15:50:38 +0100 Subject: [PATCH 2/9] fixed typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 954a6a3719..e5d06210ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,7 @@ We want to avoid sudden breaking changes which has been often been pointed out i Please consider that Parse Server is just one component in a stack for many developers. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: - "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change - less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers -- less feedback on feature, slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on +- less feedback and slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on ### Phased Deprecation Policy From 5ea2753638422951b0ee0fd6064ddae9050c9aa2 Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 23:38:48 +0100 Subject: [PATCH 3/9] added changelog entry --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40be52734a..3d9141d015 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -98,6 +98,7 @@ ___ - EXPERIMENTAL: Added custom routes to easily customize flows for password reset, email verification or build entirely new flows (Manuel Trezza) [#7231](https://github.com/parse-community/parse-server/issues/7231) - Remove support for Node 10 which has reached its End-of-Life support date (Manuel Trezza) [#7314](https://github.com/parse-community/parse-server/pull/7314) - Remove support for MongoDB 3.6 which has reached its End-of-Life support date (Manuel Trezza) [#7315](https://github.com/parse-community/parse-server/pull/7315) +- Added Deprecation Policy to govern the introduction of braking changes in a phased pattern that is more predictable for developers (Manuel Trezza) [#7199](https://github.com/parse-community/parse-server/pull/7199) ### Other Changes - Fix error when a not yet inserted job is updated (Antonio Davi Macedo Coelho de Castro) [#7196](https://github.com/parse-community/parse-server/pull/7196) - request.context for afterFind triggers (dblythy) [#7078](https://github.com/parse-community/parse-server/pull/7078) From 1df332ae92af85d1e1afd98fff7348112ef86c4b Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 23:39:06 +0100 Subject: [PATCH 4/9] some rewording --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5d06210ed..52726127cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,8 +11,8 @@ - [Please Do's](#please-dos) - [Test against Postgres](#test-against-postgres) - [Postgres with Docker](#postgres-with-docker) -- [Change and Removal of Existing Features](#change-and-removal-of-existing-features) - - [Phased Deprecation Policy](#phased-deprecation-policy) +- [Breaking Changes](#breaking-changes) + - [Deprecation Policy](#deprecation-policy) - [Feature Considerations](#feature-considerations) - [Security Checks](#security-checks) - [Add Security Check](#add-security-check) @@ -166,25 +166,25 @@ RUN chmod +x /docker-entrypoint-initdb.d/setup-dbs.sh Note that the script above will ONLY be executed during initialization of the container with no data in the database, see the official [Postgres image](https://hub.docker.com/_/postgres) for details. If you want to use the script to run again be sure there is no data in the /var/lib/postgresql/data of the container. -## Change and Removal of Existing Features +## Breaking Changes -We want to avoid sudden breaking changes which has been often been pointed out in community feedback. Therefore we intend to follow the [Phased Deprecation Policy](#phased-deprecation-policy) when changing or removing existing features. +We want to avoid sudden breaking changes which has been often been pointed out in community feedback. Therefore we intend to follow the [Deprecation Policy](#deprecation-policy) when changing or removing existing features. -Please consider that Parse Server is just one component in a stack for many developers. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: +Please consider that Parse Server is just one component in a stack that requires attention. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: - "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change - less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers - less feedback and slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on -### Phased Deprecation Policy +### Deprecation Policy If you change or remove an existing feature that would lead to a breaking change, consider the following: 1. Only urgent changes with security relevance are allowed to be sudden breaking changes. 2. Use a phased deprecation pattern for all other changes: - Make the new feature or change optional, if necessary with a new Parse Server option parameter. - Use a default value that falls back to the existing behavior. - - Add a warning log message to the Parse Server options validation in [Config.js](https://github.com/parse-community/parse-server/blob/master/src/Config.js) that the option value will be deprecated in the future: + - Add a warning log message to the Parse Server options validation in [Config.js](https://github.com/parse-community/parse-server/blob/master/src/Config.js) that the option value will be deprecated in the future, for example: > `Warning: The option : will be deprecated in a future release. Use : instead which will become the new default.` -3. Breaking changes are to be collected into the next major release of Parse Server. +3. Breaking changes are collected into the next major release of Parse Server. Developers should be notified of breaking changes for at least 6 months before they become mandatory. ## Feature Considerations ### Security Checks From d0701a0430192bdd51fe04bb15013572daa05998 Mon Sep 17 00:00:00 2001 From: Manuel <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 17:39:42 +0100 Subject: [PATCH 5/9] Fixed typo --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52726127cc..5aadd2525f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,7 @@ Most importantly, with every contribution you improve your skills so that future ### Recommended Tools -* [vscode](https://code.visualstudio.com), the popular IDE. +* [Visual Studio Code](https://code.visualstudio.com), the popular IDE. * [Jasmine Test Explorer](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-jasmine-test-adapter), a very practical test exploration plugin which let you run, debug and see the test results inline. ### Setting up your local machine @@ -168,9 +168,9 @@ Note that the script above will ONLY be executed during initialization of the co ## Breaking Changes -We want to avoid sudden breaking changes which has been often been pointed out in community feedback. Therefore we intend to follow the [Deprecation Policy](#deprecation-policy) when changing or removing existing features. +To make breaking changes more predictable we follow a [Deprecation Policy](#deprecation-policy) when changing or removing existing features. -Please consider that Parse Server is just one component in a stack that requires attention. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: +We acknowledge that Parse Server is just one component in a stack that requires attention. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: - "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change - less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers - less feedback and slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on From 6b860f4145cb054cca1928c01461cac9d0defb90 Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 16 Feb 2021 23:46:16 +0100 Subject: [PATCH 6/9] fixed typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5aadd2525f..64a80732c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -184,7 +184,7 @@ If you change or remove an existing feature that would lead to a breaking change - Use a default value that falls back to the existing behavior. - Add a warning log message to the Parse Server options validation in [Config.js](https://github.com/parse-community/parse-server/blob/master/src/Config.js) that the option value will be deprecated in the future, for example: > `Warning: The option : will be deprecated in a future release. Use : instead which will become the new default.` -3. Breaking changes are collected into the next major release of Parse Server. Developers should be notified of breaking changes for at least 6 months before they become mandatory. +3. Breaking changes are collected into the next major release of Parse Server. Developers should be notified of breaking changes at least 6 months before they become mandatory. ## Feature Considerations ### Security Checks From 36a0d0614fc252368e702b9c356cc2b73f81d04d Mon Sep 17 00:00:00 2001 From: Manuel <5673677+mtrezza@users.noreply.github.com> Date: Mon, 8 Mar 2021 17:25:43 +0100 Subject: [PATCH 7/9] Fixed typo --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d9141d015..c748c6f212 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -86,6 +86,7 @@ Jump directly to a version: ___ + ## Unreleased (Master Branch) [Full Changelog](https://github.com/parse-community/parse-server/compare/4.5.0...master) ### Breaking Changes @@ -127,7 +128,7 @@ ___ - Use Node.js 15.13.0 in CI (Olle Jonsson) [#7312](https://github.com/parse-community/parse-server/pull/7312) - Fix file upload issue for S3 compatible storage (Linode, DigitalOcean) by avoiding empty tags property when creating a file (Ali Oguzhan Yildiz) [#7300](https://github.com/parse-community/parse-server/pull/7300) ___ -## 4.5.0 + [Full Changelog](https://github.com/parse-community/parse-server/compare/4.4.0...4.5.0) ### Breaking Changes - FIX: Consistent casing for afterLiveQueryEvent. The afterLiveQueryEvent was introduced in 4.4.0 with inconsistent casing for the event names, which was fixed in 4.5.0. [#7023](https://github.com/parse-community/parse-server/pull/7023). Thanks to [dblythy](https://github.com/dblythy). From 1f3b040cc4b9899f187d1386d6efd60e63817f7c Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 30 Mar 2021 19:32:22 +0200 Subject: [PATCH 8/9] updated deprecation policy --- CONTRIBUTING.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64a80732c9..a761f91955 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -168,23 +168,28 @@ Note that the script above will ONLY be executed during initialization of the co ## Breaking Changes -To make breaking changes more predictable we follow a [Deprecation Policy](#deprecation-policy) when changing or removing existing features. +Breaking changes should be avoided whenever possible. For a breaking change to be accepted, the benefits of the change have to clearly outweigh the costs of developers having to adapt their deployments. If a breaking change is only cosmetic it will likely be rejected and preferred to become obsolete organically during the course of further development, unless it is required as part of a larger change. Breaking changes should follow the [Deprecation Policy](#deprecation-policy). -We acknowledge that Parse Server is just one component in a stack that requires attention. A breaking change requires resources and effort to adapt a production environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: +Please consider that Parse Server is just one component in a stack that requires attention. A breaking change requires resources and effort to adapt an environment. An unnecessarily high frequency of breaking changes can have detrimental side effects such as: - "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change - less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers - less feedback and slower identification of bugs and an overall slow-down of Parse Server development because new versions with breaking changes also include new features we want to get feedback on ### Deprecation Policy -If you change or remove an existing feature that would lead to a breaking change, consider the following: -1. Only urgent changes with security relevance are allowed to be sudden breaking changes. -2. Use a phased deprecation pattern for all other changes: - - Make the new feature or change optional, if necessary with a new Parse Server option parameter. - - Use a default value that falls back to the existing behavior. - - Add a warning log message to the Parse Server options validation in [Config.js](https://github.com/parse-community/parse-server/blob/master/src/Config.js) that the option value will be deprecated in the future, for example: - > `Warning: The option : will be deprecated in a future release. Use : instead which will become the new default.` -3. Breaking changes are collected into the next major release of Parse Server. Developers should be notified of breaking changes at least 6 months before they become mandatory. +If you change or remove an existing feature that would lead to a breaking change, use the following deprecation pattern: + - Make the new feature or change optional, if necessary with a new Parse Server option parameter. + - Use a default value that falls back to existing behavior. + - Add a deprecation definition in `Deprecator/Deprecations.js` that will output a deprecation warning log message on Parse Server launch, for example: + > DeprecationWarning: The Parse Server option 'example' will be removed in a future release. + +Deprecations become breaking changes after notifying developers through deprecation warnings for at least one entire previous major release. For example: + - `4.5.0` is the current version + - `4.6.0` adds a new optional feature and a deprecation warning for the existing feature + - `5.0.0` marks the beginning of logging the deprecation warning for one entire major release + - `6.0.0` makes the breaking change by removing the deprecation warning and making the new feature replace the existing feature + +Developer feedback during the deprecation period may further postpone the introduction of a breaking change. ## Feature Considerations ### Security Checks From 20172ce9804f72b617ca129dbed7ec50e0a31bbc Mon Sep 17 00:00:00 2001 From: Manuel Trezza <5673677+mtrezza@users.noreply.github.com> Date: Tue, 30 Mar 2021 19:43:20 +0200 Subject: [PATCH 9/9] remove empty line --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c748c6f212..8597e5faff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -128,7 +128,7 @@ ___ - Use Node.js 15.13.0 in CI (Olle Jonsson) [#7312](https://github.com/parse-community/parse-server/pull/7312) - Fix file upload issue for S3 compatible storage (Linode, DigitalOcean) by avoiding empty tags property when creating a file (Ali Oguzhan Yildiz) [#7300](https://github.com/parse-community/parse-server/pull/7300) ___ - +## 4.5.0 [Full Changelog](https://github.com/parse-community/parse-server/compare/4.4.0...4.5.0) ### Breaking Changes - FIX: Consistent casing for afterLiveQueryEvent. The afterLiveQueryEvent was introduced in 4.4.0 with inconsistent casing for the event names, which was fixed in 4.5.0. [#7023](https://github.com/parse-community/parse-server/pull/7023). Thanks to [dblythy](https://github.com/dblythy).