diff --git a/.cz.toml b/.cz.toml new file mode 100644 index 0000000..f1eb04d --- /dev/null +++ b/.cz.toml @@ -0,0 +1,26 @@ +[tool.commitizen] +name = "cz_customize" +version = "0.1.0" +tag_format = "v$version" + +[tool.commitizen.customize] +message_template = "(): " +example = "feat(api): add app grouping endpoints" +schema = "(): " +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 } diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..439d2ad --- /dev/null +++ b/.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 + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..cc58618 --- /dev/null +++ b/.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"] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f9eeecf --- /dev/null +++ b/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: `/-` (we use GitHub issue numbers for project tracking) + - `` one of: `feat, feature, fix, add, chore, docs, refac, wip, hotfix, security` + - `` 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: `(): ` + - `` 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 #` 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! diff --git a/README.md b/README.md index 9655637..85ec692 100644 --- a/README.md +++ b/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: `/-` + - `` 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.