Before you start to code, please open a new issue to describe your idea, or search for and continue the discussion in an existing issue.
⚠️ Please do not post a security vulnerability on GitHub or in the Parse Community Forum. Instead, follow the Parse Community Security Policy.
Please completely fill out any templates to provide essential information about your new feature or the bug you discovered.
Together we will plan out the best conceptual approach for your contribution, so that your and our time is invested in the best possible approach. The discussion often reveals how to leverage existing features of Parse Server to reach your goal with even less effort and in a more sustainable way.
When you are ready to code, you can find more information about opening a pull request in the GitHub docs.
Whether this is your first contribution or you are already an experienced contributor, the Parse Community has your back – don't hesitate to ask for help!
An issue is required to be linked in every pull request. We understand that no-one likes to create an issue for something that appears to be a simple pull request, but here is why this is beneficial for everyone:
An issue and pull request must limit its scope on a distinct issue. Pull requests can only contain changes that are required to address the scoped issue. While it may seem quick and easy to add unrelated changes to the pull request, it can cause singificant complications after merging. Some of the reasons are:
You are required to use and completely fill out the templates for new issues and pull requests. We understand that no-one enjoys filling out forms, but here is why this is beneficial for everyone:
Buy cheap, buy twice. What? No, this is not the Economics 101 class, but the same is true for contributing.
There are two ways of writing a feature or fixing a bug. Sometimes the quick solution is to just write a Cloud Code function that does what you want. Contributing by making the change directly in Parse Server may take a bit longer, but it actually saves you much more time in the long run.
Consider the benefits you get:
Most importantly, with every contribution you improve your skills so that future contributions take even less time and you get all the benefits above for free — easy choice, right?
Instead of writing review comments back-and-forth, why doesn't the reviewer just write the code themselves?
A reviewer is already helping you to make a code contribution through their review. A reviewer may even help you to write code by actually writing it for you, but is not obliged to do so.
GitHub allows reviewers to suggest and write code changes as part of the review feedback. These code suggestions are likely to contain mistakes due to the lack of code syntax checks when writing code directly on GitHub. You should therefore always review these suggestions before accepting them, ideally in an IDE. If you merge a code suggestion and the CI then fails, take another look at the code change before asking the reviewer for help.
It takes too much effort to incorporate the review feedback, why why can't you just merge my pull request?
If you are a new contributor, it's naturally a learning experience for you and therefore takes longer. We welcome contributors of any experience levels and gladly support you in getting familiar with the code base and our quality standards and contribution requirements. In return we expect you to be open to and appreciative of the reviewers' feedback.
In a large pull request, it can be a significant effort to bring it over the finish line. Luckily this is a collaborative environment and others are free to jump in to contribute to the pull request to share the effort. You can either give others access to your fork or they can open their own pull request based on your previous work.
If you are out of resources stay calm, explain your personal constraints (expertise or time) and ask for help. Wasting time by complaining about the amount of review comments will neither use your own time in a meaningful way, nor the time of others who read your complaint.
This is a collaborative enviroment in which everyone works on a common goal - to get a pull request ready for merging. Reviewers are working with you to get your pull request ready, not against you.
❗️ Always be mindful that the reviewers' efforts are an integral part of code contribution. Their review is as important as your written code and their review time is a valuable as your coding time.
The feature already works, why do you request more changes instead of just merging my pull request?
A feature may work for your own use case or in your own environment, but that doesn't necessarily mean that it's ready for merging. Aside from code quality and code style requirements, reviewers also review based on strategic and architectural considerations. It's often easy to just get a feature to work, but it needs to be also maintained in the future, robust therefore well tested and validated, intuitive for other developers to use, well documented, and not cause a forseeable breaking change in the near future.
The reviewer has never worked on the issue and was never part of any previous discussion, why would I care about their opinion?
It's contrary to an open, collaborative environment to expect others to be involved in an issue or discussion since its beginning. Such a mindset would close out any new views, which are important for a differentiated discussion.
The reviewer doesn't have any expertise in that matter, why would I care about their opinion?
Your arguments must focus on the issue, not on your assumption of someone else's personal experience. We will take immediate and appropriate action in case of personal attacks, regardless of your previous contributions. Personal attacks are not permissible. If you became a victim of personal attacks, you can privately report the GitHub comment to the Parse Platform PMC.
Can I open a new pull request based on another author's pull request?
If your pull request contains work from someone else then you are required to get their permission to use their work in your pull request. Please make sure to observe the license for more details. In addition, as an appreciative gesture you should clearly mention that your pull request is based on another pull request with a link in the top-most comment of your pull request. To avoid this issue we encourage contributors to collaborate on a single pull request to preserve the commit history and clearly identify each author's contribution. To do so, you can review the other author's pull request and submit your code suggestions, or ask the original author to grant you write access to their repository to also be able to make commits directly to their pull request.
Can I get write access to the repository to make changes faster?
Keeping our products safe and secure is one of your top priorities. Our security policy mandates that write access to repositories is only provided to as few people as necessary. All usual contributions can be made via public pull requests. If you think you need write access, contact the repository team and explain in detail what the constraint is that you are trying to overcome. We want to make contributing for you as easy as possible. If there are any bottlenecks that are slowing you down we are happy to receive your feedback to see where we can improve.
Can I get a new private repository within the Parse Platform organization to work on some stuff?
Private repositories are not provided unless there is a significant constraint or requirement that makes it necessary. For example, when collaborating on fixing a security vulnerability we provide private repositories to allow collaborators to share sensitive information within a select group.
Can I get a new public repository within the Parse Platform organization to work on some stuff?
First of all, we appreciate your contribution. In rare cases, where we consider it beneficial to the advancement of the repository, a new public repository for a specific purpose may be provided, for example for increased visibility or to provide the organization's GitHub ressources. In other cases, we encourage you to start your contribution in a personal repository of your own GitHub account, and later transfer it to the Parse Platform organization. We will be happy to assist you in the repository transfer.
$ git clone https://github.com/parse-community/parse-server
$ cd parse-server # go into the clone directory
$ npm install # install all the node dependencies
$ code . # launch vscode
$ npm run watch # run babel watching for local file changes
To launch VS Code from the terminal with the
code
command you first need to follow the launching from the command line section in the VS Code setup documentation.
Once you have babel running in watch mode, you can start making changes to parse-server.
lib/
folder is not committed, so never make changes in there.src/
folder.lib/
folder.lib/
folder is produced by babel
using either the npm run build
, npm run watch
, or the npm run prepare
step.npm run prepare
step is automatically invoked when your package depends on forked parse-server installed via git for example using npm install --save git+https://github.com/[username]/parse-server#[branch/commit]
.await reconfigureServer({ ... some configuration })
found in spec/helper.js
.spec
folderPARSE_SERVER_LOG_LEVEL=debug
Question: I modify the code in the src folder but it doesn't seem to have any effect.
Answer: Check that npm run watch
is running
Question: How do I use breakpoints and debug step by step?
Answer: The easiest way is to install Jasmine Test Explorer, it will let you run selectively tests and debug them.
Question: How do I deploy my forked version on my servers?
Answer: In your package.json
, update the parse-server
dependency to https://github.com/[username]/parse-server#[branch/commit]
. Run npm install
, commit the changes and deploy to your servers.
Question: How do I deploy my forked version using docker?
Answer: In your package.json
, update the parse-server
dependency to https://github.com/[username]/parse-server#[branch/commit]
. Make sure the npm install
step in your Dockerfile
is running under non-privileged user for the npm run prepare
step to work correctly. For official node images from hub.docker.com that non-privileged user is node
with /home/node
working directory.
npm run coverage
npm test spec/MyFile.spec.js
npm run lint
to make sure the code is not going to be rejected by the CI.spec/support
folder.If your pull request introduces a change that may affect the storage or retrieval of objects, you may want to make sure it plays nice with Postgres.
You'll need to have postgres running on your machine and setup appropriately or use Docker
Run the tests against the postgres database with:
PARSE_SERVER_TEST_DB=postgres PARSE_SERVER_TEST_DATABASE_URI=postgres://postgres:password@localhost:5432/parse_server_postgres_adapter_test_database npm run testonly
The Postgres adapter has a special debugger that traces all the sql commands. You can enable it with setting the environment variable PARSE_SERVER_LOG_LEVEL=debug
If your feature is intended to only work with MongoDB, you should disable PostgreSQL-specific tests with:
describe_only_db('mongo')
// will create a describe
that runs only on mongoDBit_only_db('mongo')
// will make a test that only runs on mongoit_exclude_dbs(['postgres'])
// will make a test that runs against all DB's but postgresSimilarly, if your feature is intended to only work with PostgreSQL, you should disable MongoDB-specific tests with:
describe_only_db('postgres')
// will create a describe
that runs only on postgresit_only_db('postgres')
// will make a test that only runs on postgresit_exclude_dbs(['mongo'])
// will make a test that runs against all DB's but mongoIf your feature is intended to work with MongoDB and PostgreSQL, you can include or exclude tests more granularly with:
it_only_mongodb_version('>=4.4')
// will test with any version of Postgres but only with version >=4.4 of MongoDB; accepts semver notation to specify a version rangeit_exclude_mongodb_version('<4.4')
// will test with any version of Postgres and MongoDB, excluding version <4.4 of MongoDB; accepts semver notation to specify a version rangeit_only_postgres_version('>=13')
// will test with any version of Mongo but only with version >=13 of Postgres; accepts semver notation to specify a version rangeit_exclude_postgres_version('<13')
// will test with any version of Postgres and MongoDB, excluding version <13 of Postgres; accepts semver notation to specify a version rangePostGIS images (select one with v2.2 or higher) on docker hub is based off of the official postgres image and will work out-of-the-box (as long as you create a user with the necessary extensions for each of your Parse databases; see below). To launch the compatible Postgres instance, copy and paste the following line into your shell:
docker run -d --name parse-postgres -p 5432:5432 -e POSTGRES_PASSWORD=password --rm postgis/postgis:16-3.4-alpine && sleep 20 && docker exec -it parse-postgres psql -U postgres -c 'CREATE DATABASE parse_server_postgres_adapter_test_database;' && docker exec -it parse-postgres psql -U postgres -c 'CREATE EXTENSION pgcrypto; CREATE EXTENSION postgis;' -d parse_server_postgres_adapter_test_database && docker exec -it parse-postgres psql -U postgres -c 'CREATE EXTENSION postgis_topology;' -d parse_server_postgres_adapter_test_database
To stop the Postgres instance:
docker stop parse-postgres
You can also use the postgis/postgis:16-3.4-alpine image in a Dockerfile and copy this script to the image by adding the following lines:
#Install additional scripts. These are run in abc order during initial start
COPY ./scripts/setup-dbs.sh /docker-entrypoint-initdb.d/setup-dbs.sh
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 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 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.
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:
If you change or remove an existing feature that would lead to a breaking change, use the following deprecation pattern:
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.
For deprecations that can only be determined ad-hoc during runtime, for example Parse Query syntax deprecations, use the Deprecator.logRuntimeDeprecation()
method.
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 version4.6.0
adds a new optional feature and a deprecation warning for the existing feature5.0.0
marks the beginning of logging the deprecation warning for one entire major release6.0.0
makes the breaking change by removing the deprecation warning and making the new feature replace the existing featureSee the Deprecation Plan for an overview of deprecations and planned breaking changes.
The Parse Server security checks feature warns developers about weak security settings in their Parse Server deployment.
A security check needs to be added for every new feature or enhancement that allows the developer to configure it in a way that weakens security mechanisms or exposes functionality which creates a weak spot for malicious attacks. If you are not sure whether your feature or enhancements requires a security check, feel free to ask.
For example, allowing public read and write to a class may be useful to simplify development but should be disallowed in a production environment.
Security checks are added in CheckGroups.
Adding a new security check for your feature is easy and fast:
Look into CheckGroups whether there is an existing CheckGroup[Category].js
file for the category of check to add. For example, a check regarding the database connection is added to CheckGroupDatabase.js
.
If you did not find a file, duplicate an existing file and replace the category name in setName()
and the checks in setChecks()
:
class CheckGroupNewCategory extends CheckGroup {
setName() {
return 'House';
}
setChecks() {
return [
new Check({
title: 'Door locked',
warning: 'Anyone can enter your house.',
solution: 'Lock the door.',
check: () => {
return; // Example of a passing check
}
}),
new Check({
title: 'Camera online',
warning: 'Security camera is offline.',
solution: 'Check the camera.',
check: async () => {
throw 1; // Example of a failing check
}
}),
];
}
}
If you added a new file in the previous step, reference the file in CheckGroups.js, which is the collector of all security checks:
export { default as CheckGroupNewCategory } from './CheckGroupNewCategory';
Add a test that covers the new check to SecurityCheckGroups.js for the cases of success and failure.
Consider the following when adding a new security check:
Introducing new Parse Errors requires the following steps:
throw new Parse.Error(Parse.Error.EXAMPLE_ERROR_CODE, 'Example error message.');
throw new Parse.Error(Parse.Error.FILE_SAVE_ERROR, 'The file could not be saved because it exceeded the maximum allowed file size.');
throw new Parse.Error(Parse.Error.FILE_SAVE_ERROR, 'The file could not be saved because the file format was incorrect.');
Introducing new Parse Server configuration parameters requires the following steps:
Add parameters definitions in /src/Options/index.js.
If the new parameter does not have one single value but is a parameter group (an object containing multiple sub-parameters):
nestedOptionEnvPrefix
in /resources/buildConfigDefinition.js
nestedOptionTypes
in /resources/buildConfigDefinition.js
For example, take a look at the existing Parse Server security
parameter. It is a parameter group, because it has multiple sub-parameter such as checkGroups
. Its interface is defined in index.js as export interface SecurityOptions
. Therefore, the value to add to nestedOptionTypes
would be SecurityOptions
, the value to add to nestedOptionEnvPrefix
would be PARSE_SERVER_SECURITY_
.
Execute npm run definitions
to automatically create the definitions in /src/Options/Definitions.js and /src/Options/docs.js.
Add parameter value validation in /src/Config.js.
Add test cases to ensure the correct parameter value validation. Parse Server throws an error at launch if an invalid value is set for any configuration parameter.
Execute npm run docs
to generate the documentation in the /out
directory. Take a look at the documentation whether the description and formatting of the newly introduced parameters is satisfactory.
For release automation, the title of pull requests needs to be written in a defined syntax. We loosely follow the Conventional Commits specification, which defines this syntax:
<type>: <summary>
The type is the category of change that is made, possible types are:
feat
- add a new feature or improve an existing featurefix
- fix a bugrefactor
- refactor code without impact on features or performancedocs
- add or edit code comments, documentation, GitHub pagesstyle
- edit code stylebuild
- retry failing build and anything build process relatedperf
- performance optimizationci
- continuous integrationtest
- testsThe summary is a short change description in present tense, not capitalized, without period at the end. This summary will also be used as the changelog entry.
LQ
write LiveQuery
Cloud Validator
use Cloud Function validation
For example:
feat: add handle to door for easy opening
Currently, we are not making use of the commit scope, which would be written as <type>(<scope>): <summary>
, that attributes a change to a specific part of the product.
If a pull request contains a braking change, the description of the pull request must contain a dedicated chapter at the bottom to indicate this. This is to assist the committer of the pull request to avoid merging a breaking change as non-breaking.
The following guide is for anyone who merges a contributor pull request into the working branch, the working branch into a release branch, a release branch into another release branch, or any other direct commits such as hotfixes into release branches or the working branch.
Squash and Merge
, to create a single commit message that describes the change.Merge Commit
, to preserve each individual commit message that describes its respective change.If the pull request contains a breaking change, the commit message must contain the phrase BREAKING CHANGE
, capitalized and without any formatting, followed by a short description of the breaking change and ideally how the developer should address it, all in a single line. This line should contain more details focusing on the "breaking” aspect of the change and is intended to assist the developer in adapting. Keep it concise, as it will become part of the changelog entry, for example:
fix: remove handle from door
BREAKING CHANGE: You cannot open the door anymore by using a handle. See the [#migration guide](http://example.com) for more details.
Keep in mind that in a repository with release automation, merging such a commit message will trigger a release with a major version increment.
If the commit reverts a previous commit, use the prefix revert:
, followed by the header of the reverted commit. In the body of the commit message add This reverts commit <hash>.
, where the hash is the SHA of the commit being reverted. For example:
revert: fix: remove handle from door
This reverts commit 1234567890abcdef.
⚠️ A revert
prefix will always trigger a release. Generally, a commit that did not trigger a release when it was initially merged should also not trigger a release when it is reverted. For example, do not use the revert
prefix when reverting a commit that has a ci
prefix:
ci: add something
is reverted with:
ci: remove something
instead of:
revert: ci: add something
This reverts commit 1234567890abcdef.
Fixes for securify vulnerabilities are developed in private forks with a closed audience, inaccessible to the public. A current GitHub limitation does not allow to run CI tests on pull requests in private forks. Whether a pull requests fully passes all CI tests can only be determined by publishing the fix as a public pull request and running the CI. This means the fix and implicitly information about the vulnerabilty are made accessible to the public. This increases the risk that a vulnerability fix is published, but then cannot be merged immediately due to a CI issue. To mitigate that risk, before publishing a vulnerability fix, the following tests needs to be run locally and pass:
npm run test
(MongoDB)npm run test
(Postgres)npm run madge:circular
(circular dependencies)npm run lint
(Lint)npm run definitions
(Parse Server options definitions)A current GitHub limitation does not allow to customize the commit message when merging pull requests of a private fork that was created to fix a security vulnerabilty. Our release automation framework demands a specific commit message syntax which therefore cannot be met. This prohibits to follow the process that GitHub suggest, which is to merge a pull request from a private fork directly to a public branch. Instead, after local testing, a public pull request needs to be created with the code fix copied over from the private pull request.
This creates a risk that a vulnerability is indirectly disclosed by publishing a pull request with the fix, but the fix cannot be merged due to a CI issue. To mitigate that risk, the pull request title and description should be kept marginal or generic, not hiting to a vulnerabilty or giving any details about the vulnerabilty, until the pull request has been successfully merged.
package-lock.json
file has to be deleted and recreated by npm from scratch in regular intervals using the npm i
command. It is not enough to only update the file via automated security pull requests (e.g. dependabot, snyk), that can create inconsistencies between sub-dependencies of a dependency and increase the chances of vulnerabilities. The file should be recreated once every release cycle which is usually monthly.While the current major version is published on branch release
, a Long-Term-Support (LTS) version is published on branch release-#.x.x
, for example release-4.x.x
for the Parse Server 4.x LTS branch.
The following changes are done in the alpha
branch, before publishing the last beta
version that will eventually become the major release. This way the changes trickle naturally through all branches and code consistency is ensured among branches.
release-#.x.x
to the branch list in release.config.js so that the branch will later be recognized for release automation.build
on branch beta
.build
into release
:
build: release
package.json
and package-lock.json
it doesn't matter which version is chosen, as the version will be set by auto-release in a commit after merging. However, for both files the same version should be chosen when resolving the conflict.release-automated
to finish:
build
.build
on branch alpha
.build
into beta
:
build: release
Create PR to merge hotfix PR into release
:
alpha
.Wait for GitHub Action release-automated
to finish:
! [rejected] HEAD -> beta (non-fast-forward)
; this is expected as auto-release currently cannot fully handle back-merging; docker will not publish the new release, so this has to be done manually using the GitHub workflow release-manual-docker
and entering the version tag that has been created by auto-release.Pull all remote branches into local branches.
Create a new temporary branch backmerge
on branch release
.
Create PR to merge backmerge
into beta
:
refactor: <commit-summary>
where <commit-summary>
is the commit summary of step 1. The commit type needs to be refactor
, otherwise the commit will show in the changelog of the release
branch, once the beta
branch is merged into release; this would a duplicate entry because the same changelog entry has already been generated when the PR was merged into the release
branch in step 1.Resolve any conflicts:
release
branch, the incoming changes come from the beta
branch usually being ahead of the release
branch. This makes back-merging so complex and bug-prone and is the main reason why it should be avoided if possible.Merge PR with "squash and merge", do not do a "merge commit":
ℹ️ Merging this PR will not trigger a release; the back-merge will not appear in changelogs of the beta
, alpha
branches; the back-merged fix will be an undocumented change of these branches' next releases; if necessary, the change needs to be added manually to the pre-release changelogs after the next pre-releases.
Delete temporary branch backmerge
.
Create a new temporary branch backmerge
on branch beta
.
Repeat steps 4-8 to merge PR into alpha
.
⚠️ Long-term-support branches are excluded from the processes above and handled individually as they do not have pre-releases branches and are not considered part of the current codebase anymore. It may be necessary to significantly adapt a PR for a LTS branch due to the differences in codebase and CI tests. This adaption should be done in advance before merging any related PR, especially for security fixes, as to not publish a vulnerability while it may still take significant time to adapt the fix for the older codebase of a LTS branch.
release-#.x.x
off the latest version tag on release
branch.build-release
off branch beta
and create a pull request with release
as the base branch.build-release
into release
. Given that there will be breaking changes, a new major release will be created. In the unlikely case that there have been no breaking changes between the previous major release and the upcoming release, a major version increment has to be triggered manually. See the docs of the release automation framework for how to do that.release-#.x.x
from step 1 to Snyk so that Snyk opens pull requests for the LTS branch; remove previously existing LTS branch release-#.x.x
from Snyk.The following versioning system is applied since Parse Server 5.0.0 and does not necessarily apply to previous releases.
Parse Server follows semantic versioning with a flavor of calendric versioning. Semantic versioning makes Parse Server easy to upgrade because breaking changes only occur in major releases. Calendric versioning gives an additional sense of how old a Parse Server release is and allows for Long-Term Support of previous major releases.
Example version: 5.0.0-alpha.1
Syntax: [major]
.[minor]
.[patch]
-[pre-release-label]
.[pre-release-increment]
major
version increments with the first release of every year and may include changes that are not backwards compatible.minor
version increments during the year and may include new features or improvements of existing features that are backwards compatible.patch
version increments during the year and may include bug fixes that are backwards compatible.pre-release-label
is optional for pre-release versions such as:
-alpha
(likely to contain bugs, likely to change in features until release)-beta
(likely to contain bugs, no change in features until release)[pre-release-increment]
is a number that increments with every new version of a pre-releaseExceptions:
major
version may increment during the year in the unlikely event that a breaking change is so urgent that it cannot wait for the next yearly release. An example would be a vulnerability fix that leads to an unavoidable breaking change. However, security requirements depend on the application and not every vulnerability may affect every deployment, depending on the features used. Therefore we usually prefer to deprecate insecure functionality and introduce the breaking change following our deprecation policy.This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to honor this code.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。