Code Submission Guidelines

This document defines the code collaboration standards for the BitzOrcas.Modern team. Every contributor must follow these conventions to ensure a clean commit history, an efficient review process, and architectural guardrails that don’t silently regress.

1. Branch Naming Conventions

Branch names follow the <type>/<description> pattern — all lowercase, words separated by hyphens (-).

Naming rules

• All lowercase: feature/add-user-auth (not Feature/Add-User-Auth)
• Hyphen-delimited: bugfix/fix-null-exception (not bugfix/fix_null_exception)
• Keep it concise: 3–5 words that clearly communicate intent
• No personal prefixes: Don’t use john/feature-xxx — branches belong to the team

Branching strategy

main          ──●────●────●────●────●────  (production-ready, protected)
                 \       \       \
feature/xxx      ●──●──●  \       \        (feature branch, cut from main)
                           \       \
release/v1.2.0              ●──●───●       (release branch, frozen except bug fixes)
                                     \
hotfix/urgent                         ●──● (hotfix, cut directly from main)

• main: Protected branch. Direct pushes are blocked. All changes must arrive via pull request.
• Feature branches: Cut from main; merged back via PR when complete.
• Release branches: Cut from main for version freezing and pre-release testing. Bug fixes happen here and are back-merged to main.
• Hotfix branches: Cut from main; merged to both main and the active release branch after the fix.

2. Commit Message Format

The team follows the Conventional Commits specification:

<type>(<scope>): <subject>

[body]

[footer]

2.1 Type

2.2 Scope

Scope is optional and identifies the affected module or building block:

2.3 Subject

• Use the imperative mood: “add” not “added”, “fix” not “fixed”
• Keep it under 72 characters
• Do not end with a period
• Start with a lowercase letter (English commits)

2.4 Body (optional)

Explain why the change was made and how it was implemented. Wrap at 72 characters per line.

2.5 Footer (optional)

• Breaking Changes: Prefixed with BREAKING CHANGE:, describing the incompatible change and migration path.
• Issue References: Closes #123 or Refs #456

2.6 Examples

feat(workflow): add canary deployment binding

Introduce DeploymentBinding to pin workflow definitions to (Tenant, Office)
dimensions. New instances pick up the latest deployment automatically; in-flight
instances are unaffected.

- Add IDeploymentService.PublishAsync method
- Add WorkflowDeployment persistence entity
- Add CanaryDeploymentTests integration suite

Closes #234

fix(audit): correct platform tenant shard routing

AuditShardRouter returned null for TenantId == "PLATFORM", causing audit records
to land in the default shard.

Root cause: ShardKeyResolver did not handle the platform tenant sentinel value.
Fix: introduce PlatformShardFallback constant, used when tenant is PLATFORM.

BREAKING CHANGE: IShardKeyResolver.Resolve now accepts CancellationToken

3. Code Review Standards

3.1 Review Workflow

Developer submits PR
      │
      ▼
  ┌──────────┐       ┌──────────────┐
  │ CI checks │──────▶│ Fix and push │
  └─────┬─────┘  fail └──────────────┘
        │ pass
        ▼
  ┌────────────────┐
  │ Assign reviewer │
  └───────┬────────┘
          ▼
  ┌───────────────┐     ┌────────────────┐
  │ Reviewer inspects │◀────│ Developer revises │
  └───────┬───────┘  changes └────────────────┘
          │ approved
          ▼
    Need second reviewer?
    │              │
   Yes (core)     No
    │              │
    ▼              │
  ┌───────────────┐│
  │ 2nd reviewer  ││
  └───────┬───────┘│
          │ approved│
          ▼        ▼
     ┌────────────────┐
     │   Merge to main │
     └────────────────┘

3.2 Review Checklist

Every reviewer must verify the following before approving a PR:

Architecture Compliance

• Are module boundaries respected? Does cross-module communication go through *.Contracts only?
• Is the dependency direction correct? Endpoints → Application → Domain — no reverse references
• Were any new external dependencies introduced? Are they centrally managed in Directory.Packages.props?

Code Quality

• Does naming follow team conventions? (PascalCase for public members, _camelCase for private fields)
• Are public APIs documented with XML doc comments?
• Are there obvious code smells? (long methods, deep nesting, duplication)
• Does error handling use Result / Result<T> instead of throwing exceptions?
• Is reflection avoided in AOT-compatible projects?

