Contribution Standard

Read philosophy before reading this document. This document assumes you have internalized the principle. It does not re-explain it — it applies it.

The Single Question

Every contribution — code, documentation, design, suggestion — must answer this before anything else:

Does this read reality, or does it represent reality?

If it reads reality: continue. If it represents reality: find the approach that reads it directly before continuing.

This question is not a checklist item. It is the filter through which every decision passes.

Before You Contribute

Understand what you are contributing to

suctl is not a collection of features. It is a principle made executable. A contribution that adds a useful feature while violating the principle is not a contribution — it is damage that will need to be undone.

Read the codebase with this question in mind: where does each component read reality directly? When you can answer that for every major component, you are ready to contribute.

Understand the domain you are touching

If you are contributing a new capability for a domain you have not operated in production, find someone who has. The principle is domain-agnostic. Its application is not. Knowing that “nginx config tree is truth” requires knowing nginx config well enough to know what the tree actually contains and when it changes.

Capability Contributions

A capability is what suctl exposes. It is atomic (one operation) or compound (composed of operations). It serves one purpose, reads live state, and is independently correct and independently testable. This checklist applies to every capability; compound-specific items follow in the next section.

Checklist before submitting a capability

Single purpose — does this capability serve exactly one purpose?
Live state — does it read from the authoritative source directly? No intermediary storage, no cache, no file representing state that exists elsewhere.
Source identified — what is the source of truth for this capability? Name it explicitly. (nginx config tree, systemd unit state, running process, live socket connection…)
Independently testable — can this capability be tested without any other capability running first?
Honest failure — if the source of truth is unavailable, does the capability fail honestly rather than returning stale or assumed state?
Platform consistent — if this capability will run on multiple platforms, does it apply the same principle on each? No platform gets a caching exemption.

What a capability is not

A capability is not a shortcut. If it stores state “for convenience,” it is not a capability — it is a cache with extra steps.
A capability is not platform-specific logic wrapped in a platform check. If the Linux and Windows implementations are fundamentally different in principle (not just in syscalls), something is wrong with the design.

Composition is not a violation. A capability calling another operation — or another capability — is normal, exactly like a function calling a function. Expose an internal operation as a capability only when another module needs it.

Compound Capability Contributions

A compound capability composes operations to serve one purpose. Its steps may run in sequence or in parallel, branch on what each step reads, and self-correct from live state — governed by the operations’ real inputs and outputs, not a fixed script. It has a defined intent, a known start state, and a known end state.

Checklist before submitting a compound capability

Composed of correct operations — is every step an operation that already exists and is already correct on its own?
Each step reads reality fresh — no step relies on hidden state left by an earlier one; any data passed between steps is explicit, declared input/output.
Defined intent — can you state its purpose in one sentence, including the start state and the end state?
No misplaced logic — does any step do work that belongs inside an operation? If yes, put it there first.
Honest about partial failure — if a step fails partway, what is the system state? Is that state observable? Is it honest?

New Domain Contributions

A domain is a system that suctl manages — Odoo, nginx, Docker, Windows Services, fail2ban, and so on. Adding a new domain means adding capabilities for that domain.

Checklist before submitting a new domain

Principle holds — does every capability in this domain read live state directly from the authoritative source?
Source of truth identified — for each capability, what is the authoritative source? Config file, running process, system API, live socket?
No platform exemptions — if this domain runs on multiple platforms, does the same principle apply on each?
Capability model intact — are the domain’s operations expressed as atomic and compound capabilities, or as monolithic operations that should be decomposed?

What Will Be Rejected

These are not judgment calls. These are automatic rejections.

Any storage of state that can be read directly from its source. If nginx config is the truth, a database table of nginx domains is rejected. No exceptions for performance, convenience, or query simplicity.

Any caching of system state. “We cache it and invalidate when we make changes” is rejected. Changes made outside suctl invalidate the cache without suctl knowing. The cache lies. Read directly.

Any logic placed at the wrong level. Work that belongs inside an operation must live in that operation — not be duplicated in a compound capability that composes it. Put it where it belongs, then compose. (Composition itself — one capability calling another — is never rejected; that is how compounds are built.)

Any workaround for “reality cannot be read directly here.” This case deserves a design conversation, not a workaround. Open an issue. Explain why direct reading is not possible. The answer may be that the capability cannot be built correctly yet — and that is an honest answer.

Documentation Contributions

Documentation that contradicts philosophy is rejected regardless of technical accuracy. Documentation that explains a decision without capturing why the alternative was rejected is incomplete. Documentation that makes suctl seem like a general-purpose tool without explaining the principle it operates on is misleading.

When documenting a decision, always record:

What was decided
What the alternative was
Why the alternative was rejected
Which aspect of the principle this expresses

The Standard

The standard for contributions is not “does this work?” The standard is “does this read reality, or does it represent reality?”

A contribution that works but lies is worse than no contribution. It creates the appearance of correctness while introducing drift from reality — exactly the failure mode suctl exists to prevent.

If you are unsure whether your contribution meets the standard, ask before submitting. The question “does this read reality directly?” has a clear answer for every concrete case. Find the answer before the code is written, not after.