We use trunk based development. This means, in summary:
- One master repository with a single branch, the trunk, that is regularly deployed to production
- Trunk is always releasable
- Trunk contains work in progress. Code needs to implement refactoring techniques, such as branch by abstraction or feature flags, to provide backward compatibility until a work in progress features are fully developed and release ready.
- The team regularly contributes incremental code to the trunk in a contribution candence of no more than a couple of days
- Developers work on forked repositories on feature branches whose life is determined by the contribution cadence
- Code is shared with the team via pull requests
- CI System ensures quality gates are met by the resulting merge of the trunk and a pull request
- Pull requests that pass the quality gates are directly merged in the trunk in an automated way
- Issues define a problems to be solved
- Issues should be split up into smaller problems that fit the contribution cadence resulting in child issues
- Issues provide a discussion area to track the definition and break down of a problem, not its solution
- Each issue is fixed by a pull request in a single purpose feature branch
By splitting up an issue, you not only reduce the pain of merging each branch, you also deliver value sooner and make your repository history more readable.
We use single purpose feature branches. If a feature branch is delivering unrelated value or has multiple purposes, it indicates that the corresponding issue needs to be broken down.
Commits should tell a story of the contributions made by the team. Anyone should be able to check the repository history and understand what is going on and what changes where introduced when. See Telling stories with your git history post and presentation.
Large commits can be difficult to read, especially when they contain changes which are unrelated. Atomic commits are the smallest amount of code changed which delivers value.
Explain why you’ve made the change in the first place. This is the perfect opportunity to reflect on what you’re doing and to provide context – whether it’s to satisfy a user requirement, to fix a bug or to make another change easier to make in the future.
Use the following template for commit messages.
Issue Reference - Short one line title.
Value delivered
Description of what the change does
An explanation of why the change is being made.
Optionally, a discussion of alternatives that were considered.
The first line should be used to explain the value of the changes, rather than focussing on the implementation details. It’s always useful to explain what you’ve changed and why you’ve changed it. In some cases, it also helps, to provide further context such as explaining alternative solutions you’ve ruled out or providing external references.
When developing your code, you are bound to change direction or even make mistakes (most commonly introducing typos or bugs).
Before you share your commit history, it’s important to think about what is useful information for someone else to read. You shouldn’t think of your Git history as a “truthful” log of what you worked on step-by-step. Just as we refactor code, we should refactor our commits before sharing them with others.
The power of Git makes it simple to re-order, reword and refactor your commits until they tell the clearest story possible.
Use git rebase --interactive.
- Pull requests are used to track progress, discuss solutions and review code
- Pull requests reference the issue they provide a solution for
- Create the corresponding pull request for an issue as you start working on the solution
- Immediatly after creating the pull request, involve team members for reviewing even if there is yet nothing significant to review
- With the pull request open and team members involved you can discuss solutions to the problem or request feedback as needed without waiting for the final solution
- Pull requests with a lifespan bigger than the contribution cadence may indicate a problem (bad issue sizing, difficult problem, paralysis by analysis, ...)
Avoid comments in code. The code documentation should be comprised of code meta data captured in the repository, issues and pull requests:
- From the code we can trace the commit that introduced that code which contains a reference to the issue and the value delivered by this contribution
- From the commit we can trace the issue to gather macro information about the problem it solves, giving further context to the commit
- From the issue we can trace the pull request to track the decisions made to come up with a specific solution completing the the context of the code
The minimum quality gate is proving the build does not break
A project kanban board is shared among the team. The board contains the following columns:
- Backlog: Unprioritized issues, not ready for picking
- Prioritized: Prioritized and well defined issues ready for development
- In progress: Issues with the corresponding open pull request that are being worked on
- Done: Issues closed with the corresponding pull request merged to the trunk
- Issues are created and added to the backlog by any stakeholder.
- The product owner prioritizes and refines issues in the backlog.
- The product owner adds issues to the Prioritized column declaring an interest in providing a solution for an issue.
- Developers and product owner split up issues as needed adding them to the prioritized column.
- Developers pick issues from the prioritiezed column and start working on them
- When a pull request is successfully merged to the trunk, developers close the corresponding issue