Conventions

GitFlow Branching model

The Decidim repository 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 naming convention:

Branch prefix Comment

chore/

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

ci/

For continuous 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 two mayor version. Learn more about Backports.

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 do not like to have the issue number (fix/9123 or just 9123) as that is difficult to work with in 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 communicate 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 will 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.

Accessibility

Most Decidim websites are under different regulations that require these services to follow accessibility guidelines to make them available to as wide audiences as possible. All user interface changes need to follow the accessibility guidelines.

For more information, refer to the Decidim accessibility guide.

JavaScript

  • Do not use CSS classes to bind JavaScript selectors or Ruby specs. Try to use an id (with the js- prefix) or a data-attribute as selector, in order to shrink the coupling between changing technologies.

  • Do not use jQuery if you can do it with vanilla JavaScript. Specially try to not introduce new code with jQuery, and if you are working with a legacy file take consider migrating it to vanilla JS.