Thank you for your interest in contributing to reliable-job-engine. We are building a mission-critical, fault-tolerant background processing engine with strict distributed systems guarantees.
To maintain code quality, deterministic concurrency, and production reliability, all contributions must adhere to the standards outlined in this guide.
All contributors and maintainers are expected to follow our Code of Conduct. Please report any unacceptable behavior according to the instructions in that document.
- Fork the Repository:
Fork
https://github.com/MRINALPRAKASHFSD/Job_Queue-to your personal GitHub account. - Clone Locally:
git clone https://github.com/<your-username>/Job_Queue-.git cd Job_Queue-
- Configure Upstream Remote:
git remote add upstream https://github.com/MRINALPRAKASHFSD/Job_Queue-.git git fetch upstream
- Create a Dedicated Feature Branch:
Never develop directly on
main. Keep your localmainsynchronized withupstream/main.
Branch names should be descriptive, lowercase, hyphen-separated, and prefixed with the category of change:
feat/<short-description>: New functionality or architectural capability.fix/<short-description>: Bug fix or concurrency edge-case resolution.perf/<short-description>: Performance optimization or query tuning.refactor/<short-description>: Code restructuring without behavioral change.test/<short-description>: New test cases or test harness enhancements.docs/<short-description>: Documentation additions or corrections.chore/<short-description>: Build tooling, dependencies, or repository maintenance.security/<short-description>: Security-related hardening or dependency updates.
Examples:
feat/atomic-job-claimingfix/stale-lease-acknowledgementtest/exponential-backoff-jitterdocs/fencing-tokens-architecture
This repository strictly enforces Conventional Commits (v1.0.0). Commit messages must follow this structure:
<type>(<scope>): <short imperative summary>
[optional body explaining motivation, distributed systems trade-offs, and invariants]
[optional footer(s), e.g. Fixes #123]
feat: A new feature for users or workers.fix: A bug fix or race condition remediation.docs: Documentation-only changes.test: Adding missing tests or correcting existing tests.refactor: A code change that neither fixes a bug nor adds a feature.perf: A code change that improves performance or reduces database lock contention.chore: Changes to build scripts, auxiliary tools, or non-source code.ci: Changes to CI/CD workflows and automation scripts.security: Security patches, vulnerability mitigations, or permission hardening.
queue: Core job enqueuing, priority scheduling, and table locks.worker: Worker pool, leasing, execution loop, and heartbeating.retry: Backoff calculations, jitter algorithms, and attempt counters.dlq: Dead-letter queue isolation, failure logging, and manual replay.idempotency: Deduplication keys, transaction wrappers, and state fences.inspector: CLI and HTTP inspection endpoints.db: PostgreSQL migrations, connection pool, and query definitions.config: Environment and configuration loading.
feat(queue): implement atomic job claimingfix(worker): prevent stale lease acknowledgementtest(retry): cover exponential backoffdocs(architecture): document crash recoveryperf(queue): add partial index on state and scheduled_at
Before opening a Pull Request:
- Link Related Issues: Every non-trivial PR must reference an existing GitHub issue (e.g.,
Closes #42orAddresses #15). - Atomic Changes: Keep PRs focused on a single logical change. Large multi-faceted changes should be broken into sequential, reviewable PRs.
- Fill the PR Template: Complete all sections of the Pull Request Template.
- Mandatory Tests:
- Every bug fix must include a regression test proving the failure and verifying the resolution.
- Every new feature must include both unit tests and integration tests against real PostgreSQL.
- No Secrets or Extraneous Files: Ensure
.env, IDE files, build binaries, or debug logs are never included.
All Go source code must be formatted using standard tooling:
make fmt
# or manually:
gofmt -s -w .Code must pass standard Go static analysis without warnings:
make lint
# runs: go vet ./...If golangci-lint is installed locally, run:
golangci-lint run ./...We require rigorous testing, particularly for concurrency and lease mechanics:
- Unit Tests:
make test-unit
- Race Condition Detection:
All tests must run with the Go race detector enabled:
go test -race ./... - PostgreSQL Integration Tests:
Mock databases cannot accurately simulate row-level locking (
FOR UPDATE SKIP LOCKED), transactional deadlocks, or lease boundaries. All queue claiming and worker leasing tests must run against an active PostgreSQL instance:make test-integration
- Public functions, types, and interfaces in Go packages must include meaningful doc comments adhering to Go standard conventions.
- If a change alters system guarantees, failure handling, or schema definitions, the corresponding documentation in
README.md,ARCHITECTURE.md, orFAILURE_MODES.mdmust be updated within the same pull request.
- Never hardcode credentials, connection strings, or encryption keys.
- Always use parameterized SQL queries (
$1, $2, ...) without exception. - If you discover a security vulnerability, do NOT open a public PR or issue. Follow the instructions in SECURITY.md.
- Automated CI Validation:
Once opened, your PR will trigger GitHub Actions workflows:
- Linting & Vet checks
- Unit tests with
-race - Real PostgreSQL integration tests
- CodeQL security analysis
- Dependency vulnerability review
- Architectural Review: A repository maintainer will review the code for distributed systems correctness, locking behavior, edge-case safety, and code style.
- Revisions: Address review feedback by pushing new commits to your branch. Do not force-push over active reviews unless requested.
- Merging: Once approved and all CI checks pass, the PR will be merged using "Squash and merge" or "Rebase and merge" to maintain a clean linear commit history.