diff --git a/CHANGELOG.md b/CHANGELOG.md index 141bd94a86..67cebb83f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -86,18 +86,20 @@ Jump directly to a version: ___ + ## Unreleased (Master Branch) [Full Changelog](https://github.com/parse-community/parse-server/compare/4.5.0...master) ### Breaking Changes - Improved schema caching through database real-time hooks. Reduces DB queries, decreases Parse Query execution time and fixes a potential schema memory leak. If multiple Parse Server instances connect to the same DB (for example behind a load balancer), set the [Parse Server Option](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) `databaseOptions.enableSchemaHooks: true` to enable this feature and keep the schema in sync across all instances. Failing to do so will cause a schema change to not propagate to other instances and re-syncing will only happen when these instances restart. The options `enableSingleSchemaCache` and `schemaCacheTTL` have been removed. To use this feature with MongoDB, a replica set cluster with [change stream](https://docs.mongodb.com/manual/changeStreams/#availability) support is required. (Diamond Lewis, SebC) [#7214](https://github.com/parse-community/parse-server/issues/7214) - Added file upload restriction. File upload is now only allowed for authenticated users by default for improved security. To allow file upload also for Anonymous Users or Public, set the `fileUpload` parameter in the [Parse Server Options](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) (dblythy, Manuel Trezza) [#7071](https://github.com/parse-community/parse-server/pull/7071) - Removed [parse-server-simple-mailgun-adapter](https://github.com/parse-community/parse-server-simple-mailgun-adapter) dependency; to continue using the adapter it has to be explicitly installed (Manuel Trezza) [#7321](https://github.com/parse-community/parse-server/pull/7321) -- Remove support for MongoDB 3.6 which has reached its End-of-Life support date and PostgreSQL 10 (Manuel Trezza) [#7315](https://github.com/parse-community/parse-server/pull/7315) +- Remove support for MongoDB 3.6 which has reached its End-of-Life date and PostgreSQL 10 (Manuel Trezza) [#7315](https://github.com/parse-community/parse-server/pull/7315) +- Remove support for Node 10 which has reached its End-of-Life date (Manuel Trezza) [#7314](https://github.com/parse-community/parse-server/pull/7314) ### Notable Changes - Added Parse Server Security Check to report weak security settings (Manuel Trezza, dblythy) [#7247](https://github.com/parse-community/parse-server/issues/7247) - EXPERIMENTAL: Added new page router with placeholder rendering and localization of custom and feature pages such as password reset and email verification (Manuel Trezza) [#6891](https://github.com/parse-community/parse-server/issues/6891) - 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) +- 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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2254e4cc9..a761f91955 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) +- [Breaking Changes](#breaking-changes) + - [Deprecation Policy](#deprecation-policy) - [Feature Considerations](#feature-considerations) - [Security Checks](#security-checks) - [Add Security Check](#add-security-check) @@ -58,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 @@ -164,6 +166,31 @@ 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. +## Breaking Changes + +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). + +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, 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