Contributing

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/azure-smb-rf.git
cd azure-smb-rf

Open in Dev Container (recommended): Press F1 → Dev Containers: Reopen in Container
Install dependencies:
Terminal window
```
npm install
```

Branch Naming

Type	Pattern	Example
Feature	`feat/description`	`feat/add-cosmos-db-module`
Bug fix	`fix/description`	`fix/vpn-gateway-timeout`
Documentation	`docs/description`	`docs/update-readme`
Refactor	`refactor/description`	`refactor/simplify-networking`
CI/config	`ci/description`	`ci/add-terraform-workflow`

Domain-scoped branches (docs/, agents/, skills/, infra/, scripts/, instructions/) are restricted to files within that domain. Use feat/ or fix/ for cross-cutting changes.

Commit Conventions

This project uses Conventional Commits:

<type>(<scope>): <description>

Type	Description	Version Bump
`feat`	New feature	Minor (0.X.0)
`fix`	Bug fix	Patch (0.0.X)
`docs`	Documentation only	None
`refactor`	Code change, no feature/fix	None
`ci`	CI/config changes	None
`chore`	Build process, dependencies	None
`feat!`	Breaking change	Major (X.0.0)

Examples:

git commit -m "feat(bicep): add Cosmos DB module with private endpoint"
git commit -m "fix(deploy): resolve VPN Gateway race condition"
git commit -m "docs(site): add terraform modules reference page"

Validation Before Committing

# Full validation suite
npm run validate:all

# Individual checks
npm run lint:md                      # Markdown linting
npm run lint:json                    # JSON/JSONC validation

# Bicep (if changed)
bicep build infra/bicep/smb-ready-foundation/main.bicep
bicep lint infra/bicep/smb-ready-foundation/main.bicep

# Terraform (if changed)
cd infra/terraform/smb-ready-foundation
terraform fmt -check -recursive
terraform init -backend=false && terraform validate

Pre-push hooks run automatically via Lefthook — they validate only the file types you changed.

Pull Request Process

Create a feature branch from main
Make changes with conventional commits
Run validation (npm run validate:all)
Push to your fork and open a PR against main
Fill out the PR template completely
Wait for review — maintainers respond within 48 hours

PR Checklist

Branch is up-to-date with main
Commits follow Conventional Commits format
npm run lint:md passes
bicep build succeeds (if Bicep changes)
terraform validate succeeds (if Terraform changes)
Documentation updated (if applicable)
CHANGELOG.md updated (for features/fixes)

Key Directories

Directory	Purpose
`infra/bicep/smb-ready-foundation/`	Bicep templates
`infra/terraform/smb-ready-foundation/`	Terraform configurations
`site/src/content/docs/`	Documentation (this site)
`.github/agents/`	Copilot agent definitions
`.github/skills/`	Reusable skill knowledge
`.github/instructions/`	AI coding standards
`agent-output/smb-ready-foundation/`	Generated artifacts

License

By contributing, you agree that your contributions will be licensed under the MIT License.