Repository management

A well-organized repository can make a big difference in the development process. It helps developers find the code they need quickly and easily and also help keep the codebase clean. Follow below practices to keep repositories manageable, and easy to understand.

Note

Please read about Version Control in general first.

Use a single repository for each project: it is easier to keep track of changes of projects. Additionally, if code has to be shared with someone, this way gives more granular control over access rights.

Keep main branch clean: main branch has to be stable and working correctly all the time. This means that every change that goes into main should be tested, reviewed and approved before it's merged.

Avoid long-running branches: long-running branches can lead merge conflicts, which can be difficult to resolve.

Make frequent, small commits: it makes it easier to see what changed between commits and revert changes if necessary.

Test changes before committing them: committed changes must not break the build. Before you commit any changes ensure that the code can be built and all test cases are green.

Write good commit messages: commit messages are like a change log of the codebase. They should be clear, concise and descriptive. They help others to understand the purpose of a change without digging through the code itself.

Follow branching strategy: read more about branching strategy here and here.

Follow code review process: consult with Code Review page for general information and Code Review for .NET specific guidelines.

Standard folder structure

$/
+-- README.md
+-- .gitignore
+-- {solution}.sln
|
+-- .pipelines/
│   +-- templates
|   |
+-- bin/
|   |
+-- build/
│   +-- file011.txt
|   |
+-- docs/
│   +-- file011.txt
|   |
+-- infrastructure/
│   +-- modules
|   |
+-- lib/
│   +-- file011.txt
|   |
+-- obj/
|   |
+-- packages/
|   |
+-- src/
│   +-- SolutionFolder1
│   +-- SolutionFolder2
|   |
+-- tests/
│   +-- file011.txt
|   |
+-- tools/

.pipelines: CI / CD pipeline definitions in yaml format
.pipelines/templates: Reusable yaml templates for CI / CD pipelines
bin: build outputs (only in local repository)
build: Build customizations (custom msbuild files/psake/fake/albacore/etc) scripts
docs: Documentation markdown files, help files etc.
infrastructure: ARM (Bicep) files for infrastructure deployment (IaC)
infrastructure/modules: Reusable modules for infrastructure deployment
lib: 3rd party libraries that are not available in NuGet packages
obj: temporary files created by build process (only in local repository)
packages: NuGet packages (only in local repository)
src: Main projects (the product code)
tests: Test projects
tools: Tools that are required by the project
.gitignore: Specifies intentionally untracked files that Git should ignore
README.me: Contains essential information about the repo's project.

.gitignore

Build artifacts, NuGet packages, local configurations should not be committed into the repository. Use below snippet for .NET development.

## Ignore Visual Studio temporary files, build results, and
## files generated by popular Visual Studio add-ons.

# User-specific files
*.rsuser
*.suo
*.user
*.userosscache
*.sln.docstates
*.userprefs

# Build results
[Dd]ebug/
[Dd]ebugPublic/
[Rr]elease/
[Rr]eleases/
x64/
x86/
[Ww][Ii][Nn]32/
[Aa][Rr][Mm]/
[Aa][Rr][Mm]64/
bld/
[Bb]in/
[Oo]bj/
[Ll]og/
[Ll]ogs/

# Visual Studio cache/options directory
.vs/

# MSTest test Results
[Tt]est[Rr]esult*/
[Bb]uild[Ll]og.*

# .NET Core
project.lock.json
project.fragment.lock.json
artifacts/

# Files built by Visual Studio
*_i.c
*_p.c
*_h.h
*.ilk
*.meta
*.obj
*.iobj
*.pch
*.pdb
*.ipdb
*.pgc
*.pgd
*.rsp
*.sbr
*.tlb
*.tli
*.tlh
*.tmp
*.tmp_proj
*_wpftmp.csproj
*.log
*.tlog
*.vspscc
*.vssscc
.builds
*.pidb
*.svclog
*.scc

# Visual Studio profiler
*.psess
*.vsp
*.vspx
*.sap

# Visual Studio Trace Files
*.e2e

# NuGet Packages
*.nupkg
# NuGet Symbol Packages
*.snupkg
# The packages folder can be ignored because of Package Restore
**/[Pp]ackages/*
# except build/, which is used as an MSBuild target.
!**/[Pp]ackages/build/
# Uncomment if necessary however generally it will be regenerated when needed
#!**/[Pp]ackages/repositories.config
# NuGet v3's project.json files produces more ignorable files
*.nuget.props
*.nuget.targets

# VS Code files for those working on multiple tools
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
*.code-workspace

# Local History for Visual Studio Code
.history/

README.md

Use below template for .NET projects. Optional sections are at the end of the template and can be omitted. Don't forget to add it to the Table of Contents section if one of the optional sections is added to the project's readme file.

# <Project-Name>

## Description

Provide a short description explaining the what, why, and how of the project. Use the following questions as a guide:

- Why this project was built?
- What problem does it solve?

## Table of Contents

If your README is long, add a table of contents to make it easy for users to find what they need.

- [Installation](#installation)
- [Usage](#usage)
- [Tools](#tools)

## Installation

What are the steps required to install the project? Provide a step-by-step description of how to get the development environment running.

## Usage

Provide instructions and examples for use. Include screenshots as needed.

To add a screenshot, create an `assets/images` folder in the repository and upload the screenshots to it. Then, using the relative filepath, add it to the README using the following syntax:

![alt text](assets/images/screenshot.png)

## Tools

Describe the technology stack of the project and provide a list of tools that are used for the development of the application.

## Badges (Optional)

Badges aren't necessary, per se, but can provide a quick, clean, visual status of the project. 

## Features (Optional)

If the project has a lot of features, list them here.

## Tests (Optional)

Write tests for the application and provide examples on how to run them here.