Software Conventions

Index

  1. Introducion
  2. Version naming
  3. Git branch model
  4. TODO/IDEAS
  5. Documentation
  6. Specs to follow
  7. Bad Habits to avoid
  8. Programming guidelines

Introduction

Repository for IFAE software conventions

This repository will contain all IFAE conventions either in form of configurations (when possible) or documentation. The idea is to make it easier to share a same standard for everyone and to have a way of proposing changes (using PR).

To install IFAE configuration run ./install.sh

For Gentoo users (me) there is available a system package.

Version naming

We follow https://semver.org/ convention for version naming.

Git branch model

Main branches

  • master (or main nowadays): Production-ready state of source code. Can be deployed by CI/CD etc.

  • dev: Development branch. When code is ready to be released it should be merge to master. Then, on master branch, a tag should be created following the version naming.

When more than one person is modifying the same files, it should make a fork and send merge requests to the dev branch.

Hotfix branch

hotfix-*: Branch for fixing urgent bugs in production code, should be deleted after merge.

Hotfix branches can only branch off from main(otherwise it will be a normal fix).

Must merge back into: dev and main

  1. Hotfix branches are created from the master branch (e.g) git checkout -b hotfix-1.7.1 master
  2. Fix the bug in hotfix branch, when finished with bug fixing perform the following steps
    1. Merged hotfix branch into master
    2. Create Tag for future reference e.g (1.7.1)
    3. Merge changes back to develop branch
    4. Delete hotfix Branch

Topic branch

Topic branches may exist but it should be short-living. Those branches should start with “wip” for example “wip-ota”, once the work is completed it should be merged to dev branch and the wip branch should be removed.

(this git branching model is based on git flow and related derivatives. The main difference is that future and release branch have been removed and exception cases have been eliminated in a pursue to avoid unneeded complexity)

TODO/IDEAS

  • Make a wrapper arround git add so it automatically runs clang-format. This way it won’t matter which IDE or editor people use, it will always keep updated.

Documentation

BUGLOG

BUGLOG is a file which contains information about bugs which required an important dedication in time or bugs that were considered difficult to solve. Each entry should consist of the date (in dd/mm/YY format), commit id, name and description. Note that the commit author and the author of the BUGLOG entry may differ. For example: > 7/10/22 02fde590bb9f432cb36662bc4e4e2d06db114aaf droman: We faced this bug in this conditions and to solve it we needed to do this with that result, etc

Specs to follow

XDG directory specification which defines where should configurations be located and other things: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html