From ce3bb378d3e58c7023088d92ef9042e5a2d61235 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Apr 2026 21:50:31 +0300 Subject: ci: add CLAUDE.md and Copilot custom instructions (#1830) * ci: add CLAUDE.md and GitHub Copilot custom instructions Add AI assistant instructions to improve automated review quality: - CLAUDE.md: project conventions, RST rules, linter details - .github/copilot-instructions.md: repo-wide Copilot context - .github/instructions/rst-linter.instructions.md: linter rules for RST files (address space, line length, suppression syntax) Co-Authored-By: Claude Opus 4.6 (1M context) * docs: fix build commands, code-block exemption, and address space heading - Fix Docker build/run commands to match README (vyos/vyos-documentation image, /vyos mount, /vyos/docs workdir) - Fix local build to run from docs/ directory - Clarify code-block lines are exempt from 80-char limit - Expand address space heading to reference docs/documentation.rst - Fix confusing 0.0.0.0/0 entry in common mistakes - Simplify inline code backtick example Co-Authored-By: Claude Opus 4.6 (1M context) * docs: expand Copilot instructions to reduce false positive reviews Add guidance for common false positives observed in automated reviews: - Only flag issues introduced by the PR, not pre-existing - Column-0 linter markers are the repo convention, not a bug - Code-block lines are exempt from 80-char limit - RFC 1918 and other private IPs are allowed without suppression - TODO markers can be intentionally added for tracking - YAML in code blocks uses RST-relative indentation Co-Authored-By: Claude Opus 4.6 (1M context) * docs: fix backtick rendering and linter marker indentation guidance - CLAUDE.md: use fenced code span to show RST double-backtick syntax - copilot-instructions.md: markers match surrounding indentation inside directives, column 0 at top level (both patterns exist in repo) Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .github/instructions/rst-linter.instructions.md | 70 +++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .github/instructions/rst-linter.instructions.md (limited to '.github/instructions') diff --git a/.github/instructions/rst-linter.instructions.md b/.github/instructions/rst-linter.instructions.md new file mode 100644 index 00000000..419f094a --- /dev/null +++ b/.github/instructions/rst-linter.instructions.md @@ -0,0 +1,70 @@ +--- +applyTo: "**/*.rst" +--- + +## RST Linter Rules + +Every pull request is automatically linted by `doc-linter.py` (from the `vyos/.github` repository). It checks **only changed files** for two things: IP address usage and line length. + +### IP Address Rules + +The linter rejects public IP addresses that are not reserved for documentation. + +**Use these documentation-reserved addresses (no suppression needed):** + +| Type | Range | RFC | +|------|-------|-----| +| IPv4 | `192.0.2.0/24` (TEST-NET-1) | RFC 5737 | +| IPv4 | `198.51.100.0/24` (TEST-NET-2) | RFC 5737 | +| IPv4 | `203.0.113.0/24` (TEST-NET-3) | RFC 5737 | +| IPv6 | `2001:db8::/32` | RFC 3849 | + +**These are allowed without suppression (not flagged by linter):** + +| Type | Range | Why | +|------|-------|-----| +| RFC 1918 private | `10.0.0.0/8` | Private address space | +| RFC 1918 private | `172.16.0.0/12` | Private address space | +| RFC 1918 private | `192.168.0.0/16` | Private address space | +| Loopback | `127.0.0.0/8` | Loopback range | +| Link-local | `169.254.0.0/16` | Link-local | + +**These require `stop/start_vyoslinter` suppression:** + +| Example | Why suppression is needed | +|---------|--------------------------| +| `8.8.8.8` (Google DNS) | Real public IP, not documentation-reserved | +| `64:ff9b::/96` (NAT64) | Well-known prefix, not in doc ranges | +| Real provider IPs in examples | Authenticity matters for the example | + +### Line Length Rules + +Maximum 80 characters per line. Lines inside `.. code-block::` directives are **exempt** from the line length limit (they render with `
` tags and preserve source formatting).
+
+### Suppression Syntax
+
+When real public IPs or long lines are unavoidable, wrap the block:
+
+```rst
+.. stop_vyoslinter
+
+.. code-block:: none
+
+   set system name-server '8.8.8.8'
+
+.. start_vyoslinter
+```
+
+**Rules for suppression markers:**
+
+- Place `.. stop_vyoslinter` on its own line, immediately before the content
+- Place `.. start_vyoslinter` on its own line, immediately after the content
+- Always re-enable the linter — never leave it stopped for the rest of the file
+- Suppress the smallest possible region
+- Do NOT use suppression for content that can use documentation-reserved addresses instead
+
+### Common Mistakes
+
+- Removing `stop/start_vyoslinter` markers without fixing the underlying issue (exposes the line to the linter and fails CI)
+- Using real public IPs when documentation addresses would work just as well
+- Adding suppression markers around content that only has private (RFC 1918) addresses or `0.0.0.0/0` — these are allowed and don't need suppression
-- 
cgit v1.2.3