mirror of
https://github.com/status-im/ift-docs.git
synced 2026-08-31 03:41:09 +00:00
Jorge Campo
2d66d07028
Added repository-wide instructions for using Copilot effectively, including purpose, operational checklist, and guidelines for documentation edits.
52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# Copilot instructions (repository-wide)
|
||
|
||
## Purpose
|
||
|
||
Make successful docs PRs on the first try by using the repo’s own bootstrap → lint → links → build pipeline. These instructions apply to Copilot Chat, the coding agent, and PR review.
|
||
|
||
## What this repo is
|
||
|
||
- Docs-first repository. Primary content under `docs/`.
|
||
- Config at repo root: `.vale.ini` + `vale/`, `.markdownlint.*` (or remark config), `.cspell.json`, `lychee.*`, optional site generator config (`mkdocs.yml` or Docusaurus files).
|
||
- Use **Makefile** targets or **package.json** scripts when present. Avoid calling underlying CLIs directly.
|
||
|
||
## Operational checklist (before proposing a PR)
|
||
|
||
1) Bootstrap
|
||
- If `Makefile` has a bootstrap target: `make bootstrap`
|
||
- Else if `package.json` exists: `npm ci`
|
||
- If Python tooling is used: create venv, `pip install -r requirements.txt`
|
||
|
||
2) Lint
|
||
- Markdown: `make lint-md` or `npm run lint:md`
|
||
- Prose/style (Vale): `make lint-prose` or `npm run lint:prose`
|
||
- Spelling (cspell): `make lint-spell` or `npm run lint:spell`
|
||
- Links (lychee): `make lint-links` or `npm run lint:links`
|
||
|
||
3) Build / Preview (only if site generator is configured)
|
||
- MkDocs: `mkdocs build` (local preview: `mkdocs serve`)
|
||
- Docusaurus: `npm run build` (local preview: `npm run start`)
|
||
|
||
4) Stop if any step fails. Fix locally, re-run, then open the PR.
|
||
|
||
## Guardrails for docs edits
|
||
|
||
- Keep front matter and any HTML-comment rule IDs intact.
|
||
- For procedures, use Markdown numbered lists; put paragraphs, code, and images **under** the correct list item (blank line + indent).
|
||
- Use relative links for internal references; update inbound links if a file moves.
|
||
- If adding code blocks or screenshots, follow the Style Guide documents in the repo (do not restate rules here).
|
||
- Keep changes small and scoped; preserve technical accuracy and author voice.
|
||
|
||
## Scope
|
||
|
||
Markdown files under content under `/docs/**`.
|
||
|
||
## PR review behavior
|
||
|
||
- Re-run the same pipeline locally before pushing fixes.
|
||
- When moving or renaming files, update navigation/sidebars (if applicable) and re-run link checks.
|
||
|
||
## Source of truth
|
||
|
||
- Prefer repo scripts. If a script is missing, consult the config files at repo root for tool flags and rules. Do not duplicate Style-Guide content here.
|