Test Coverage

• Do new features include corresponding unit tests?
• Do persistence-related changes include integration tests?
• Do module boundary changes include architecture test assertions?
• Is CI fully green? (build + test + trim-publish)

Security

• Are there any hardcoded secrets, connection strings, or API keys?
• Is user input validated?
• Is tenant isolation correctly implemented?
• Are sensitive operations audit-logged?

3.3 Review Etiquette

• Critique the code, not the author: Comments address the implementation, never the person.
• Explain the “why”: Don’t just say “change X to Y” — explain why Y is better in this context.
• Categorize severity: Use labels to distinguish blocking issues from suggestions:
  • [must]: — Must be addressed before merge (blocking)
  • [should]: — Should be addressed (non-blocking)
  • [nit]: — Nice to have (entirely optional)

3.4 Approval Rules

4. Complete PR Workflow Guide

4.1 Setup: Fork & Clone

Note: Internal team members typically clone the main repository directly and create branches. The fork workflow below applies to external contributors or cross-team collaboration scenarios.

# 1. Fork the main repository via the Git platform's web UI

# 2. Clone your fork locally
git clone https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git
cd BitzOrcas.Modern

# 3. Add the main repository as the upstream remote
git remote add upstream https://github.com/shbitz/BitzOrcas.Modern.git

# 4. Verify remote configuration
git remote -v
# origin    https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git (fetch)
# origin    https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git (push)
# upstream  https://github.com/shbitz/BitzOrcas.Modern.git (fetch)
# upstream  https://github.com/shbitz/BitzOrcas.Modern.git (push)

4.2 Create a Feature Branch

# 1. Ensure you're on main and in sync with upstream
git checkout main
git fetch upstream
git rebase upstream/main

# 2. Create a feature branch with a conventional name
git checkout -b feature/workflow-canary-deploy

# 3. (Optional) Push an empty branch to confirm the name
git push -u origin feature/workflow-canary-deploy

4.3 Develop & Commit

# 1. Make your code modifications and save files

# 2. Check what's changed
git status

# 3. Stage changes — prefer interactive staging to avoid bulk commits
git add -p

# Or stage specific files
git add src/Platform/BitzOrcas.Workflow/Engine/DeploymentService.cs

# 4. Commit following Conventional Commits
git commit -m "feat(workflow): add canary deployment binding

Introduce DeploymentBinding to pin workflow definitions to (Tenant, Office)
dimensions. New instances pick up the latest deployment automatically; in-flight
instances are unaffected.

- Add DeploymentBinding persistence entity
- Add PublishDeploymentAsync API
- Add CanaryDeploymentTests integration suite"

# 5. Sync with upstream regularly (avoid large merge conflicts)
git fetch upstream
git rebase upstream/main

# If conflicts arise, resolve them and continue:
git rebase --continue
# Or abort the rebase:
git rebase --abort

# 6. Push your branch (force-push after rebasing)
git push -u origin feature/workflow-canary-deploy
# If you've already pushed and rebased:
git push --force-with-lease origin feature/workflow-canary-deploy

4.4 Open a Pull Request

# 1. Push your final changes
git push origin feature/workflow-canary-deploy

# 2. Create a Pull Request via the Git platform's web UI:
#    - Base branch: upstream/main (or origin/main)
#    - Compare branch: feature/workflow-canary-deploy

PR Description Template

When creating a PR, use the following template:

## Summary
<!-- Briefly describe what this PR does and why -->

## Change Type
- [ ] New feature (feat)
- [ ] Bug fix (fix)
- [ ] Refactoring (refactor)
- [ ] Documentation (docs)
- [ ] Testing (test)
- [ ] Build / dependencies (chore)
- [ ] Performance (perf)

## Affected Areas
<!-- Mark the modules or building blocks affected -->
- [ ] Workflow Engine
- [ ] Authentication / Authorization
- [ ] Audit
- [ ] Files / Notifications / Webhooks / Chat / Tickets / Billing / Catalog
- [ ] Building Blocks
- [ ] CLI Tools
- [ ] CI / Build System
- [ ] Documentation

## Test Plan
<!-- Describe how you tested these changes -->
- [ ] Unit tests added / updated
- [ ] Integration tests added / updated
- [ ] Architecture tests pass
- [ ] Manual verification steps (if any):

