59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Workspace Conventions
|
|
|
|
## Working Conventions
|
|
|
|
- Confirm the target repository before editing; never treat this directory as
|
|
a monorepo.
|
|
- Inspect the relevant upstream application before designing or changing its
|
|
Ansible role.
|
|
- Keep standalone application roles independently usable. Cross-application
|
|
policy belongs in `ansible-role-dnd-pipeline` and is exposed to consumers as
|
|
`rakestraw.dnd.pipeline`.
|
|
- Prefer codebase-memory graph tools for code discovery. Use text/file search
|
|
for documentation, configuration, literals, or when the graph is
|
|
insufficient.
|
|
- Preserve unrelated and pre-existing working-tree changes in every
|
|
repository.
|
|
- Never place credentials or secret values in plans, examples, inventory, or
|
|
tests.
|
|
- Validate changes in the repository that owns them and report the commands
|
|
run.
|
|
- Do not duplicate an application contract in workspace documentation when a
|
|
link and a concise deployment consequence are sufficient.
|
|
|
|
## Ansible House Style (Normative)
|
|
|
|
- Always use the smallest clear sequence of declarative tasks that reaches the
|
|
required end state.
|
|
- Prefer `ansible.builtin` modules where they directly fit the task.
|
|
`community.general` is an approved, stable dependency and its modules may be
|
|
selected freely when appropriate; declare and pin the collection wherever a
|
|
role or collection depends on it.
|
|
- Do not strengthen the specification. Implement the requested invariants
|
|
without inventing additional guarantees for integrity, provenance, drift
|
|
recovery, corruption detection, rollback, or similar behavior.
|
|
- Prefer convergence over state inspection. Declare what should be true and
|
|
let the relevant module reconcile it.
|
|
- Trust Ansible's abstraction boundary. A module that manages state owns the
|
|
checks necessary to manage that state. Inspect it beforehand only when the
|
|
observed state is independently required.
|
|
- Complexity requires a requirement. Every additional task, conditional,
|
|
registered variable, or state probe must correspond to behavior the role is
|
|
required to provide.
|
|
- Persisted role-private state is a design smell. Fingerprints, checksum
|
|
databases, stamps, manifests, and similar bookkeeping require specific
|
|
justification.
|
|
- **Assume convergence first.** Before adding machinery for an edge case,
|
|
determine whether rerunning the ordinary desired-state operations already
|
|
repairs it.
|
|
- Consider whether a conditional task or a notified handler best expresses the
|
|
dependency. A `when` condition keeps triggers visible at the action site but
|
|
grows with their number. Notifications keep the action independent of the
|
|
number of notifiers, but distribute the control flow and defer execution
|
|
until the next handler flush. An explicit
|
|
`ansible.builtin.meta: flush_handlers` affects all pending handlers in the
|
|
play.
|
|
- Treat `rakestraw-ansible` as a style reference for direct tasks, shallow
|
|
control flow, and concise variable use, while retaining current practices
|
|
such as fully qualified collection names.
|