Git branch handling in the Neos project

This describes the handling of Git branches in the Neos project, effective as of September 2022.

Default branches

  • There is no master or main branch in the Flow or Neos development collections or distributions.
  • Other repositories may still have a main or master branch.
  • master should be renamed to main whenever possible

The default branch should be one for the latest released version. Usually “higher version” branch exists as a target for the next minor release (this is what in most projects is the main branch.)

If you think a repository has an incorrectly set default branch, please let us know!

Branch naming

  • Every minor version has a corresponding branch, named x.y
  • There may already be a branch for the next major version, named x.0, even though that version has not been released. That is to allow work on breaking changes without affecting the feature branch(es) below.

Branch creation

  • To create a new release branch, use the respective job in Jenkins.
  • PR branches should be created in forks, not in the Neos org repositories.

Target branches for pull requests

  • Pull requests for bugfixes must be made against the lowest affected branch still maintained. Which branch that is, can be checked on Release roadmap & process - Why Neos CMS? -
  • Feature pull requests must be made against the branch for the next minor version.
  • Breaking changes must only go into the branch for the next major version.

If in doubt, read Release roadmap & process - Why Neos CMS? - and ask either in #creating or on Slack.


We merge bugfixes in the lowest affected branch still maintained. Which branch that is, can be checked on Release roadmap & process - Why Neos CMS? -

To make sure all fixes land in later branches, too, we regularly do upmerges. That means we merge the oldest branch in the following branch, repeating this until the latest branch is up to date.

1 Like

Sounds great, thanks for the writeup!

What does that mean for neos/neos-development-collection (in regards to the 9.0 branch). I.e. will main be based on 8.0 or 9.0 or should we postpone creation of main until 9.0 is released?

No more main there.

  • We’ll (soon) have 8.1 for the next release and 8.2 as base for the next minor.
  • 9.0 exists already.
  • 8.3 will be created with feature freeze / release of 8.2.
  • After the release of 9.0 we’ll have a 9.1 branch.
  • If we want to work on breaking changes afterwards, we can create 10.0 already…

Upmerges are to be done “naturally”, i.e. all changes will always be in later branches, too.

1 Like

Hi all,

master is still the default branch for neos/flow-development-collection and neos/neos-development-collection.
Shouldn’t those be disabled and a 8.2 branch added? (I’m happy to help, but I’m not sure if that was actually the plan)

It was… is… I just didn’t get around to doing it, yet. :grimacing:

Working on this this week…

  • :white_check_mark: neos/behat : mastermain
  • :white_check_mark: neos/welcome : master8.2
  • :white_check_mark: neos/kickstarter : master8.2
  • :white_check_mark: neos/buildessentials : master8.2
  • :white_check_mark: neos/flow-development-distribution : master8.2
  • :white_check_mark: neos/flow-development-collection : master8.2
  • :white_check_mark: neos/flow-base-distribution : master8.2
  • :white_check_mark: neos/neos-development-distribution : master8.2
  • :white_check_mark: neos/neos-development-collection : master8.2
  • :white_check_mark: neos/neos-base-distribution : master8.2
  • :white_check_mark: neos/demo : master8.2
  • :white_check_mark: neos/imagine : mastermain
  • :white_check_mark: neos/party : mastermain
  • :white_check_mark: neos/setup : mastermain
  • :white_check_mark: neos/twitter-bootstrap : mastermain
  • :white_check_mark: neos/doctools : mastermain
  • :white_check_mark: neos/neos-ui : master8.2
  • :white_check_mark: neos/neos-ui-compiled : master8.2
  • :white_check_mark: neos/site-kickstarter : master8.2