Skip to content

Commit ba793fa

Browse files
committed
added phased deprecation policy
1 parent 8643ae4 commit ba793fa

File tree

1 file changed

+22
-0
lines changed

1 file changed

+22
-0
lines changed

CONTRIBUTING.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
- [Please Do's](#please-dos)
1212
- [Test against Postgres](#test-against-postgres)
1313
- [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)
1416
- [Feature Considerations](#feature-considerations)
1517
- [Security Checks](#security-checks)
1618
- [Add Security Check](#add-security-check)
@@ -164,6 +166,26 @@ RUN chmod +x /docker-entrypoint-initdb.d/setup-dbs.sh
164166

165167
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.
166168

169+
## Change and Removal of Existing Features
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.
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:
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+
- 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+
- 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
177+
178+
### Phased Deprecation Policy
179+
180+
If you change or remove an existing feature that would lead to a breaking change, consider the following:
181+
1. Only urgent changes with security relevance are allowed to be sudden breaking changes.
182+
2. Use a phased deprecation pattern for all other changes:
183+
- Make the new feature or change optional, if necessary with a new Parse Server option parameter.
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:
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.
188+
167189
## Feature Considerations
168190
### Security Checks
169191

0 commit comments

Comments
 (0)