Alex Volok

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 belongs
• Pipeline Description describes what the pipeline does, for instance: Build or Deploy

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.