Logo Header

Company playbook

Git Workflow

Prerequisites and definitions

  • develop is the integration branch
  • Gitlab is the issue tracker
  • We are using Gitlab or GitHub as git server
  • REPO is our project repository on git server (eg. git@gitlab.sparkfabrik.com:sparkfabrik/websites/sparkfabrik-tech-blog.git)

Steps

Follow these steps to achieve code serenity:

Daily work

  • Clone repository: git clone REPO
  • Pick the feature/user-story to work out from the Board: say it is #12345 - Integrate with billing server
  • Create a new branch with the following name convention: feature/[#issue-id]_[feature_title-slug] and move on it: git switch -c feature/12345_integrate_with_billing_server
  • Working the issue, always add your changes to the stage using git add -p and interactively rewiewing all changes (this is important when code is autogenerated and can overwrite other's work: i.e. a Drupal Feature)
  • Commit your code following the Conventional Commits standard: git commit -m 'feat(billing): admins can now store billing-id for a client'
  • Push it on a remote so that if your PC is blasted by aliens you can avoid being fired

When your issue is done

  • Fetch develop branch, keep integration branch fetched: git fetch
  • Rebase your branch over develop: git rebase origin/develop
  • Push to your branch: git push -f or better yet git push -f origin feature/12345_integrate_with_billing_server
  • Gitlab flow: Head to Gitlab and open a Merge Request from your branch towards develop
  • GitHub flow: Head to GitHub and open a Pull Request from your branch towards develop
  • Address possible feedback in your branch and keep pushing over it
  • When you are done the MR (or PR) will be merged by a peer or gatekeeper
  • Switch back on develop and reset to the latest develop: git fetch && git reset --hard origin/develop

Redo from start and live happy! :)

Conventional Commits

We follow the Conventional Commits specification for all new commits. It makes the history readable at a glance and enables automated tooling (changelogs, semantic versioning, etc.).

Structure

(): 

[optional body]

[optional footer(s)]
  • type – what kind of change: feat, fix, docs, style, refactor, test, chore, ci, perf, revert
  • scope – the area of the codebase affected (optional but encouraged): e.g. billing, auth, api
  • subject – short imperative description, lowercase first letter, no trailing period
  • body – motivation and context (wrap at ~72 chars); must include the full issue reference, e.g. Refs: sparkfabrik/company-playbook#299
  • footer – breaking changes (BREAKING CHANGE: …) or issue references (Closes #12345)

Examples

feat(billing): add billing-id storage endpoint for admin users

Refs: sparkfabrik/company-playbook#12345
fix(auth): prevent session token reuse after logout

Refs: sparkfabrik/company-playbook#12345
docs(git-workflow): document conventional commits standard

Refs: sparkfabrik/company-playbook#12345
feat(api)!: rename /users endpoint to /accounts

BREAKING CHANGE: all clients must update their base URL.
Refs: sparkfabrik/company-playbook#9876

Tip: Use the SparkFabrik skill for Conventional Commits to get AI-assisted commit messages locally with Claude Code or other terminal agents.

Legacy format (deprecated)

The old format [#issue-id]: Commit message (e.g. #12345: Admins can now store billing-id) is no longer the standard. It is still supported where existing conventions require it, but must not be used for new work.

Pro-tips

  • When you open a branch to work out a user-story, and have to name it against the naming convention we exposed, consider that the title part is amendable at need, the issue-id is not!
  • When you create a new commit, try to keep your message short but significant! #12345: More love means nothing! A good rule of thumb is: don't write what you did (others can see the code by themselves) but why you did it
  • If your work spans over a long time (days) we advice you rebase it onto develop at least daily: git fetch && git rebase origin/develop (solve conflicts if they arise and push with -f options).
  • You can use an optional -i parameter when you rebase your branch onto develop, this way: git rebase origin/develop. In that case, you can pick only the commits you want to rebase, save and quit the interactive editor. Be warned: there shall be dragons!
  • If you are working on a branch and you need to switch to another one, you can use git stash to save your work and git stash pop to restore it later
  • If you don't see automated tools linting or testing the code while committing and pushing, please contact your team leader or the tech lead to setup the environment
  • Please try to keep one commit per issue, and one issue per commit. This way, if you need to revert a commit, you can do it without reverting other's work

Useful resources

Last updated on 29 May 2026