Skip to content

Commit bd55d11

Browse files
Tapanitomvadari
Tapanito
and
mvadari
committed
Revise Copilot instructions for XRPL-Standards
Updated instructions for Copilot Cloud Agent in XRPL-Standards repository, including repository purpose, layout, and key rules. Co-authored-by: mvadari <mvadari@gmail.com>
1 parent c1a4259 commit bd55d11

1 file changed

Lines changed: 121 additions & 38 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 121 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,141 @@
1-
# GitHub Copilot Instructions for XRPL-Standards
1+
# Copilot Cloud Agent Instructions — XRPL-Standards
22

3-
## Repository Summary
3+
## Repository Purpose
44

5-
**Documentation-only** repository for XRP Ledger Standards (XLSes) — Markdown specification documents plus Python validation/site-generation scripts and GitHub Actions CI. No application code to compile. Trust these instructions; only search if something here is incomplete or in error.
5+
This repository is the canonical home for **XRP Ledger Standards (XLSes)** — specifications and standards that govern the XRP Ledger ecosystem. Each XLS is a living document covering protocol amendments, system-level changes, or community/off-chain conventions. The full process is defined in [XLS-0001](../XLS-0001-xls-process/README.md) and summarized in [CONTRIBUTING.md](../CONTRIBUTING.md).
66

7-
## Project Layout
7+
---
88

9-
| Path | Purpose |
10-
| ------------------------------------ | --------------------------------------------------------------------- |
11-
| `XLS-NNNN-short-title/README.md` | One specification per standard (74 total) |
12-
| `templates/XLS_TEMPLATE.md` | Base template for all new XLS specs |
13-
| `templates/AMENDMENT_TEMPLATE.md` | Specification section structure for Amendment XLSes |
14-
| `scripts/xls_parser.py` | Parses and validates preambles of all XLS docs (main CI) |
15-
| `scripts/validate_xls_template.py` | Validates structure of changed files (Beta CI) |
16-
| `scripts/requirements.txt` | Python deps: markdown, jinja2, beautifulsoup4, pyyaml, markdown-it-py |
17-
| `.github/workflows/lint.yml` | prettier@3.6.2 check — **required on every PR** |
18-
| `.github/workflows/validate-xls.yml` | xls_parser + template validator — **required on every PR** |
19-
| `.pre-commit-config.yaml` | prettier@3.6.2 + trailing-whitespace, end-of-file-fixer |
9+
## Repository Layout
2010

21-
## XLS Preamble Format
11+
```
12+
/
13+
├── XLS-NNNN-slug/ # One folder per XLS spec (4-digit zero-padded number + hyphenated title)
14+
│ └── README.md # The XLS document itself (required)
15+
├── templates/
16+
│ ├── XLS_TEMPLATE.md # Preamble + section scaffold for all new XLSes
17+
│ └── AMENDMENT_TEMPLATE.md # Extra scaffold for Amendment-category XLSes (Section 3 onward)
18+
├── scripts/
19+
│ ├── requirements.txt # Python deps (install with: pip install -r scripts/requirements.txt)
20+
│ ├── xls_parser.py # Parses XLS README.md files and validates preamble metadata
21+
│ ├── validate_xls_template.py # Validates XLS structure against templates (Beta CI)
22+
│ └── build_site.py # Builds the GitHub Pages static site from XLS docs
23+
├── CONTRIBUTING.md # How to contribute (summarises XLS-1)
24+
└── .github/
25+
├── pull_request_template.md
26+
├── workflows/ # CI workflows (see below)
27+
└── scripts/ # Scripts used by CI (assign_xls_number.py, etc.)
28+
```
29+
30+
---
31+
32+
## XLS Document Format
2233

23-
Every `README.md` must open with a `<pre>` block (the `xls_parser.py` CI reads it):
34+
Every XLS lives at `XLS-NNNN-slug/README.md` and **must** start with an RFC-822-style `<pre>` preamble block:
2435

