Skip to content

docs: move the role and plugin rules to docs/developer-guide/ - #796

Merged
markuslf merged 1 commit into
mainfrom
docs/developer-guide-split
Nov 20, 2026
Merged

markuslf merged 1 commit into
mainfrom
docs/developer-guide-split

Conversation

@markuslf

Copy link
Copy Markdown
Member

CONTRIBUTING.md (85 KB) is beyond what people and coding agents read in full; the Linuxfabrik Standards set a limit of 50 KB. Its Ansible guidelines move into nine files under docs/developer-guide/, each listed in a table in CONTRIBUTING.md that says when to read it:

File Characters
roles.md 22,875
variables.md 11,089
testing.md 10,982
tasks.md 8,371
systemd.md 7,999
upstream.md 5,008
templates.md 2,659
plugins.md 2,201
playbooks.md 2,019

CONTRIBUTING.md keeps the style guide, commit scopes, deliverables, OS coverage, security by default, the changelog sections and the credits, and shrinks to 14 KB.

A word count over all files against the original shows no change apart from the new table and the title "systemd". Quoted section names that now point to another file become links, and relative links follow the move; every link and anchor resolves.

The 38 references to CONTRIBUTING.md sections in roles, roles/shared/README.md, Molecule, .gitignore, tests/unit/test_playbooks.py, tools/maintenance.yml and the lfops-follow-upstream skill point to the new files.

tools/build-docs lists docs/developer-guide/ in the mkdocs nav under "Developer Guide", and writes docs/contributing.md as a copy in which links into docs/developer-guide/ work on the documentation site.

This is a move only; the adoption of the shared standards block follows in a pull request of its own.

Checks:

  • mkdocs build with the pinned versions after tools/build-docs, compared against main: no new findings.
  • pre-commit hooks pass on the changed files; tools/sync-standards check passes.
  • Unit tests and Molecule were not run locally, as only comments and tools/build-docs changed; CI runs the unit tests.

CONTRIBUTING.md (85 KB) is beyond what people and coding agents read
in full. Its Ansible guidelines move into nine files under
docs/developer-guide/ (playbooks, plugins, roles, systemd, tasks,
templates, testing, upstream, variables), each listed in a table in
CONTRIBUTING.md with when to read it. CONTRIBUTING.md keeps the style
guide, deliverables, OS coverage, security by default and the
changelog sections, and shrinks to 14 KB.

A word count over all files shows no change apart from the new table
and the title "systemd". Quoted section names that now point to
another file become links, and relative links follow the move.

The 38 references to CONTRIBUTING.md sections in roles, Molecule,
tests, tools/maintenance.yml and the follow-upstream skill point to
the new files.

tools/build-docs lists docs/developer-guide/ in the mkdocs nav, and
writes docs/contributing.md as a copy whose links into
docs/developer-guide/ work on the documentation site. A build
compared against main shows no new link findings.
@markuslf
markuslf merged commit 23aae1e into main Nov 20, 2026
15 checks passed
@markuslf
markuslf deleted the docs/developer-guide-split branch November 20, 2026 21:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant