Here’s a well-structured and formatted version of your branch naming convention, Git workflow, and API versioning steps:

✅ Recommended Branch Naming Convention

1️⃣ Main Development Branch

main or develop → Always contains the latest stable or development version.

2️⃣ Version-Specific Branches

release/v1.0 → First stable version
release/v2.0 → Second major update
feature/v3.0-new-payment-module → Feature branch for a new module in v3.0

3️⃣ Bug Fix & Hotfix Branches

hotfix/v1.0.1 → Hotfix for v1.0
bugfix/v2.1-db-performance → Bug fix for database performance in v2.1

🛠 Steps to Implement This in Git

1️⃣ Create a New Version Branch

To create a new branch for API version v2.0:

git checkout -b release/v2.0
git push origin release/v2.0

2️⃣ Switch Between API Versions

To work on v1.0:

git checkout release/v1.0

To work on v2.0:

git checkout release/v2.0

3️⃣ Merging API Updates

Once v2.0 is stable and ready for production, merge it into main:

git checkout main
git merge release/v2.0
git push origin main

📌 Branch Strategy Usage Guide

Scenario	Branch Name
Major API updates (breaking changes)	`release/vX.X`
New feature in a specific version	`feature/vX.X-feature-name`
Bug fixes in an older API version	`bugfix/vX.X-description`
Urgent hotfixes (security, critical bugs)	`hotfix/vX.X.X`

🚀 Setting Up API Versioning in `Ncs.Cqrs`

✅ Step 1: Create a New Git Branch for Version 1.0

Since you want to mark this as stable (v1.0), create a release branch:

git checkout -b release/v1.0
git push origin release/v1.0

✅ Step 2: Install API Versioning Packages

Inside your project folder, install the required API versioning dependencies:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.API explorer
dotnet add package Swashbuckle.AspNetCore

✅ Step 3: Configure API Versioning in `Program.cs`

Modify Program.cs to enable API versioning.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// 🔹 Add API Versioning
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),      // /api/v1/orders
        new QueryStringApiVersionReader("api-version"),  // ?api-version=1.0
        new HeaderApiVersionReader("X-API-Version")  // Header: X-API-Version: 1.0
    );
});

// 🔹 Configure API Explorer for Swagger
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// 🔹 Configure Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo
        {
            Title = $"Ncs.Cqrs API {description.ApiVersion}",
            Version = description.ApiVersion.ToString()
        });
    }
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
}

app.UseAuthorization();
app.MapControllers();

app.Run();

✅ Step 4: Apply Versioning to Your Controllers

Modify your existing controllers by adding API version attributes.

OrdersController (v1.0 - Stable)

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v1 API" });
    }
}

Now, this controller only works for v1.0.

✅ Step 5: Push Changes to GitHub

Once you've added API versioning, push your changes to the release/v1.0 branch.

git add .
git commit -m "Added API versioning (v1.0 stable)"
git push origin release/v1.0

✅ Step 6: Test API Versioning

Test using URL Versioning

GET http://localhost:5000/api/v1/orders

Test using Query String

GET http://localhost:5000/api/orders?api-version=1.0

Test using Header

Header: X-API-Version: 1.0
GET http://localhost:5000/api/orders

🐞 Bug Fixing Workflow for `v1.0` API

Since v1.0 has already released, follow this workflow to create a hotfix branch.

1️⃣ Create a Hotfix Branch for v1.0

git checkout -b hotfix/v1.0.1 release/v1.0
git push origin hotfix/v1.0.1

2️⃣ Apply the Fix & Commit

git add .
git commit -m "🐞 Fixed issue with API Order update status in v1.0"
git push origin hotfix/v1.0.1

3️⃣ Merge the Fix into `release/v1.0`

git checkout release/v1.0
git merge hotfix/v1.0.1
git push origin release/v1.0

4️⃣ Merge the Fix into `main`

If main is still on v1.0, merge the fix into main:

git checkout main
git merge release/v1.0
git push origin main

5️⃣ Tag the Release (`v1.0.1`)

git tag v1.0.1
git push origin v1.0.1

6️⃣ Delete the Hotfix Branch (Cleanup)

git branch -d hotfix/v1.0.1
git push origin --delete hotfix/v1.0.1

🚀 Build & Publish API

Run in API project folder using Command Prompt:

dotnet build --configuration Release
dotnet publish --configuration Release --output C:\App\CanteenApi

🎯 Final Workflow Summary

Create Hotfix Branch → hotfix/v1.0.1
Apply Fix & Commit Changes
Merge into release/v1.0
Merge into main (if main is still on v1.0)
Tag Release (v1.0.1)
Delete Hotfix Branch

This ensures v1.0 remains stable while allowing fixes. 🚀

Branching Strategy for API Versioning