From ec0f1a06cdbeaaaafefa40a02dbccdb633350658 Mon Sep 17 00:00:00 2001 From: pkuwkl Date: Wed, 15 Jul 2026 17:28:11 +0800 Subject: [PATCH] docs(contexts): prevent hard-wrapped GitHub prose --- .agents/skills/quantmind-dev/SKILL.md | 5 +- .../quantmind-dev/references/pull-request.md | 5 +- .claude/skills/quantmind-dev/SKILL.md | 5 +- .../quantmind-dev/references/pull-request.md | 5 +- .github/ISSUE_TEMPLATE/bug_report.md | 2 + .github/ISSUE_TEMPLATE/feature_request.md | 2 + .github/PULL_REQUEST_TEMPLATE.md | 2 + AGENTS.md | 3 + CLAUDE.md | 3 + contexts/dev/README.md | 1 + contexts/dev/github-writing.md | 46 ++++++++++++ contexts/dev/labels.md | 3 + tests/test_contexts.py | 70 ++++++++++++++++++- 13 files changed, 145 insertions(+), 7 deletions(-) create mode 100644 contexts/dev/github-writing.md diff --git a/.agents/skills/quantmind-dev/SKILL.md b/.agents/skills/quantmind-dev/SKILL.md index 1e60a0f..e4beb79 100644 --- a/.agents/skills/quantmind-dev/SKILL.md +++ b/.agents/skills/quantmind-dev/SKILL.md @@ -17,7 +17,10 @@ Development workflow for contributing to the QuantMind codebase. operation or public-network source. 4. When creating, updating, or triaging an issue or pull request, use the canonical [repository label guidance](../../../contexts/dev/labels.md). -5. Pick exactly one workflow reference below; do not load the others. +5. Before writing or editing any GitHub body, follow the canonical + [GitHub writing style](../../../contexts/dev/github-writing.md), including + its no-hard-wrap rule. +6. Pick exactly one workflow reference below; do not load the others. ## Select Workflow diff --git a/.agents/skills/quantmind-dev/references/pull-request.md b/.agents/skills/quantmind-dev/references/pull-request.md index 36f4231..d57de56 100644 --- a/.agents/skills/quantmind-dev/references/pull-request.md +++ b/.agents/skills/quantmind-dev/references/pull-request.md @@ -34,7 +34,10 @@ batch input`, `docs(readme): update quick start`. Written in English (external audiences read it: contributors, search indexers, future maintainers). Follow `.github/PULL_REQUEST_TEMPLATE.md` -and make sure the body covers: +and the canonical +[GitHub writing style](../../../../contexts/dev/github-writing.md). Do not +hard-wrap body prose at 80 columns or another fixed width. Make sure the body +covers: 1. **What changed and why** — a short summary; link the design discussion if one exists. diff --git a/.claude/skills/quantmind-dev/SKILL.md b/.claude/skills/quantmind-dev/SKILL.md index 1e60a0f..e4beb79 100644 --- a/.claude/skills/quantmind-dev/SKILL.md +++ b/.claude/skills/quantmind-dev/SKILL.md @@ -17,7 +17,10 @@ Development workflow for contributing to the QuantMind codebase. operation or public-network source. 4. When creating, updating, or triaging an issue or pull request, use the canonical [repository label guidance](../../../contexts/dev/labels.md). -5. Pick exactly one workflow reference below; do not load the others. +5. Before writing or editing any GitHub body, follow the canonical + [GitHub writing style](../../../contexts/dev/github-writing.md), including + its no-hard-wrap rule. +6. Pick exactly one workflow reference below; do not load the others. ## Select Workflow diff --git a/.claude/skills/quantmind-dev/references/pull-request.md b/.claude/skills/quantmind-dev/references/pull-request.md index 36f4231..d57de56 100644 --- a/.claude/skills/quantmind-dev/references/pull-request.md +++ b/.claude/skills/quantmind-dev/references/pull-request.md @@ -34,7 +34,10 @@ batch input`, `docs(readme): update quick start`. Written in English (external audiences read it: contributors, search indexers, future maintainers). Follow `.github/PULL_REQUEST_TEMPLATE.md` -and make sure the body covers: +and the canonical +[GitHub writing style](../../../../contexts/dev/github-writing.md). Do not +hard-wrap body prose at 80 columns or another fixed width. Make sure the body +covers: 1. **What changed and why** — a short summary; link the design discussion if one exists. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index fe1c2a1..3b49264 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,6 +6,8 @@ labels: ['type: bug'] assignees: '' --- + + ## 🐛 Bug Description diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index e86df97..a3c4dc9 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -6,6 +6,8 @@ labels: ['type: feature'] assignees: '' --- + + ## ✨ Feature Summary diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6c2f1ee..90c5d98 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,5 @@ + + ## Summary diff --git a/AGENTS.md b/AGENTS.md index acc6a1f..5a2f200 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,6 +89,9 @@ A new feature ships with a unit test **and** a focused example: - Commit messages: English, Conventional Commits. - PR titles, PR bodies, and issue bodies: English. +- GitHub Issue, Pull Request, Discussion, and comment body formatting follows + the [GitHub writing style](contexts/dev/github-writing.md); never hard-wrap + remote prose at 80 columns or another fixed width. - Code comments and docstrings: English, Google style. ## Development Workflows diff --git a/CLAUDE.md b/CLAUDE.md index 538fa0b..a599942 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,6 +90,9 @@ A new feature ships with a unit test **and** a focused example: - Commit messages: English, Conventional Commits. - PR titles, PR bodies, and issue bodies: English. +- GitHub Issue, Pull Request, Discussion, and comment body formatting follows + the [GitHub writing style](contexts/dev/github-writing.md); never hard-wrap + remote prose at 80 columns or another fixed width. - Code comments and docstrings: English, Google style. ## Development Workflows diff --git a/contexts/dev/README.md b/contexts/dev/README.md index fb438aa..30d1e4e 100644 --- a/contexts/dev/README.md +++ b/contexts/dev/README.md @@ -8,6 +8,7 @@ canonical source instead of treating this page as a replacement for it. | Architecture constraints and module ownership | [`AGENTS.md`](../../AGENTS.md) or [`CLAUDE.md`](../../CLAUDE.md) | | Component-development workflow | [`quantmind-dev` component workflow](../../.agents/skills/quantmind-dev/references/develop-components.md) | | Issue and pull-request labels | [Repository label guidance](labels.md) | +| Issue and pull-request body formatting | [GitHub writing style](github-writing.md) | | Public operation and source catalog | [`docs/README.md`](../../docs/README.md) | | Public operation naming | [Operation naming contract](../../docs/design/en/operations.md) | | Component designs | [`docs/design/`](../../docs/design/) | diff --git a/contexts/dev/github-writing.md b/contexts/dev/github-writing.md new file mode 100644 index 0000000..ef1485c --- /dev/null +++ b/contexts/dev/github-writing.md @@ -0,0 +1,46 @@ +# GitHub Writing Style + +This guide is the canonical source-format contract for QuantMind Issue, Pull +Request, Discussion, and comment bodies. It applies to text submitted to +GitHub, not to Markdown files stored in the repository. + +## No Hard-wrapped Prose + +GitHub wraps rendered prose for the viewer. Do not insert source newlines at a +fixed width, including 80 columns. + +- Keep each logical paragraph on one physical source line. +- Keep each list or checklist item on one physical source line. +- Keep each blockquote paragraph on one physical source line after `>`. +- Keep each Markdown table row on one physical source line. +- Preserve line structure inside fenced code blocks. +- Use blank lines, headings, lists, code fences, tables, or an intentional + Markdown hard break only when they express real structure. + +Repository formatters and code line-length settings do not apply to GitHub +body prose. In particular, do not run Issue or Pull Request bodies through +`textwrap.fill`, an 80-column editor wrap, or a Markdown formatter configured +to wrap prose. + +## Write Workflow + +1. Draft the complete body with one logical prose unit per source line. +2. Preserve the selected Issue or Pull Request template and its checklist. +3. Submit the body as written, preferably with `--body-file` when using `gh`. +4. Read the raw body back after creation or editing and check that prose was + not hard-wrapped before considering the write complete. + +When Prettier is already available, use its no-wrap mode as a preflight on the +temporary body file: + +```bash +prettier --write --parser markdown --prose-wrap never /tmp/github-body.md +prettier --check --parser markdown --prose-wrap never /tmp/github-body.md +``` + +Do not introduce a repository-wide Markdown formatter or change Python's +80-column setting for this purpose. The preflight applies only to the temporary +GitHub body. + +When updating an existing hard-wrapped body, normalize the complete body while +preserving its meaning, headings, lists, code blocks, links, and checkboxes. diff --git a/contexts/dev/labels.md b/contexts/dev/labels.md index 7272886..0ecb799 100644 --- a/contexts/dev/labels.md +++ b/contexts/dev/labels.md @@ -69,6 +69,9 @@ type, area, and impact dimensions. ## Issues and Pull Requests +Body source formatting follows the [GitHub writing style](github-writing.md), +including its no-hard-wrap rule. + - Label an issue from the intended problem and accepted scope. - Label a pull request from its actual diff. - A pull request that closes an issue should normally align with the issue's diff --git a/tests/test_contexts.py b/tests/test_contexts.py index 0dc14f7..c84e538 100644 --- a/tests/test_contexts.py +++ b/tests/test_contexts.py @@ -9,6 +9,7 @@ def test_context_index_targets_exist(self) -> None: context_indexes = ( "contexts/README.md", "contexts/dev/README.md", + "contexts/dev/github-writing.md", "contexts/dev/labels.md", "contexts/usage/README.md", ) @@ -118,9 +119,72 @@ def test_label_guide_has_complete_taxonomy(self) -> None: with self.subTest(dimension=dimension): self.assertEqual(found, expected) + def test_github_writing_guide_has_required_routes(self) -> None: + repo_root = Path(__file__).resolve().parents[1] + required_links = { + "contexts/dev/README.md": "github-writing.md", + "contexts/dev/labels.md": "github-writing.md", + "AGENTS.md": "contexts/dev/github-writing.md", + "CLAUDE.md": "contexts/dev/github-writing.md", + ".agents/skills/quantmind-dev/SKILL.md": ( + "../../../contexts/dev/github-writing.md" + ), + ".claude/skills/quantmind-dev/SKILL.md": ( + "../../../contexts/dev/github-writing.md" + ), + ".agents/skills/quantmind-dev/references/pull-request.md": ( + "../../../../contexts/dev/github-writing.md" + ), + ".claude/skills/quantmind-dev/references/pull-request.md": ( + "../../../../contexts/dev/github-writing.md" + ), + } + + for source_path, target in required_links.items(): + source = repo_root / source_path + with self.subTest(source=source_path): + self.assertIn( + f"]({target})", + source.read_text(encoding="utf-8"), + f"{source_path} must route to the GitHub writing guide", + ) + self.assertTrue( + (source.parent / target).resolve().is_file(), + f"broken GitHub writing guide link: {target}", + ) + + marker = "