|
11 | 11 | - [Please Do's](#please-dos)
|
12 | 12 | - [Test against Postgres](#test-against-postgres)
|
13 | 13 | - [Postgres with Docker](#postgres-with-docker)
|
14 |
| -- [Change and Removal of Existing Features](#change-and-removal-of-existing-features) |
15 |
| - - [Phased Deprecation Policy](#phased-deprecation-policy) |
| 14 | +- [Breaking Changes](#breaking-changes) |
| 15 | + - [Deprecation Policy](#deprecation-policy) |
16 | 16 | - [Feature Considerations](#feature-considerations)
|
17 | 17 | - [Security Checks](#security-checks)
|
18 | 18 | - [Add Security Check](#add-security-check)
|
@@ -166,25 +166,25 @@ RUN chmod +x /docker-entrypoint-initdb.d/setup-dbs.sh
|
166 | 166 |
|
167 | 167 | 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.
|
168 | 168 |
|
169 |
| -## Change and Removal of Existing Features |
| 169 | +## Breaking Changes |
170 | 170 |
|
171 |
| -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. |
| 171 | +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. |
172 | 172 |
|
173 |
| -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: |
| 173 | +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: |
174 | 174 | - "upgrade fatigue" where developers run old versions of Parse Server because they cannot always attend to every update that contains a breaking change
|
175 | 175 | - less secure Parse Server deployments that run on old versions which is contrary to the security evangelism Parse Server intends to facilitate for developers
|
176 | 176 | - 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
|
177 | 177 |
|
178 |
| -### Phased Deprecation Policy |
| 178 | +### Deprecation Policy |
179 | 179 |
|
180 | 180 | If you change or remove an existing feature that would lead to a breaking change, consider the following:
|
181 | 181 | 1. Only urgent changes with security relevance are allowed to be sudden breaking changes.
|
182 | 182 | 2. Use a phased deprecation pattern for all other changes:
|
183 | 183 | - Make the new feature or change optional, if necessary with a new Parse Server option parameter.
|
184 | 184 | - Use a default value that falls back to the existing behavior.
|
185 |
| - - 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: |
| 185 | + - 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: |
186 | 186 | > `Warning: The option <option_name>: <old_option_value> will be deprecated in a future release. Use <option_name>: <new_option_value> instead which will become the new default.`
|
187 |
| -3. Breaking changes are to be collected into the next major release of Parse Server. |
| 187 | +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. |
188 | 188 |
|
189 | 189 | ## Feature Considerations
|
190 | 190 | ### Security Checks
|
|
0 commit comments