Contributing

Contributing

Thanks for your interest in Kernel Borderlands. This page covers the practical mechanics of contributing; see Team for who owns what, and Getting Started to get a dev environment running first.

Before You Start

1. Read Getting Started and confirm your environment meets the minimums.
2. Read Architecture to understand where your change fits in the four-layer model.
3. Check Team for the relevant subsystem's Primary Maintainer — cross-subsystem changes should loop in both maintainers.
4. If touching the eBPF ↔ Go boundary, read Wire Protocol and Event Contract first — these are locked contracts; changes need coordination across kb-core and kb-control-plane, and a version bump (KB_WIRE_VERSION).

Recommended Reading Order

1. docs/README.md
2. Getting Started (installation + requirements)
3. Architecture
4. Kernel Hook Points
5. Team
6. docs/project/KB.pdf (full whitepaper)
7. docs/project/KB_Synopsis-1.pdf (condensed overview)

Filing Issues

Use the repository's issue templates:

• Bug report — steps to reproduce, expected vs. actual behavior, environment details (OS/kernel version matters a lot here — see Cross Kernel Portability).
• Feature request — the problem being solved, the proposed solution, and alternatives considered.

Pull Requests — Subsystem-Specific Checks

Subsystem	Test command	Notes
kb-core	./scripts/test.sh	eBPF changes must stay CO-RE compatible — see Cross Kernel Portability guidelines
kb-control-plane	go test ./...	Wire protocol changes need a corresponding wire_test.go update pinning the new byte layout
kb-aads	pytest tests/	Activate the venv first
kb-dashboard	(project's lint/test scripts)
kb-tui	go test ./...
kb-checker	cargo test	New integrity checks should ship with a matching threat model scenario

Wire/Contract Changes

If you change ProcessStateMsg, ZoneTransitionMsg, or any Event Contract value:

1. Bump KB_WIRE_VERSION on both the C side (kb_bridge.c) and Go side (wire.go).
2. Update the struct layout comment with the verified sizeof() byte count — never hand-count.
3. Update wire_test.go's frame-builder helpers and add a round-trip test for any new field.
4. Cross-post the change to both kb-core and kb-control-plane maintainers (see Team) — this is exactly the kind of change that has drifted silently before (see the history note in Wire Protocol).

Code of Conduct

This project follows the Contributor Covenant v2.0 — see CODE_OF_CONDUCT.md in the repository root. Report concerns to teamkbdevelopers@gmail.com.

License

Kernel Borderlands is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see LICENSE in the repository root. Notably, AGPLv3's network-use clause requires that modified versions running on a publicly accessible server make their source available to users of that server.

See also: Team, Architecture, .github/ISSUE_TEMPLATE/.

# Contributing

Thanks for your interest in Kernel Borderlands. This page covers the practical mechanics of contributing; see Team for who owns what, and Getting Started to get a dev environment running first.

Before You Start

1. Read Getting Started and confirm your environment meets the minimums.
2. Read Architecture to understand where your change fits in the four-layer model.
3. Check Team for the relevant subsystem's Primary Maintainer — cross-subsystem changes should loop in both maintainers.
4. If touching the eBPF ↔ Go boundary, read Wire Protocol and Event Contract first — these are locked contracts; changes need coordination across kb-core and kb-control-plane, and a version bump (KB_WIRE_VERSION).

Recommended Reading Order

1. docs/README.md
2. Getting Started (installation + requirements)
3. Architecture
4. Kernel Hook Points
5. Team
6. docs/project/KB.pdf (full whitepaper)
7. docs/project/KB_Synopsis-1.pdf (condensed overview)

Filing Issues

Use the repository's issue templates:

• Bug report — steps to reproduce, expected vs. actual behavior, environment details (OS/kernel version matters a lot here — see Cross Kernel Portability).
• Feature request — the problem being solved, the proposed solution, and alternatives considered.

Pull Requests — Subsystem-Specific Checks

Subsystem	Test command	Notes
kb-core	./scripts/test.sh	eBPF changes must stay CO-RE compatible — see Cross Kernel Portability guidelines
kb-control-plane	go test ./...	Wire protocol changes need a corresponding wire_test.go update pinning the new byte layout
kb-aads	pytest tests/	Activate the venv first
kb-dashboard	(project's lint/test scripts)
kb-tui	go test ./...
kb-checker	cargo test	New integrity checks should ship with a matching threat model scenario

Wire/Contract Changes

If you change ProcessStateMsg, ZoneTransitionMsg, or any Event Contract value:

1. Bump KB_WIRE_VERSION on both the C side (kb_bridge.c) and Go side (wire.go).
2. Update the struct layout comment with the verified sizeof() byte count — never hand-count.
3. Update wire_test.go's frame-builder helpers and add a round-trip test for any new field.
4. Cross-post the change to both kb-core and kb-control-plane maintainers (see Team) — this is exactly the kind of change that has drifted silently before (see the history note in Wire Protocol).

Code of Conduct

This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html) v2.0 — see CODE_OF_CONDUCT.md in the repository root. Report concerns to teamkbdevelopers@gmail.com.

License

Kernel Borderlands is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see LICENSE in the repository root. Notably, AGPLv3's network-use clause requires that modified versions running on a publicly accessible server make their source available to users of that server.

See also: Team, Architecture, .github/ISSUE_TEMPLATE/.