From 750e1fba2f571a19ecfc247ab2edf0a6fc5799eb Mon Sep 17 00:00:00 2001 From: sugan0tech Date: Mon, 18 Aug 2025 18:36:45 +0530 Subject: [PATCH 1/2] feat(tooling): add pre-commit, commitizen, golangci-lint; enforce OM branch naming\n\nCloses #29 --- .cz.toml | 5 ++++ .golangci.yml | 19 ++++++++++++ .pre-commit-config.yaml | 65 +++++++++++++++++++++++++++++++++++++++++ README.md | 15 ++++++++++ 4 files changed, 104 insertions(+) create mode 100644 .cz.toml create mode 100644 .golangci.yml create mode 100644 .pre-commit-config.yaml diff --git a/.cz.toml b/.cz.toml new file mode 100644 index 0000000..6c3b1ee --- /dev/null +++ b/.cz.toml @@ -0,0 +1,5 @@ +[tool.commitizen] +name = "cz_conventional_commits" +version = "0.1.0" +tag_format = "v$version" + 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..ef4aa92 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,65 @@ +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|bugfix|chore|docs|refactor|test|ci|build|perf|wip|break|revert|hotfix|security)/(OM|om)-[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/README.md b/README.md index 9655637..cadade3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,17 @@ # 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: `/(OM|om)-_` + - Allowed types: `feat, feature, fix, bugfix, chore, docs, refactor, test, ci, build, perf, wip, break, revert, 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 From c84d6021b76dc54af66f2de8ee8cef54167f542c Mon Sep 17 00:00:00 2001 From: sugan0tech Date: Mon, 18 Aug 2025 18:47:07 +0530 Subject: [PATCH 2/2] docs(contrib): contributor guide; tighten verbs and branch pattern\n\nRefs #29 --- .cz.toml | 23 +++++++++- .pre-commit-config.yaml | 3 +- CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++ README.md | 7 ++- 4 files changed, 122 insertions(+), 5 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.cz.toml b/.cz.toml index 6c3b1ee..f1eb04d 100644 --- a/.cz.toml +++ b/.cz.toml @@ -1,5 +1,26 @@ [tool.commitizen] -name = "cz_conventional_commits" +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/.pre-commit-config.yaml b/.pre-commit-config.yaml index ef4aa92..cc58618 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,7 +12,7 @@ repos: - id: no-commit-to-branch args: - '--pattern' - - '^((?!(feat|feature|fix|bugfix|chore|docs|refactor|test|ci|build|perf|wip|break|revert|hotfix|security)/(OM|om)-[0-9]{1,5}_[A-Za-z0-9._\-]+).)*$' + - '^((?!(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 @@ -62,4 +62,3 @@ repos: 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 cadade3..85ec692 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,9 @@ Controller component of the OpenMigrate platform — receives replicated disk da - 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: `/(OM|om)-_` - - Allowed types: `feat, feature, fix, bugfix, chore, docs, refactor, test, ci, build, perf, wip, break, revert, hotfix, security` +- 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`. @@ -15,3 +16,5 @@ Configs: - `.pre-commit-config.yaml` — hooks configuration - `.golangci.yml` — linter configuration - `.cz.toml` — commitizen configuration + +See `CONTRIBUTING.md` for detailed contributor guidelines.