We rely on the regular github workflow of forking and pull requests (PR) which is described in the github help. If you don’t know how that works we recommend the github help that offers lots of guides to get you started working with github: https://help.github.com/
You can always ask the community for help while preparing a pull request if you are unsure about the github workflow, the following rules or any other aspect of contributing. We are happy to help!
All pull requests should stick to a single topic. Don’t work on more than one bug and/or feature in the same pull request unless the bugs all have the same cause and fix.
Which branch do I create the pull request for?
Features always go to the master branch unless there is a very good reason to put them into an already released version (usually to fix a bug that cannot be fixed without the feature).
Bugfixes on the other hand should go to the lowest supported version (that has the bug).
So for example if
2.0 are the maintained stable versions then a bugfix should go to
1.2 and will subsequently be merged into
2.0 and the development
master by a team member.
In most cases, this is the lowest LTS version in bugfix support mode, which you can check on the release roadmap.
We might ask you to change the branch your pull request would go to. That means you need to close the pull request and open another one to the requested branch. Avoid extra work by getting it right the first time.
If you’re unsure which branch to submit to, just submit it or ask in the development channels on Slack.
We love it when at least your pull request message sticks to our commit message style but team members can help you with that after you created the pull request. The actual commit messages may be one-liners if the pull request message describes all changes inside sufficiently.
Please add labels (if you have the permission to do so) to your PR to help organize them. In any case, take note of labels added to your PR and act accordingly, if needed.
- Component (Blue) – Neos, Content Repository, NodeTypes, Media, Kickstart / Flow, Fluid, Eel, Kickstart
- Topic (Green) – PHP, JS, Documentation, Database, Testing, UX
- Impediment (Orange) – WIP (work in progress), Needs feedback, Help wanted, Discussion (currently blocked by a discussion), Merge conflict
Additionally there’s a red label “Wrong branch” for indicating the PR was submitted for the wrong branch. See section above.
Note: You can make use of github’s “draft pull request” feature to denote a WIP PR you are still working on. See Introducing draft pull requests - The GitHub Blog
If assigning the WIP label, this means the PR should not be merged and usually people might not consider it for reviewing (because it is not done anyway). So, if you want to have feedback on a WIP pull request, also assign the Needs feedback label.
Automated tests and code style
All pull requests are automatically tested by https://travis-ci.org/ and cannot be merged if the tests fail. We expect that you ran the tests locally and made sure they completed successfully before creating the pull request.
In order to run tests, you typically execute the following command(s) from the command line inside your
./bin/phpunit --configuration Build/BuildEssentials/PhpUnit/UnitTests.xml
./bin/phpunit --configuration Build/BuildEssentials/PhpUnit/FunctionalTests.xml
See https://phpunit.readthedocs.io/en/8.0/textui.html#command-line-options for more information on the command line parameters.
If you are on a branch of Flow >= 6.0 (including master), then you are also adviced to run our static analysis:
./bin/psalm --config=Packages/Framework/psalm.xml --update-baseline --show-info=false
Note: The --update-baseline option may lead to a change to the psalm-baseline.xml file. Don’t worry about it and just commit it into your PR.
Changes should be accompanied by tests that confirm the behavior to prevent bugs and to make the life of everyone easier.
Make sure you follow the coding style guidelines before opening the pull request as our style checker will block the pull request if the change doesn’t follow them.
All PRs need to be reviewed before merging. Everyone is welcome to review and the more reviews the better. For merging there needs to be at least two votes before merging a change, for complex changes more votes can be necessary. Merging can be done by any team member with the needed permissions.
Discussion about a change happens on Github in the pull request and may result in the need to change the pull request, therefore please make sure you subscribe to notifications for your own pull requests.
Note that our time is limited and it might take a moment to check a pull request and get back to you. Don’t be discouraged if you don’t get quick answers. We will have a look at it!
Collaboration on PRs
If you want people to be be able to directly improve on a PR (e.g. to fix small things directly instead of simply leaving a comment asking you to do it), you can grant push access to your fork. A suggestion is to give all team members access to your fork, if you plan to contribute regularly.
Flow and Neos bring multiple migration tools for separate areas:
- Code migrations (includes configuration files and templates)
- Database migrations
- Node migrations (only relevant for the Content Repository)
If a change in code makes adaption of one of the above necessary you should provide a migration with your pull request. Again we can help you with that. Note that we currently ship migrations for MySQL and Postgresql so your pull request needs to provide both if a database migration is necessary.
Any change that needs manual work to keep existing code running is by definition a breaking change. This is automatically true for any changes in @api methods and interfaces. Those changes must be marked accordingly in the commit message (see details in the commit message styleguide) and should only go to master unless specific reasons make that necessary and it was discussed and agreed upon with active team members.
The Neos Project strifes for a high quality code base and thus we try to stick to principles like DRY, SOLID and Clean Code. Additionally we follow design patterns. All this shouldn’t block you from creating a pull request, we can help you to adjust the code if we feel improvements are possible.