feat(tooling): pre-commit + commitizen + golangci-lint (OM branch rules)

.cz.toml

@@ -0,0 +1,26 @@
+[tool.commitizen]
+name = "cz_customize"
+version = "0.1.0"
+tag_format = "v$version"
+
+[tool.commitizen.customize]
+message_template = "<type>(<scope>): <subject>"
+example = "feat(api): add app grouping endpoints"
+schema = "<type>(<scope>): <subject>"
+schema_pattern = "^(feat|feature|fix|add|chore|docs|refac|wip|hotfix|security)(\\([\\w\\-.]+\\))?!?: .+"
+
+[tool.commitizen.customize.questions]
+type = { type = "list", message = "Select the type of change:", choices = [
+  { value = "feat", name = "feat: a new feature" },
+  { value = "feature", name = "feature: a new feature (long form)" },
+  { value = "fix", name = "fix: a bug fix" },
+  { value = "add", name = "add: add files or capabilities" },
+  { value = "chore", name = "chore: tooling or maintenance" },
+  { value = "docs", name = "docs: documentation changes" },
+  { value = "refac", name = "refac: refactor code" },
+  { value = "wip", name = "wip: work in progress" },
+  { value = "hotfix", name = "hotfix: urgent fix" },
+  { value = "security", name = "security: security-related change" },
+]}
+scope = { type = "input", message = "Scope (optional):", required = false }
+subject = { type = "input", message = "Short description:", required = true }

.golangci.yml

@@ -0,0 +1,19 @@
+run:
+  timeout: 3m
+  issues-exit-code: 1
+  tests: true
+
+linters:
+  enable:
+    - govet
+    - staticcheck
+    - gosimple
+    - ineffassign
+    - errcheck
+    - gofmt
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0
+

.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+default_install_hook_types: [commit-msg, pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      # Git style
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-vcs-permalinks
+      - id: forbid-new-submodules
+      - id: no-commit-to-branch
+        args:
+          - '--pattern'
+          - '^((?!(feat|feature|fix|add|chore|docs|refac|wip|hotfix|security)/[0-9]{1,5}-[A-Za-z0-9._\-]+).)*$'
+
+      # Common errors
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-yaml
+      - id: check-executables-have-shebangs
+
+      # Cross platform
+      - id: check-case-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/Yelp/detect-secrets.git
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+        name: Detect secrets
+        always_run: true
+        description: Detects high entropy strings that are likely to be passwords.
+        entry: detect-secrets-hook
+        files: .*(\.(json|yml|yaml|tf|toml|ini))$
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v2.42.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  # Go formatting and vet (local hooks)
+  - repo: local
+    hooks:
+      - id: go-fmt
+        name: go fmt
+        entry: bash -lc 'go fmt ./...'
+        language: system
+        pass_filenames: false
+      - id: go-vet
+        name: go vet
+        entry: bash -lc 'go vet ./...'
+        language: system
+        pass_filenames: false
+
+  # GolangCI-Lint (static analysis)
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v1.59.1
+    hooks:
+      - id: golangci-lint
+        args: ["-c", ".golangci.yml"]

CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to Replicator
+
+Thanks for your interest in contributing! This guide covers local setup, branch and commit conventions, development workflow, and where to start as a new contributor.
+
+## Local Development
+
+- Prerequisites
+  - Go 1.23+ (see `go.mod`)
+  - GitHub CLI (`gh`) for issues/PRs
+  - Pre-commit, Commitizen, GolangCI-Lint
+
+- macOS
+  - Install tools:
+    ```bash
+    brew install go gh pre-commit golangci-lint
+    pipx install commitizen || pip install commitizen
+    ```
+
+- Ubuntu/Debian
+  - Install tools:
+    ```bash
+    sudo apt update && sudo apt install -y golang-go python3-pip
+    pipx install pre-commit commitizen || pip install pre-commit commitizen
+    curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b ~/.local/bin v1.59.1
+    export PATH="$HOME/.local/bin:$PATH"
+    ```
+
+- Setup hooks
+  ```bash
+  pre-commit install --hook-type pre-commit --hook-type commit-msg
+  ```
+
+- Run the server
+  ```bash
+  cp -n config.toml config.local.toml 2>/dev/null || true
+  go run ./cmd/replicator --config config.toml
+  ```
+
+- Run tests
+  ```bash
+  go test ./...
+  ```
+
+## Branch Naming
+
+- Pattern: `<type>/<issue>-<short-desc>` (we use GitHub issue numbers for project tracking)
+  - `<type>` one of: `feat, feature, fix, add, chore, docs, refac, wip, hotfix, security`
+  - `<issue>` numeric GitHub issue ID (e.g., `29`)
+  - Examples:
+    - `feat/29-precommit-setup`
+    - `fix/102-buggy-disk-check`
+
+Our pre-commit `no-commit-to-branch` hook blocks commits on non-conforming branches.
+
+## Commit Messages
+
+- We use Commitizen with a customized Conventional Commits subset.
+- Format: `<type>(<scope>): <subject>`
+  - `<type>` must be one of: `feat, feature, fix, add, chore, docs, refac, wip, hotfix, security`
+  - Examples:
+    - `feat(api): add app grouping endpoints`
+    - `fix(storage): handle sqlite busy timeout`
+
+- Recommended:
+  ```bash
+  cz commit
+  ```
+  or commit normally and the `commit-msg` hook will validate.
+
+## Development Workflow
+
+- Create or pick up an issue. For new features, propose design via an issue first.
+- Create a branch following the naming convention.
+- Keep PRs small and focused. Reference issues with `Closes #<issue>` in the PR description.
+- Ensure `go fmt`, lint, and tests pass locally before opening the PR.
+
+## Good First Issues
+
+- Look for issues labeled `good first issue` or `help wanted`:
+  - https://github.com/OpenMigrate/replicator/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+  - https://github.com/OpenMigrate/replicator/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
+- Unsure where to start? Comment on an issue and we’ll guide you.
+
+## Code Style & Linting
+
+- `go fmt ./...` and `go vet ./...` run via pre-commit.
+- `golangci-lint` runs as part of pre-commit; CI integration may run it on PRs as well.
+
+## Security & Secrets
+
+- `detect-secrets` scans for potential credentials.
+- Never commit secrets. Use environment variables or secure stores.
+
+Happy hacking!

README.md

@@ -1,2 +1,20 @@
 # replicator
 Controller component of the OpenMigrate platform — receives replicated disk data from agents, processes block-level changes, applies compression, and securely uploads to target cloud storage (e.g., S3). Enables scalable, centralized orchestration of migrations across environments.
+
+### Pre-commit, Commitizen, and Linting
+
+- Install pre-commit hooks:
+  - pipx: `pipx install pre-commit` (or `pip install pre-commit`)
+  - Install hooks: `pre-commit install --hook-type pre-commit --hook-type commit-msg`
+- Branch naming enforced via pre-commit: `<type>/<issue>-<short-desc>`
+  - `<issue>` is the GitHub issue number (e.g., `29`).
+  - Allowed types: `feat, feature, fix, add, chore, docs, refac, wip, hotfix, security`
+- Commit messages validated by Commitizen (Conventional Commits) on `commit-msg`.
+- Go formatting and vet run on commit; static analysis via `golangci-lint`.
+
+Configs:
+- `.pre-commit-config.yaml` — hooks configuration
+- `.golangci.yml` — linter configuration
+- `.cz.toml` — commitizen configuration
+
+See `CONTRIBUTING.md` for detailed contributor guidelines.