-
Notifications
You must be signed in to change notification settings - Fork 0
Contributing
Thank you for considering contributing to MuxCore. This guide covers development setup, contract contribution guidelines, and the PR process.
- Go 1.24+ (project targets Go 1.26)
- protoc + protoc-gen-go + protoc-gen-go-grpc (for proto changes)
- git + GitHub account
git clone https://github.com/Muxcore-Media/core.git
cd core
go build ./...scripts/run_tests.shgolangci-lint runConfiguration is in .golangci.yml.
# Development mode (no TLS)
MUXCORE_INSECURE_DISABLE_TLS=true go run ./cmd/muxcored --tag default
# Bare loom (no modules)
MUXCORE_INSECURE_DISABLE_TLS=true go run ./cmd/muxcoredprotoc --go_out=. --go_opt=module=github.com/Muxcore-Media/core \
--go-grpc_out=. --go-grpc_opt=module=github.com/Muxcore-Media/core \
-I proto proto/muxcore/**/v1/*.protoIf adding a new media type requires changing the core platform, the architecture is wrong.
Core knows nothing about movies, TV, music, or books. All domain logic lives in modules.
-
Core contracts — interfaces in
pkg/contracts/that define fabric infrastructure (event bus, registry, storage, mesh, security). These are reviewed for minimalism and fabric-agnosticism. -
Domain contracts — interfaces specific to a media domain (downloader, transcoder, metadata). These go in separate
github.com/Muxcore-Media/contracts-*repos. Core never imports them.
Before adding a new contract to pkg/contracts/:
- Is it truly fabric infrastructure, not domain-specific?
- Is it discoverable via
Registry.FindByCapability()? - Is the interface minimal (only methods modules actually need)?
- Are security considerations documented on the interface type?
- Is the contract documented in the wiki Contracts page and this skill?
Modules are standalone binaries, not compile-time imports. See Writing Modules for the sidecar pattern. Reference implementation: downloader-qbittorrent.
- Branch from
master - Use descriptive branch names:
feat/description,fix/description,docs/description - Keep branches focused — one concern per PR
-
go build ./...passes -
scripts/run_tests.shpasses -
golangci-lint runpasses - New code has tests
- New contracts are documented in the wiki
- Commit messages are descriptive
area: short description (max 72 chars)
Longer explanation if needed. What changed and why.
Examples:
contracts: add EncryptionProvider interfacegrpcmesh: fix heartbeat TLS guard for nil credsdocs: update roadmap to separate contracts from implementations
All PRs require review. CI must pass (build + test + lint). Doc-only PRs still require CI green.
Squash-merge to master. Branch protection requires PRs, blocks force push, blocks branch deletion.
The wiki at github.com/Muxcore-Media/core.wiki is the primary user-facing documentation. When adding or changing a feature:
- Update the relevant wiki page
- If it's a new contract, add it to the Contracts page
- If it's a new config option, add it to the Configuration Reference
- Update the Roadmap if applicable
Wiki changes are pushed directly to the wiki repo's master branch.
- All exported types, functions, and interfaces must have GoDoc comments
- Security-sensitive interfaces must document what callers and implementers must not log
- Credential-bearing types must implement
slog.LogValuerfor safe logging
Portions of this codebase may be written with AI assistance. Every change — human, AI, or hybrid — goes through the same rigorous pipeline: mandatory code review, automated testing, Dependabot security scanning, and a capability-based security model that limits blast radius regardless of code origin.
- Vulnerability reporting: See SECURITY.md
- Secure coding: Follow OWASP Go-SCP guidelines
-
Never log credentials — use
slog.LogValueron config types with URLs - Constant-time comparison for security-sensitive string checks (join tokens, API keys)
- TLS is required for production — gRPC refuses to start without it unless explicitly disabled
GPL-3.0. See LICENSE.