Add automated style guide#4830
Draft
aneta-petrova wants to merge 19 commits into
Draft
Conversation
github-actions
Bot
added
Needs tech review
|
The PR preview for 0609413 is available at theforeman-foreman-documentation-preview-pr-4830.surge.sh The following output files are affected by this PR: |
9 tasks
9 tasks
Contributor
|
It would be better to implement this as rules for writing rather than a validation check. |
aneta-petrova
removed
Needs tech review
Member
Author
Which part? (EDIT: Which part of the PR?) |
Contributor
Actually, I might have misunderstood what you're trying to achieve with this PR. Not sure what that is. Consider my comment premature. |
CONTRIBUTING.md is now a symlink to a skill file that serves dual purposes:
- Human-readable contribution guidelines (visible on GitHub)
- AI-invocable validation skill via /validate-contribution
The skill validates and auto-fixes common issues in documentation contributions:
- Trailing whitespace removal
- File naming conventions (con_, proc_, ref_, snip_ prefixes)
- Content type attributes
- Module ID format with {context}
- Hardcoded product names replaced with attributes
- Vale linter integration
- Build verification
Contributors can run /validate-contribution manually to check their changes
before submitting PRs.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Create a standalone guide at guides/doc-Contributing/ that consolidates all contribution resources into a single HTML page. Content included: - CONTRIBUTING.md (contribution guidelines) - All documentation skills from .cursor/skills/ (abstract, heading, prerequisites, refactor-adoc, split-web-ui-cli, validate-contribution) - Project-specific Vale rules from .vale/styles/foreman-documentation/ (AvoidBrandedTerminology, Capitalization, OneSentencePerLine) Build system: - Uses kramdown (Ruby markdown processor) instead of asciidoctor - Single build (no BUILD context variants like foreman-el, katello, etc.) - Auto-rebuilds on GitHub when source files change via Makefile dependencies - Output: guides/build/Contributing/index.html Files added: - guides/doc-Contributing/build.rb - Concatenates markdown sources, strips YAML frontmatter, converts to HTML - guides/doc-Contributing/template.html - HTML5 template with responsive CSS, TOC sidebar, syntax highlighting - guides/doc-Contributing/Makefile - Build system with dependency tracking - guides/doc-Contributing/README.md - Documentation for using the guide Modified: - Gemfile - Added kramdown and kramdown-parser-gfm gems - guides/Makefile - Excluded doc-Contributing from BUILD matrix, added separate 'contributing' target The guide auto-rebuilds in GitHub Actions when CONTRIBUTING.md, skill files, or Vale rules are modified. No workflow changes needed. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>
aneta-petrova
force-pushed
the
ai-contributors
branch
2 times, most recently
from
760bd4b to
a516e6a
Compare
aneta-petrova
force-pushed
the
ai-contributors
branch
from
a516e6a to
d0065a4
Compare
- Reorganize skill files with standardized sections: - Overview: Human-readable guidelines and definitions - Examples: Good/bad examples with explanations - Instructions: AI-specific workflow steps - Update build.rb to extract only Overview and Examples sections for the Contributors' Guide - Change category headings to top-level in the guide - Fix .claude/skills path (was incorrectly .cursor/skills) - Update all skills except validate-contribution with new structure: abstract, heading, prerequisites, refactor-adoc, review-assembly-user-story, split-web-ui-cli This separates human-facing documentation guidelines from AI-specific instructions, making the Contributors' Guide more focused and useful for human contributors. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Extract YAML comment descriptions as Overview sections for Vale rules - Update Vale rule descriptions to imperative voice: - "Use attributes instead of branded terms" - "Use proper capitalization for product names and technical terms" - "Write one sentence per line" - Rename category to "Foreman-documentation custom Vale rules" - Add skip notification for skills without Overview/Examples sections - Match formatting style with AI skills section (H1 categories, H2 items) Vale rules now have the same human-friendly structure as AI skills, with Overview sections explaining the rules in user-directed language. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Expand Vale rule Overview sections with detailed explanations: - AvoidBrandedTerminology: Explain attribute usage for multi-product docs - Capitalization: Include examples and context exceptions - OneSentencePerLine: Explain benefits for version control and review - Replace embedded YAML code blocks with links to rule files - Keep guide focused on guidelines rather than technical implementation This makes the Contributors' Guide more readable while still providing access to the detailed rule definitions via links. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
aneta-petrova
force-pushed
the
ai-contributors
branch
from
41cc619 to
a569878
Compare
- Create new "personas" skill for user persona guidelines - Overview explains User, Admin, and Architect personas - Instructions for applying persona-appropriate content - Restructure "validate-contribution" skill as "Documentation conventions" - Add comprehensive Overview section covering all conventions - Add Examples section with good/bad examples - Keep AI validation instructions in Instructions section - Improve code block handling in build script - Now properly appears in Contributors' Guide - Update build.rb to include personas in style guidelines category Both skills now follow the standard structure with Overview and Examples sections for the Contributors' Guide, while keeping detailed AI instructions separate. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Member
Author
|
I'm not ready to switch this to |
Vale rules are run by the Vale linter locally and in CI, not in AI-assisted editors. Co-authored-by: Cursor <cursoragent@cursor.com>
Replace links to Vale rule files with embedded YAML content inside collapsible HTML <details> sections. This keeps the guide concise while making full rule definitions accessible without navigation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
aneta-petrova
force-pushed
the
ai-contributors
branch
from
881b9bb to
0609413
Compare
Contributor
|
You could put all the AI guidelines into a single CLAUDE.md file. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes are you introducing?
Adding a style guide for the project that concatenates the following resources:
OverviewandExamplesget pulled into the style guide in full, and the rest (AI instructions) gets pulled in as collapsible content)Why are you introducing these changes? (Explanation, links to references, issues, etc.)
There are so many style resources and guidelines and rules that it's hard for a person to keep up with them. Automation should help us conform to all of these rules, but defining the rules both in a style guide and through automation introduces overhead and the risk of the style guides and automation getting out of sync.
With an automatically built style guide such as this one, we have one source of truth -- the automation-friendly resources -- but still keep a human-friendly guide for easy reference.
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
This project is based on the idea that if we want to introduce a new style/contribution rule, we should think in an "automation-first" rule. In its most radical sense, it would mean that if it can't be automated (through an AI skill or a Vale rule etc.), it should not be a contribution rule. And because not everyone's this radical, there's CONTRIBUTING.md for exceptions :)
One of the outcomes should be being able to show the automated style guide next to a regular style guide for comparison. It doesn't have to be a 1:1 match but just to show that the automated style guide can also serve as a style guide for a documentation project.
Contributor checklists
Please cherry-pick my commits into: