Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (81 loc) · 2.52 KB

CONTRIBUTING.md

File metadata and controls

115 lines (81 loc) · 2.52 KB

Contributing to Groxy

Thanks for considering a contribution to Groxy.

Groxy is currently pre-v1. The API is intentionally still open to feedback, so issues and pull requests about API design, naming, docs, examples, and developer experience are very welcome.

Before you start

For larger changes, please open an issue first so we can discuss the design before you spend time implementing it.

Good contribution areas include:

  • docs and examples
  • tests and benchmarks
  • middleware helpers
  • proxy correctness fixes
  • observability and logging
  • HTTPS inspection safety improvements

Please do not report security vulnerabilities in public issues. See SECURITY.md instead.

Project layout

.
├── *.go                 # public groxy package
├── cmd/groxy            # small demo proxy binary
├── docs                 # guides and security/operational notes
├── examples             # runnable examples
├── .github              # CI, issue templates, PR template
├── README.md            # landing page / quickstart
├── CHANGELOG.md         # release history
├── ROADMAP.md           # planned work
└── RELEASE.md           # maintainer release checklist

The root Go files intentionally belong to one public package: github.com/SalzDevs/groxy. Avoid splitting code into subpackages unless there is a clear API or maintenance reason.

Development setup

Requirements:

  • Go 1.24 or newer
  • Git

Clone the repository:

git clone https://github.com/SalzDevs/groxy.git
cd groxy

Run the test suite:

go test ./...

Run vet:

go vet ./...

Run race tests before larger changes:

go test -race ./...

Run benchmarks when changing hot paths:

go test -run '^$' -bench=. -benchmem ./...

Format Go code before opening a PR:

gofmt -w .

Pull request guidelines

A good PR should:

  • explain the problem and solution clearly
  • include tests for behavior changes
  • update README/examples/godoc when public API changes
  • keep public APIs beginner-friendly
  • avoid unrelated formatting or drive-by changes

For public API changes, please include a short usage example in the PR description.

Commit messages

Use concise, conventional-style commit messages when possible:

feat: add access log middleware
fix: preserve proxy headers correctly
docs: clarify HTTPS inspection setup
test: cover blocked HTTPS requests

Release process

Maintainers use RELEASE.md before tagging releases.