= Conventions

== GitFlow Branching model

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

* https://nvie.com/posts/a-successful-git-branching-model/[the original post]
* https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow[Atlassian tutorial]

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:

[source,bash]
----
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 two mayor version. Learn more about xref:develop:backports.adoc[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:

. refactor/autocomplete
. feature/add-pagination-to-moderated-users
. 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 difficults working with `git`.

== Git commit messages and Pull Request titles

We recommend following https://chris.beams.io/posts/git-commit/[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 https://keepachangelog.com/en/1.0.0/[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 https://github.com/decidim/decidim/issues/5908[#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 https://github.com/decidim/decidim/compare/v0.20.0...v0.20.1[github]

== Semantic Versioning

For releases we follow https://semver.org/[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 xref:develop:guide_accessibility.adoc[Decidim accessibility guide].

== JavaScript

* Do not use CSS classes to bind JavaScript selectors or Ruby specs. Try to use an `id` (with the `js-` preffix) or a `data-attribute` as selector, in order to shrink the couplish 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.