Conventions

GitFlow Branching model

The Decidim respository follows the GitFlow branching model. There are good documentations on it at:

This model introduces the develop branch as a kind of queue for new features to enter into the next release.

In summary, Decidim developers that work on feature/... or fix/... branches will branch off from develop and must be merged back into develop.

Then, to start a new feature branch off from develop in the following way:

git checkout develop
git checkout -b feature/xxx

Implement the feature, and open a Pull Request as normal, but against develop branch. As this is the most common operation, develop is the default branch instead of master.

Please note that Decidim does not use the master branch.

Naming branches

We would like to have all branches following this namings:

Branch prefix Comment

chore/

Internal work. For instance, automatisms, etc. No production code change.

ci/

For continous integration related tasks. No production code change.

deps/

For dependency management tasks.

doc/

For changes to the documentation.

feature/

For new features for the users or for the Decidim command.

fix/

For feature bugfixing.

release/

With MAYOR.MINOR-stable. For instance, release/0.22-stable

refactor/

For refactorings related with production code.

test/

When adding missing tests, refactoring tests, improving coverage, etc.

backport/

We only offer support for the last mayor version.

After the prefix we recommend to add some words that describe what the change is doing, like a summary of the Pull Request title. For instance, some good branch names are:

  1. refactor/autocomplete

  2. feature/add-pagination-to-moderated-users

  3. fix/free-text-choice-answer

The rationale behind this is that we don’t like to have the issue number (fix/9123 or just 9123) as that difficults working with git.

Git commit messages and Pull Request titles

We recommend following this guide for making good git commit messages. It also applies to Pull Request titles. The summary is:

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why vs. how

Changelog

For keeping track of changes we like the rules of Keep A Changelog.

In the past we kept a file for all the development of a given version but that was difficult to maintain, as we had conflicts all the time. See the full discussion in #5908. We decided that:

  • We will not ask CHANGELOG for all the changes make on this repository. We will ask for CHANGELOG instructions only for special changes that really need some actions on part of developers/implementers or something to comunicate on the releases notes

  • The CHANGELOG will be manually made as part of the release process with the tooling from git (git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline) or github

Semantic Versioning

For releases we follow Semantic Versioning recommendations. Some details in our case:

  • Until v1 there could be changes in the API. We’ll let you know on the Release Notes for a given version

  • Upgrading on patch versions should be safe (for instance from 0.20.0 to 0.20.1). The only things that we add are bug fixes and new languages.