50 lines
2.5 KiB
Markdown
50 lines
2.5 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.
|
|
- Trust the documented contract of each Ansible module, including its
|
|
idempotence and change detection.
|
|
- Gather state only when the result controls necessary behavior that the
|
|
responsible module cannot determine. Fingerprints, checksums, sidecar state,
|
|
manual drift detection, and speculative recovery paths require an explicit
|
|
acceptance criterion and rationale. Do not precede a declarative module with
|
|
a probe or recreate its internal logic unless a concrete requirement cannot
|
|
be expressed by the module itself.
|
|
- 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.
|