2536
```
2637
<pre>
2738
xls: [number]
28-
title: [max 44 chars, no "XLS" prefix or number]
29-
description: [one full sentence]
30-
author: [Name <email@example.com>, Name2 (@github-handle)]
39+
title: [max 44 chars, no "XLS" prefix]
40+
description: [max 140 chars, one sentence]
41+
author: Name (@github-handle), Other Name <email@example.com>
3142
category: [Amendment | System | Ecosystem | Meta]
3243
status: [Draft | Final | Living | Deprecated | Stagnant | Withdrawn]
33-
proposal-from: [URL to GitHub Discussions thread]
44+
proposal-from: https://github.com/XRPLF/XRPL-Standards/discussions/NNN
3445
created: YYYY-MM-DD
35-
updated: YYYY-MM-DD ← optional
36-
implementation: [URL] ← optional; required for Final Amendment/System
37-
requires: XLS-N, XLS-M ← optional
38-
withdrawal-reason: [text] ← required if status is Withdrawn
46+
updated: YYYY-MM-DD # optional
47+
implementation: [url] # optional, for Amendment/System XLSes
48+
requires: [xls numbers] # optional
49+
withdrawal-reason: [reason] # required only when status is Withdrawn
3950
</pre>
4051
```
4152

42-
Every author **must** have a link — `Name <email>` or `Name (@github-handle)`; a bare name fails CI.
53+
**Required sections** (all XLSes): Abstract, Rationale, Security Considerations.
54+
**Amendment XLSes** additionally require the sub-structure from `AMENDMENT_TEMPLATE.md` covering STypes, Ledger Entries, Transactions, Permissions, and RPCs as applicable.
55+
56+
### Categories
57+
58+
| Category | Description |
59+
|----------|-------------|
60+
| `Amendment` | Requires an XRP Ledger amendment (on-chain protocol change via rippled) |
61+
| `System` | Affects XRPL protocol behavior (RPCs, P2P) but no amendment needed |
62+
| `Ecosystem` | Off-chain/community standards (metadata, registries, etc.) |
63+
| `Meta` | Standards about the XLS process itself |
64+
65+
### Statuses
66+
67+
`Idea` → `Proposal` → `Draft` → `Final` or `Living`
68+
69+
Also: `Deprecated` (Final XLS no longer recommended), `Stagnant` (Draft inactive ≥6 months), `Withdrawn` (removed by author — number cannot be reused).
70+
71+
---
72+
73+
## How to Add a New XLS
74+
75+
1. Start in GitHub Discussions (Idea or Proposal stage) — do **not** open a PR until there is community feedback.
76+
2. Create a directory named `XLS-draft-<short-title>/` (agents/authors must NOT self-assign numbers for XLS numbers > 95).
77+
3. Copy `templates/XLS_TEMPLATE.md` to `XLS-draft-<short-title>/README.md` and fill it in.
78+
4. Open a PR. CI will assign the official XLS number automatically after a maintainer with write access approves; the `assign-xls-number.yml` workflow renames the directory and updates the preamble.
79+
80+
---
81+
82+
## CI Workflows
83+
84+
| Workflow | Trigger | What it does |
85+
|----------|---------|--------------|
86+
| `validate-xls.yml` | PRs, push to master | Runs `python scripts/xls_parser.py` — validates preamble of **all** XLS docs |
87+
| `validate-xls.yml` (beta job) | PRs | Runs `python scripts/validate_xls_template.py <changed files>` — checks section structure |
88+
| `assign-xls-number.yml` | PRs | Detects `XLS-draft-*` directories and assigns the next available XLS number after write-access approval |
89+
| `pre-commit.yml` | PRs, push to master | Runs pre-commit hooks (trailing whitespace, end-of-file, prettier) |
90+
| `deploy.yml` | Push to master | Builds and deploys the GitHub Pages site |
91+
| `discussions.yml` | Daily schedule | Closes/warns on stale GitHub Discussions (inactive ≥1 year) |
92+
| `close-xls-discussions.yml` | Push to master | Closes the GitHub Discussion linked in `proposal-from` when an XLS is merged |
93+
94+
### Running Validation Locally
95+
96+
```bash
97+
pip install -r scripts/requirements.txt
98+
99+
# Validate all XLS preambles
100+
python scripts/xls_parser.py
101+
102+
# Validate structure of changed files
103+
python scripts/validate_xls_template.py XLS-NNNN-slug/README.md
104+
105+
# Build the static site
106+
python scripts/build_site.py
107+
```
108+
109+
---
110+
111+
## Code Style and Conventions
112+
113+
- **Markdown formatting**: enforced by `prettier` via pre-commit. Run `pre-commit run --all-files` or let CI flag issues.
114+
- **No trailing whitespace**, files must end with a newline (`end-of-file-fixer` hook).
115+
- **Folder naming**: `XLS-NNNN-slug` with a 4-digit zero-padded number and lowercase hyphenated slug.
116+
- **Author format**: either `Name (@github-handle)` or `Name <email@example.com>` — both forms are parsed by `xls_parser.py`. Each author must have a name **and** a link; otherwise validation fails.
117+
- **Dates**: always `YYYY-MM-DD`.
118+
- **Section numbering**: XLS documents use numeric section headings (`## 1. Abstract`, `## 2. Motivation`, etc.).
119+
- **Python scripts** in `scripts/` use Python 3.11 and are run directly (no build step needed beyond `pip install -r scripts/requirements.txt`).
120+
- **Templates are normative**: sections from `XLS_TEMPLATE.md` and `AMENDMENT_TEMPLATE.md` are checked by `validate_xls_template.py`. Do not skip required sections or leave template placeholders (bracketed instructions) in merged XLS documents.
121+
122+
---
123+
124+
## PR Checklist (from `pull_request_template.md`)
43125

44-
## Template Compliance
126+
- Summarize the change and link any associated GitHub Discussion.
127+
- Check the type of change: New XLS Draft / XLS Update / XLS Status Change / Process/Meta / Infrastructure / Documentation.
128+
- Ensure the preamble is correct and complete.
129+
- Do not self-assign XLS numbers (for numbers > 95); use `XLS-draft-<slug>` naming.
45130

46-
> **Always read the actual template files before reviewing or writing any XLS specification.** The templates are the single source of truth for section structure, sub-section ordering, table column headings, and naming conventions. Do not rely on summaries — open the files directly.
47-
>
48-
> - `templates/XLS_TEMPLATE.md` — top-level section structure for all XLS types
49-
> - `templates/AMENDMENT_TEMPLATE.md` — Specification section structure for Amendment XLSes (Ledger Entries, Transactions, Permissions, RPCs, and their required table schemas)
50-
>
51-
> When reviewing or authoring a spec, diff the document against the relevant template to catch missing sections, wrong table columns, or incorrect heading numbering.
131+
---
52132

53-
## Key Rules
133+
## Known Gotchas
54134

55-
- **No unfilled placeholders** — `validate_xls_template.py` rejects patterns like `[FieldName]`, `[example value]`, `_[Describe...]`, `0x[XXXX]`, `[r-address]`, `[Yes/No]`, etc.
56-
- **New draft directories** use `XLS-draft-<short-title>/` — the CI bot assigns the number; editors rename before merge.
57-
- **`scripts/_site/` is gitignored** — never commit build output.
58-
- Always run `python scripts/xls_parser.py` after any preamble change; it validates all docs and exits 1 on error.
135+
- **Duplicate XLS numbers**: `xls_parser.py` fails if two folders resolve to the same number. Always use the `XLS-draft-*` naming convention and let CI assign the number.
136+
- **Self-assigned numbers > 95**: the `assign-xls-number.yml` workflow posts a warning comment and blocks the CI if a PR adds a numbered directory (> XLS-0095) without the `has-xls-number` label.
137+
- **Withdrawn XLSes** must include a `withdrawal-reason` field in the preamble or validation fails.
138+
- **Amendment XLSes cannot reach `Final`** until the corresponding rippled PR is merged; `System` XLSes require a merged implementation too.
139+
- **`proposal-from` is required** for all XLSes in the preamble. Missing it causes `validate_xls_preamble` to fail.
140+
- The `build_site.py` script outputs to `scripts/_site/` — this directory is ephemeral and not committed.
141+
- Pre-commit uses pinned SHAs (not tags) for hook repos — update them in `.pre-commit-config.yaml` if upgrading.

0 commit comments

Comments
 (0)