## Architecture Impact
<!-- Does this PR involve any of the following? -->
- [ ] Public contract changes (*.Contracts assembly)
- [ ] New external dependency
- [ ] Database schema change
- [ ] Breaking Change
- [ ] No architectural impact

## Linked Issues
<!-- Use Closes / Refs keywords to link issues -->
Closes #

## Screenshots / Logs (optional)
<!-- Attach any relevant UI screenshots or log output -->

4.5 During Code Review

# After receiving review feedback, revise code locally and verify

# 1. Make the requested changes

# 2. Commit as a fixup (to be squashed later)
git add .
git commit -m "fixup: address review feedback on DeploymentService error handling"

# 3. Push the update
git push origin feature/workflow-canary-deploy

# 4. Reply to review comments on the PR, resolving addressed threads

# 5. Once all reviews are approved, clean up the commit history
git rebase -i upstream/main

# In the editor:
#   pick <commit1> feat(workflow): add canary deployment binding
#   fixup <commit2> fixup: address review feedback
#   fixup <commit3> fixup: add missing doc comments

# 6. Force-push the cleaned history
git push --force-with-lease origin feature/workflow-canary-deploy

4.6 Merge & Clean Up

The merge strategy is configured by the team’s CI/CD settings — typically Squash Merge (all PR commits squashed into one) or Rebase Merge (linear history preserved).

# After the PR is merged, clean up your local environment:

# 1. Switch back to main and pull the latest
git checkout main
git pull upstream main

# 2. Delete the local feature branch
git branch -d feature/workflow-canary-deploy

# 3. Delete the remote feature branch (if not auto-deleted on merge)
git push origin --delete feature/workflow-canary-deploy

# 4. Prune stale remote-tracking branches
git remote prune origin

5. FAQ

5.1 How do I resolve merge conflicts?

# 1. Sync latest from main
git fetch upstream
git rebase upstream/main

# 2. If conflicts arise, Git pauses and marks conflicting files
#    Edit the files — remove conflict markers (<<<<<<< / ======= / >>>>>>>)

# 3. Mark as resolved
git add <resolved-file>

# 4. Continue the rebase
git rebase --continue

# 5. If the conflicts are too complex, abort
git rebase --abort

5.2 What if I accidentally commit sensitive information?

# 1. Immediately change the exposed credentials / revoke keys

# 2. If not yet pushed, use interactive rebase to remove the offending commit
git rebase -i HEAD~3

# 3. If already pushed, contact a repo admin immediately to scrub history
#    Note: pushed secrets should be considered compromised — rotate them immediately

5.3 What do I do when CI fails?

1. Inspect the CI logs to determine the root cause
2. If it’s a code issue (build error, test failure), fix locally and push again
3. If it’s a CI infrastructure issue (timeout, network error), request a re-run
4. Do not merge until CI is fully green

6. Project Structure Quick Reference

src/
├── Framework/          → Framework foundation, source generators, and infrastructure adapters
│   ├── BitzOrcas.Domain/              → Domain primitives (Entity, AggregateRoot, Result)
│   ├── BitzOrcas.Application/         → CQRS abstractions (Command, Query, Pipeline)
│   ├── BitzOrcas.DI.* / Endpoint.*    → Compile-time DI and endpoint generation
│   ├── BitzOrcas.Infrastructure.*/    → Persistence / cache / messaging / storage adapters
│   └── BitzOrcas.Workflow/            → Self-built workflow engine (zero ORM dependency)
├── Platform/           → Platform modules grouped by capability (current physical layout)
├── Modules/Sandbox/    → Golden Use Case and business-module layout example
├── Hosts/              → Gateway, Api, JobHost, AppHost, and ServiceDefaults
└── Tooling/            → CLI tools (4 tools)
    ├── BitzOrcas.CodeGeneration.Cli/  → Code generation CLI
    ├── BitzOrcas.Modern.Templates/    → dotnet new solution template
    ├── BitzOrcas.SeedData.Exporter/   → Seed data exporter
    └── BitzOrcas.Workflow.Migrator/   → Workflow definition migrator
tests/                  → Unit, application, architecture, integration, parity, consumer, and commercial gates

This document is maintained by the BitzOrcas.Modern team. To suggest improvements, submit a PR to this documentation repository.