docs(doc-style): backtick consistency audit - #81
Closed
prikotov wants to merge 7 commits into
Closed
Conversation
validator.md: 26.6% → 0.0% via Russian technical writing (translate generic words, backtick code identifiers, English terms in parens on first mention). No allowlist gaming — proves the conventions docs can reach 0% editorially. allowlist: add PSR, PHPMD, XML — genuine abbreviations/tools parallel to the existing PHP/SQL/JSON/YAML/PHPUnit entries (consistent policy, not ratio gaming).
…r threshold Reduce anglicism ratio in all docs/conventions/ files below the 2% threshold (overwhelmingly to 0.0%) via Russian technical writing — not allowlist gaming. Technique (validator.md is the exemplar): - code identifiers / class names -> backticks (extractor excludes inline code); - English terms -> «русский (english)» on first mention (parens excluded); - generic English words -> Russian translation. Result: validate-language on docs/ -> 0 files over threshold (was 63); worst files 17-27% -> 0% (presentation.md, query-dto/request-dto/response-dto, criteria-mapper). validate-docs + validate-md-links pass. Front matter, fenced code blocks, and links preserved; no meaning distorted. Reaches the bar the docs prescribe: warning-mode gives 0 real anglicisms — --strict can now be enabled. Root README.md (2.9%) and AGENTS.md (8.7%) are out of scope (not conventions).
README.md: 2.9% → 0.0%. AGENTS.md: 8.7% → 0.0%. Same technique as the conventions cleanup (backtick code/paths/commands, English-in-parens, Russian-ize link labels and generic prose). Rules, commands, and links preserved; validate-md-links passes (no broken anchors from the 'Git workflow' → 'Git-процесс' heading rename). Package's own validate-language now reports 0 files over threshold across all default paths (docs/, README.md, AGENTS.md).
Now that the anglicism cleanup reached 0 files over threshold across all default paths (docs/, README.md, AGENTS.md), flip validate-language to --strict in composer check. Any future regression that pushes a file over the 2% ratio fails CI immediately — the cleanup is now load-bearing. Verified: 'composer check' exits 0; highest ratio 1.9% (under the 2% gate).
The metric-driven anglicism cleanup left inconsistent backticks: it backticked only non-allowlisted words (to pass the gate) and left allowlisted terms bare, so e.g. `Common` was backticked while the layer names (Domain/Application/...) next to it were bare, and the concept 'Enum' sat beside the keyword `match`. Apply the semantic rule uniformly in enum.md: - backtick literal code: keywords (`enum`, `match`, `case`), class names (`ApplicationEnum`, `ValueError`), paths/namespaces, layer names used as namespace references (`Domain`, `Application`, `Common`, ...); - prose concept -> Russian «перечисление» (the term the doc already establishes); English gloss stays in parens «перечисление (Enum)». enum.md still 0.0%; validate-docs passes.
Add docs/conventions/principles/doc-style.md — the convention for backtick placement: backtick literal code (keywords, identifiers, paths, namespaces, layer names as code refs); leave concept terms in prose (Russian, or English gloss in parens). Key rule: allowlist does NOT decide backticks — only semantics (code vs concept) does. This fixes the metric-driven inconsistency (e.g. `Common` backticked while allowlisted layer names beside it were bare). allowlist + PascalCase, camelCase, kebab-case — common naming-convention terms (concepts, not code identifiers), so they read bare in prose.
Apply docs/conventions/principles/doc-style.md uniformly: backtick ALL code identifiers — including allowlisted layer/pattern names (Domain, Application, Presentation, Repository, Service, Validator, ...) when used as code/namespace references, not just non-allowlisted words. The anglicism cleanup had backticked only what the linter required, leaving allowlisted names bare beside backticked siblings (the inconsistency spotted in enum.md). Also un-backtick naming-convention concept terms (PascalCase, camelCase) now that they are allowlisted terms. Cosmetic consistency only — no meaning, code blocks, front matter, links, or structure changed. All files remain at 0.0% anglicism ratio; validate-docs and validate-md-links pass. 6 of 48 files were already consistent (no change).
Owner
Author
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
1 participant
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.
Что и зачем
Отдельный аудит-проход (запрошен отдельно): применить
docs/conventions/principles/doc-style.mdединообразно ко всем почищенным конвенциям. Чистка англицизмов (PR #80) обрамляла в backticks только то, что требовал линтер, — allowlisted имена слоёв/паттернов (Domain,Application,Presentation,Repository,Service,Validator…) оставались bare как code-ссылки рядом с обрамлёнными соседями (та самая непоследовательность, замеченная вenum.md).Эта ветка основана на
task/docs-anglicism-cleanup(PR #80). Сначала мёрдж PR #80 — после него этот PR покажет только diff аудита (42 файла). Сейчас в списке коммитов видны и коммиты #80.Что сделано
PascalCase,camelCase, теперь в allowlist) — обратно bare в прозе.Объём
Проверка
composer check(со--strict) → EXIT=0, 0 over-threshold, internal links valid, validate-docs pass.layers.md, ~40 правок в таблицах/заголовках) — единообразно, голых layer-refs нет.validate-language <file> <2%+validate-docs.