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:
-
refactor/autocomplete
-
feature/add-pagination-to-moderated-users
-
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:
-
Separate subject from body with a blank line
-
Limit the subject line to 50 characters
-
Capitalize the subject line
-
Do not end the subject line with a period
-
Use the imperative mood in the subject line
-
Wrap the body at 72 characters
-
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.