[Core] Reorganise the repository branches for v5

[dvoituron]

Reorganise the repository branches for v5: archive-v4 and dev (v5 code)

📅 UPDATED: 2026-09-16

Context and motivation

Version 5 will soon become the main development version of Fluent UI Blazor.

• dev currently contains the version 4 codebase.
• dev-v5 contains the upcoming version 5 codebase.

The repository will keep dev as its default branch and replace its content with the version 5 codebase.
The existing version 4 codebase will first be preserved in archive-v4.

Target branch structure

• archive-v4: version 4 maintenance.
• dev: default branch and active version 5 development.

Action plan

1. Prepare dev for the v4 archive

• Temporarily freeze merges and direct pushes to dev and dev-v5.
• Update v4 CI references from dev to archive-v4.
• Update version calculation to recognize archive-v4 as the v4 maintenance branch.
• Update the v4 Dependabot configuration.
• Update v4-specific scripts, badges, and links.
• Verify that the v4 builds and tests pass.

2. Create archive-v4

• Create archive-v4 from the latest commit on dev: git switch -c archive-v4
• Push archive-v4 to the Microsoft repository.
• Confirm that dev and archive-v4 point to the same commit before continuing.
• Protect archive-v4 against accidental deletion or force pushes.

3. Prepare dev-v5 for its future dev name

• Update GitHub Actions and Azure Pipelines triggers from dev-v5 to dev.
• Update version calculation to recognize dev as the v5 development branch.
• Update the v5 Dependabot configuration.
• Replace dev-v5 references in documentation, contribution instructions, scripts, badges, and links.
• Verify that the v5 builds and tests pass.
• Freeze dev-v5 after the final preparation changes are merged.

4. Merge the v5 history and content into dev

• Fetch the latest dev and dev-v5 branches in a dedicated clean clone.
• Merge dev-v5 into dev with --allow-unrelated-histories because the branches have no common ancestor.
• Replace the merge result with the exact tree from dev-v5 before committing.
• Confirm that the resulting commit has both the v4 and v5 histories as parents.
• Confirm that the resulting dev content is identical to dev-v5.
• Push the merge commit to dev, using an approved temporary protection bypass if required.
• Do not squash or rebase this merge, as doing so would not connect both histories.

## ---

git fetch origin

git switch dev-v5
git pull --ff-only origin dev-v5

git switch dev
git pull --ff-only origin dev

git merge dev-v5 --allow-unrelated-histories --no-commit
git restore --source=dev-v5 --staged --worktree -- .
git commit -m "Merge dev-v5 into dev and adopt its content"

## ---

# Identical content
git diff --exit-code dev-v5

# All commits in dev-v5 are accessible from dev
git merge-base --is-ancestor dev-v5 dev

# If both commands return the code 0, push dev:
git push origin dev

# Create a branch for the future PR
git switch -c merge-dev-v5-into-dev
git push -u origin merge-dev-v5-into-dev

# Create the PR
gh pr create --base dev --head merge-dev-v5-into-dev --title "Merge dev-v5 into dev and adopt its content" --body "Merge dev-v5 history into dev and adopt its current content."

# Merge it into dev
gh pr merge merge-dev-v5-into-dev --repo microsoft/fluentui-blazor --merge --delete-branch --admin

## ---

# Verify the result
git switch dev
git pull --ff-only origin dev
git merge-base --is-ancestor dev-v5 dev

5. Verify branch protection and repository settings

• Confirm that dev remains the GitHub default branch.
• Update the required checks and protection rules on dev for v5 development.
• Verify the protection rules on archive-v4 for v4 maintenance.
• Verify that the dev - Restrict deletions ruleset still applies correctly.
• Remove protection from dev-v5 only when it is ready to be deleted.

6. Verify pull requests

• Retarget existing v4 pull requests from dev to archive-v4.
• Retarget existing v5 pull requests from dev-v5 to dev.
• Review each pull request diff after changing its base branch.
• Update the base branches used by bots and other automation.

7. Update external services

• Update Azure DevOps branches and policies.
• Set dev as the Azure Static Web Apps production_branch.
• Verify GitHub Actions and Azure Pipelines triggers.
• Update external scripts, dashboards, badges, webhooks, and links.
• Verify that development packages are published from dev.
• Keep the required v4 pipelines active on archive-v4.

8. Validate the migration

• Create a small v4 test pull request targeting archive-v4.
• Create a small v5 test pull request targeting dev.
• Verify CI, required checks, branch policies, version calculation, and package publishing.
• Verify documentation and demo deployments.
• Confirm that dev still has the exact content of dev-v5.
• Confirm that the former dev-v5 history is an ancestor of the new dev history.

9. Remove obsolete branches

• Delete dev-v5 after all pull requests have been retargeted and validation has completed.
• Keep main as the release branch for version 5
• Confirm that the final development branches are dev and archive-v4.

git fetch origin

git switch main
git pull --ff-only origin main

git merge origin/dev --no-commit --no-ff
git restore --source=origin/dev --staged --worktree -- .
git commit -m "Merge dev into main and adopt its content"

# Validations
git diff --exit-code HEAD origin/dev
git merge-base --is-ancestor origin/dev main

git push origin main

10. Notify contributors

• Announce that dev remains the default branch and now contains version 5.
• Announce that archive-v4 is the version 4 maintenance branch.
• Ask contributors to run git fetch --prune and update their local branches.
• Ask fork owners to fetch dev and archive-v4 from the Microsoft repository and publish them to their forks.
• Ask contributors with existing v5 work to rebase their branches onto the new dev.

11. Resume development

• End the temporary merge freeze after both test pull requests pass.
• Resume v4 maintenance only on archive-v4.
• Target dev for all new v5 development.
• Monitor the first builds, package publications, and deployments after the migration.

12. Rollback readiness

• Keep archive-v4 unchanged as the preserved v4 state.
• Keep dev-v5 until the migration has been fully validated.
• If rollback is required, revert the merge commit using its v4 parent instead of rewriting dev history.
• Restore the previous CI, protection, and external service settings after a rollback.

[vnbaaij]

Looks good. We need to add a step to clarify how someone who forked the repo can get in the correct setup of branches again (ie the problem Marvin was having)

[MarvinKlein1508]

For me as reference:

git remote add upstream https://github.com/microsoft/fluentui-blazor.git
git fetch upstream
git switch -c <branch-name> --track upstream/<branch-name>
git push -u origin <branch-name>