Contributing to xenvsync

Thank you for considering a contribution. This guide covers everything from local setup to PR expectations, code style, commit conventions, and security disclosure.

Note: Before writing code, review the Development Guide and Architecture docs to understand the codebase structure and design decisions.

Development Setup

Prerequisites: Go 1.25+, Git. Optionally install golangci-lint and govulncheck for richer local checks.

Initial setupbash

# 1. Fork and clone
$ git clone https://github.com/nasimstg/xenvsync.git
$ cd xenvsync

# 2. Download dependencies
$ go mod download

# 3. Run tests with race detection
$ go test -race ./...

# 4. (Recommended) Install quality tools
$ go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
$ go install golang.org/x/vuln/cmd/govulncheck@latest

Making Changes

Feature branch workflowbash

# Create a feature branch from main
$ git checkout -b feature/my-change

# Make changes, then run checks
$ go test -race ./...
$ go vet ./...

# Run local CI-equivalent before pushing
$ ./scripts/ci-check.sh

# Open a pull request against main

Important: All changes must be against the main branch. Keep commits focused and atomic — one logical change per commit.

Pull Request Checklist

1.Add or update tests for any new or changed behavior.

2.Ensure all tests pass with race detection enabled.

3.Run the local CI-equivalent checks script before pushing.

4.Keep docs aligned with user-visible changes (README, INSTALL, ARCHITECTURE).

5.Include migration notes for breaking changes.

6.Use focused, atomic commits with imperative mood messages.

7.Reference the relevant issue in your PR description.

Code Style

gofmt

All code must be formatted with gofmt. CI enforces this.

go vet

No vet warnings allowed. Run go vet ./... before pushing.

golangci-lint

Optionally install golangci-lint for broader static analysis.

govulncheck

Scan for known vulnerabilities with govulncheck ./...

Small functions

Keep functions focused and well-named. Avoid long multi-purpose functions.

Comments

Only add comments where the logic is not self-evident. Avoid redundant comments.

Commit Message Conventions

Use the imperative mood in the first line. Keep it under 72 characters. Reference issues when applicable.

Examplesbash

# Good — imperative mood, concise, references issue
Add --revoke flag to rotate command (#11)
Fix path traversal via --env flag
Update YAML export to quote YAML 1.1 booleans

# Bad — past tense or vague
Added rotation support
Fixed stuff
Update

Testing Requirements

xenvsync uses table-driven tests. New functionality must include tests covering normal paths, malformed input, and negative/error paths.

Command tests in cmd/*_test.go use temporary directories and invoke Cobra directly. Do not depend on global state.

Running the test suitebash

# Full suite with race detection (required before PR)
$ go test -race ./...

# With coverage report
$ go test -race -coverprofile=coverage.out ./...
$ go tool cover -html=coverage.out

# Run a specific package
$ go test -race ./internal/crypto/...
$ go test -race ./cmd/...

High-Risk Areas

These areas require extra care and thorough testing before any changes:

run command

Child process exit code propagation and signal forwarding (SIGINT/SIGTERM) must work correctly on Linux, macOS, and Windows.

rotate command

Vault is written before key to ensure rollback safety. Do not change this ordering.

Fallback merge precedence

.env.shared < .env.<name> < .env.local. Ensure layer order is preserved.

V1/V2 vault detection

decryptVault() auto-detects format. Changes must not break backward compatibility with V1 vaults.

Key permissions

Key files must be written with mode 0600. Identity files must also be 0600.

Memory zeroing

Key material must be zeroed after use via crypto.ZeroBytes.

Documentation Updates

When making user-visible behavior changes, update the following files alongside code:

–README.md — feature overview and command reference
–CONTRIBUTING.md — if contributing workflow changes
–docs/INSTALL.md — if installation steps change
–docs/ARCHITECTURE.md — if design boundaries shift
–CHANGELOG.md — add entry under the next version

Reporting Issues

Use GitHub Issues to report bugs or request features.

Include:

–Steps to reproduce the issue
–Expected vs. actual behavior
–Your OS and Go version (xenvsync version output)
–Relevant error output

Security Vulnerabilities

Warning: Do not open a public issue for security vulnerabilities. Report them privately via GitHub Security Advisories. This ensures responsible disclosure before a fix is released.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

PreviousChangelog