Welcome and thank you for taking the time to contribute!
This guide explains the workflow, coding standards, and policies that keep the project healthy and collaborative.
Plexaubnet is a Kubernetes-native IP Address Management (IPAM) controller set written in Go.
The project follows the Apache License 2.0 and embraces open, friendly collaboration.
| Tool | Minimum Version | Purpose |
|---|---|---|
| Go | 1.24 | Build & test |
| make | latest | Task automation |
| Docker | 24.x | Local container runtime |
| kind | 0.22 | Local Kubernetes cluster |
| Helm | 3.14 (optional) | Chart testing |
# Clone
git clone https://github.com/appthrust/plexaubnet.git
cd plexaubnet
# Install dependencies & pre-commit hooks
make deps
# Start local Kubernetes cluster
make kind-up # kind create cluster + local registry
make install # install CRDs into the clustermain– always releasable; protected branchfeature/<short-desc>– active developmentrelease/vX.Y.Z– release preparationhotfix/<issue>– emergency patch
Create a feature branch, commit your changes, then open a Pull Request (PR).
- Run
go fmt ./...,go vet ./..., andgolangci-lint runbefore pushing. - Keep package names lowercase and short (
allocator,netutil). - Follow existing file layout (
internal/controller,docs/design). - Add unit tests for new functionality.
- Update docs/ when behavior or API changes.
Prefix commits with a type:
| Type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
test |
Adding or updating tests |
chore |
Build/CI, refactors, misc |
Example:
feat(controller): add subnet allocator
- Overview – why this change is needed
- Changes – bullet list of key modifications
- Tests – how to verify
- Impact – migration or compatibility notes
- Checklist – [ ] code formatted, [ ] tests pass, [ ] docs updated
| Command | Purpose |
|---|---|
make test |
Run unit tests |
make e2e |
Envtest + kind integration tests |
make lint |
Execute golangci-lint |
make coverage |
Generate coverage report |
All checks run automatically in GitHub Actions on every PR.
Design documents live under docs/design/.
If your change adds a new controller, CRD, or significant behavior, include/update a design doc.
When opening an issue, please include:
- Steps to reproduce
- Expected behavior
- Actual behavior / logs
- Environment (Go version, Kubernetes version)
Use GitHub Discussions for questions and proposals.
The project is licensed under Apache-2.0.
When adding dependencies, ensure they are Apache-2.0, MIT, BSD, or similarly permissive.
Run:
go-licenses csv ./... | grep -v "UNKNOWN"and attach the report in your PR if new licenses appear.
All commits must be signed:
git commit -s -m "feat: awesome contribution"which appends:
Signed-off-by: Your Name <email@example.com>
- Submit at least 3 high-quality PRs reviewed & merged.
- Actively participate in reviews and discussions.
- Request maintainer status via a Discussion thread; existing maintainers vote.
flowchart TD
A[Fork repository] --> B[Clone locally]
B --> C[Create feature/* branch]
C --> D[Code & Commit<br/>(Signed-off-by)]
D --> E[Run Lint & Tests]
E --> F[Open Pull Request]
F --> G[CI Checks]
G --> H[Code Review]
H --> I[Merge to main]
Happy hacking! We look forward to your contributions.
If anything is unclear, open an issue or start a discussion.