From ec64ad29030641b76c8a4f2da52f6158112666dc Mon Sep 17 00:00:00 2001 From: danie1-parker Date: Wed, 19 Nov 2025 09:03:10 +0300 Subject: [PATCH] dv-3543 --- CONTRIBUTING.md | 452 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 452 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..502f25b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,452 @@ +
+ +## ๐Ÿค Contributing to DV Processing + +*Guidelines for contributing to the project* + +
+ +--- + +## ๐Ÿ“‹ Table of Contents + +- [๐Ÿš€ Getting Started](#-getting-started) โ€” Setup development environment +- [๐Ÿ”„ Development Workflow](#-development-workflow) โ€” Branch strategy and workflow +- [๐Ÿ“ Coding Standards](#-coding-standards) โ€” Code style and conventions +- [๐Ÿงช Testing](#-testing) โ€” Testing requirements and guidelines +- [๐Ÿ’ฌ Commit Messages](#-commit-messages) โ€” Commit message format +- [๐Ÿ”€ Pull Request Process](#-pull-request-process) โ€” PR submission and review +- [๐Ÿ› Issue Reporting](#-issue-reporting) โ€” How to report bugs +- [๐Ÿ”’ Security](#-security) โ€” Security vulnerability reporting +- [๐Ÿ‘€ Code Review](#-code-review) โ€” Review process and criteria +- [๐Ÿท๏ธ Release Process](#-release-process) โ€” Versioning and releases + +--- + +## ๐Ÿš€ Getting Started + +### Prerequisites + +- **Go 1.24.2+** โ€” [Download](https://go.dev/dl/) +- **PostgreSQL** โ€” Database operations +- **Make** โ€” Build commands +- **Git** โ€” Version control + +### Setup + +```bash +# 1. Fork and clone +git clone https://github.com/YOUR_USERNAME/dv-processing.git +cd dv-processing + +# 2. Add upstream remote +git remote add upstream https://github.com/dv-net/dv-processing.git + +# 3. Install development tools +make install-dev-tools + +# 4. Build and verify +make build +make fmt +make lint +``` + +> ๐Ÿ’ก **Tip**: Run `go mod download` if dependencies are missing + +--- + +## ๐Ÿ”„ Development Workflow + +### Branch Strategy + +- ๐ŸŒฟ **`main`** โ€” Production-ready stable code +- ๐Ÿ”ง **`dev`** โ€” Active development branch +- ๐ŸŒฑ **`feature/*`** โ€” New features (target: `dev` or `main`) +- ๐Ÿ› **`fix/*`** โ€” Bug fixes (target: `dev`) + +### Workflow + +```bash +# 1. Update main branch +git checkout main +git pull upstream main + +# 2. Create feature branch +git checkout -b feature/your-feature-name + +# 3. Make changes, then verify +make fmt +make lint +``` + +> โš ๏ธ **Important**: Always create PRs from feature branches, never from `main` or `dev` + +--- + +## ๐Ÿ“ Coding Standards + +### Style Guide + +Follow [Effective Go](https://go.dev/doc/effective_go) and project conventions: + +- **Formatting** โ€” `gofumpt` (via `make fmt`) +- **Imports** โ€” `goimports` for organization +- **Naming** โ€” Go naming conventions +- **Errors** โ€” Explicit handling required +- **Documentation** โ€” Document all exported functions/types + +### Linting + +```bash +# Run linter +make lint +``` + +The project uses `golangci-lint` with strict rules. All linter errors must be resolved before submitting PRs. + +### Architecture + +``` +cmd/ CLI entrypoints +internal/ Internal packages (not for external use) + โ”œโ”€โ”€ handler/ HTTP/gRPC handlers + โ”œโ”€โ”€ services/ Business logic + โ”œโ”€โ”€ store/ Repositories and data access + โ”œโ”€โ”€ config/ Configuration management + โ”œโ”€โ”€ fsm/ Finite state machines for blockchains + โ””โ”€โ”€ ... +pkg/ Shared libraries (for external use) +api/ Generated API code +schema/ Protocol buffer definitions +sql/ Database migrations and queries +``` + +### Key Rules + +- ๐Ÿšซ **Transactions** โ€” Use proper transaction management via store layer +- โœ… **Structs** โ€” Initialize all struct fields in constructors +- โœ… **Naming** โ€” Use `snake_case` for JSON/YAML fields +- โœ… **Size** โ€” Functions < 180 lines (handlers configurable) +- โœ… **Complexity** โ€” Cyclomatic complexity < 60 +- โœ… **Generated Code** โ€” Never edit generated files directly (`.pb.go`, `.sql.go`, `.connect.go`) + +--- + +## ๐Ÿงช Testing + +### Requirements + +- โœ… **New Features** โ€” Must include tests +- โœ… **Bug Fixes** โ€” Must include regression tests +- โœ… **Framework** โ€” Use `testify` for assertions +- โœ… **Naming** โ€” Test files: `*_test.go` in same package + +### Running Tests + +```bash +# Run all tests +go test ./... + +# Run specific package +go test ./internal/service/package + +# Run with coverage +go test -cover ./... + +# Run with verbose output +go test -v ./... +``` + +### Coverage + +> ๐ŸŽฏ **Target**: **80%+** coverage for new code +> +> Focus on testing business logic and edge cases + +--- + +## ๐Ÿ’ฌ Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + + + +