Azure DevOps – Team Conventions and Standards
This is a second post in an Azure DevOps series related to team agreements and standards. In a previous one I’ve illustrated a practical implementation of a branching strategy using the YAML pipeline. This post is more about other important team decisions: a selection of the branching strategy that suits team needs, repository naming convention, folders structure, and naming of the pipelines.
Why are development team agreements important?
Imagine that you are part of a mid-size software development team. You and the other six developers have sharp skills and good intentions to get the product delivered in the best way. At some, point you realize that nearly every member has his own and mostly very rational interpretation and view on how git branches should be arranged, how folders should be structured, how database views should be named, and so on. That is a good moment for a team to initiate self-organization by setting up a few meetings and discuss and then define team agreements.
The most productive and successful software development teams are those who managed to agree on one shared thing – consensus. A consensus that was discussed and sincerely agreed by an entire team gives a feeling of inclusiveness, that all members being heard and their input is evaluated into a set of conventions.
A few examples of such topics to be discussed and agreed upon:
- Git branching strategy
- Repository naming convention
- Repository folder structure
- Deployment pipelines naming convention
- Code formatting and comments
- Database object naming conventions
Let’s discuss some of these items.
Git Branching Strategy
Perhaps, this is the most basic topic to agree on an early phase – how the team wants to arrange their Git branches and what branching policies to apply. The branching strategy also depends on frequency of the releases and the size of the product and the team. Luckily, there are plenty of adopted strategies, and the most popular:
- Git Flow is perhaps one of the oldest and most used branching strategies. It is ideally suited for projects that have a scheduled release cycle.
- GitHub Flow introduced by GitHub to deliver very frequent releases
- Release Flow is Microsoft’s model of branching and merging. It is how they manage nearly all their production deployments and releases. They also use Azure DevOps internally so it supports it well.
Repository Naming Convention
General naming recommendations for Git repositories are:
- use lower case
- use dashes
Reference: A popular StackOverflow discussion: Is there a naming convention for git repositories?
Format:
lowercase-with-hyphens
Examples:
sql-ansible # not SQL_ANSIBLE sql-azure-db # not SqlAzureDB adf-marketing # not ADF-Marketing
Repository Folder Structure
Another topic to discuss how the folders are structured in the repository. A typical top-level directory layout:
. ├── build # YAML release pipeline definitions ├── docs # Documentation files (alternatively `doc`) ├── resources # Resource files, like ARM templates (alternatively `res`) ├── src # Source files (alternatively `lib` or `app`) ├── tests # Automated tests (alternatively `spec` or `test`) ├── scripts # Tools and utilities (alternatively 'tools') └── README.md
In such a structure, the most used folder is src
which contains a source code to build.
Pipeline Naming Convention
Format
{Repo Name} - { Pipeline Description }
Where:
Repo Name
is the name of the repository to which the pipeline belongsPipeline Description
describes what the pipeline does, for instance:Build
orDeploy
Example:
my-app-repo - build&release # not Alex_buildpipeline1
This approach helps to keep pipelines in DevOps UI visually bounded to related repositories
Final words
This post is about the importance of agreements in software development teams and how these agreements can bring a team to a state when the consensus is taken. It also provides an example of naming conventions, folder structures of repositories, and branching strategies to choose. However, the final decision is to be done by a certain team and according to their needs.
Many thanks for reading.