# Comment, review, and file errata

> Discussions versus Issues versus PRs, RFC #1 errata label, two-editor review, RFC 2119 and compatibility statements, and decision-log recording.

- Repository: g2tf-org/g2tf-standards
- GitHub: https://github.com/g2tf-org/g2tf-standards
- Human docs: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff
- Complete Markdown: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff/llms-full.txt

## Source Files

- `CONTRIBUTING.md`
- `GOVERNANCE.md`
- `rfcs/README.md`
- `README.md`
- `NOTICE.md`

---

---
title: "Comment, review, and file errata"
description: "Discussions versus Issues versus PRs, RFC #1 errata label, two-editor review, RFC 2119 and compatibility statements, and decision-log recording."
---

Commenting on Grid 2 happens in this repository through the `CONTRIBUTING.md` comment cycle: GitHub Discussions for open questions and alternatives, Issues for concrete defects (including RFC #1 errata), and pull requests against `specs/`, `members/`, and `architecture/`. RFCs under `rfcs/` are never edited after publication. The only published RFC is `rfcs/grid-2-rfc-1.pdf` (RFC #1, August 2026).

<Info>
Participation is open to individuals. Organizational affiliation confers no extra standing. Submitting an Issue, Discussion post, or PR licenses specification text under CC BY 4.0 (`NOTICE.md`) and may be incorporated into G2TF publications with attribution.
</Info>

## Choose a channel

| Channel | Use for | Do not use for |
|---|---|---|
| GitHub Discussions | Technical questions, design alternatives, implementation reports (Phase 0 shadow mode and later) | Filing a concrete defect or proposing replaceable spec text |
| Issues | Ambiguities, contradictions, missing normative requirements, errata against RFC #1 | Open design exploration |
| Pull requests | Proposed text against `specs/`, `members/`, or `architecture/` | Patching `rfcs/` |
| G2TF WhatsApp Community | Cross-organization news and policy debate | Normative decisions or archival rationale |

```mermaid
flowchart TD
  intent["Incoming comment"] --> q{"What is it?"}
  q -->|"Question, alternative, or implementation report"| disc["GitHub Discussions"]
  q -->|"Defect, contradiction, or missing MUST"| issue["GitHub Issue"]
  q -->|"Replacement spec text"| pr["Pull request"]
  q -->|"News or policy debate"| wa["WhatsApp Community"]
  issue --> errata{"Against RFC #1?"}
  errata -->|Yes| label["Label errata"]
  errata -->|No| living["Track against living file"]
  disc --> consensus["Editor summarizes rough consensus"]
  consensus --> pr
  label --> pr
  living --> pr
  pr --> review["Two spec-editor reviews"]
  review --> log["Decision log in GOVERNANCE.md"]
```

Living files stay the correction surface. `rfcs/README.md` states RFCs are immutable archival publications; corrections are Issues labeled `errata` and resolved in the living specs.

## Discussion categories

Discussions are organized around the technical open-question areas called out in RFC #1:

| Category | Scope in this repo |
|---|---|
| **Commercial terms** | Enforcement of flexible capabilities, limits on differential service classes, congestion-solving investment, rate-structure impacts. Specs point here (for example DESP class-policy limits stay in the domain agreement). |
| **Reliability assurance** | Coincidental load shedding, materialization of flexibility commitments at scale, compliance incentives. Failsafe open items (coincidental-fallback stability) point here. |
| **Engineering** | Headroom for coincident swings, cybersecurity / NERC CIP, standardization of transmission-owner input signals. G2P security and intra-interval timing open items point here. |

Alignment work with IEEE 2030.5 and related standards is also tracked in Discussions (`GOVERNANCE.md`). Spec files already mark open items with `*(Open: …)*` or `Discussion: …`; file those as Discussions, not as errata.

## File RFC #1 errata

RFC #1 is `rfcs/grid-2-rfc-1.pdf`. The PDF is not revised. The `errata` label is the only issue label defined in this repository.

<Steps>
  <Step title="Confirm it is errata, not a design change">
    Use `errata` when RFC #1 is wrong, internally inconsistent, or contradicts a living file that already captures the intended rule. Use a Discussion when RFC #1 left a question open (naming, timing budget, class policy, CIP mapping).
  </Step>
  <Step title="Open an Issue labeled errata">
    State the RFC section or figure, quote the incorrect or ambiguous sentence, and name the living file that should absorb the fix (`specs/g2p/spec.md`, `specs/gcap/spec.md`, `specs/desp/spec.md`, a file under `members/`, or `architecture/`).
  </Step>
  <Step title="Resolve in living specs, not in rfcs/">
    Open a PR against the living file. Do not submit a PDF or `rfcs/` patch. After merge, the RFC stays as published; implementers follow the living text.
  </Step>
</Steps>

<Warning>
There is no in-repo issue template and no other documented label set. Do not invent labels. If the defect is only in a living Draft file and does not claim RFC #1 is wrong, skip `errata` and file a normal Issue.
</Warning>

## Comment cycle

<Steps>
  <Step title="Raise">
    Open a Discussion (question or alternative) or an Issue (defect). Implementation experience from Phase 0 shadow mode and later also starts as a Discussion.
  </Step>
  <Step title="Converge">
    Editors summarize positions. When a direction has rough consensus, an editor or the proposer opens a PR with spec text.
  </Step>
  <Step title="Review">
    PRs against normative documents require review by **two spec editors**. Normative changes MUST use RFC 2119 keywords and MUST state compatibility impact.
  </Step>
  <Step title="Record">
    Merged decisions are logged in the `GOVERNANCE.md` decision log with a one-paragraph rationale and links to the originating thread. The responsible editor judges rough consensus; there is no vote.
  </Step>
  <Step title="Run">
    Implementations report experience back via Discussions. Running code informs the next revision.
  </Step>
</Steps>

Each normative document lists editors in its header. Current headers still read **Editors:** `TBD`. Until named editors appear, treat two-editor review as a merge gate on the PR, not as a named-person roster.

## Normative PR requirements

### What is normative

| Path | Status today | Keywords |
|---|---|---|
| `specs/g2p/spec.md`, `specs/gcap/spec.md`, `specs/desp/spec.md` | `Status: Draft — seeking input`, `Version: 26.0-draft` | RFC 2119 / RFC 8174 apply |
| `members/use.md`, `members/buffer.md`, `members/source.md`, `members/allocator.md` | `Status: Draft — seeking input` | RFC 2119 / RFC 8174 apply |
| `architecture/` files **not** marked `Status: Informative` | `Status: Draft — seeking input` | RFC 2119 / RFC 8174 apply |
| `architecture/design-principles.md` | `Status: Informative` | Avoid RFC 2119 keywords |
| `rfcs/` | Published, immutable | Corrections via `errata` Issues only |

Normative files are those under `specs/`, `members/`, and `architecture/` that do **not** carry `Status: Informative`. Allowed status header values:

- `Status: Draft — seeking input`
- `Status: Proposed`
- `Status: Stable (vXX.Y)`

### RFC 2119

Normative PRs use only **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY**, interpreted as in IETF RFC 2119 / RFC 8174. Living specs already open with:

```text
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 / RFC 8174.
```

Informative documents must not introduce those keywords as requirements.

### Compatibility statement

Every normative PR states its compatibility impact in the PR description. `GOVERNANCE.md` additionally requires a compatibility statement for changes to **Stable** documents (`Status: Stable (vXX.Y)`). Protocols version independently on a **YY.N** line (current line **26.x**; first 2026 release is `26.0`). The README compatibility matrix is not published yet; until it exists, the PR statement is the only required impact record.

At Draft seeking-input maturity, treat the statement as an explicit claim, for example:

- No wire or semantic change (editorial, errata wording, header-only).
- Additive open-item fill that existing Draft implementations can ignore.
- Breaking change to a MUST / MUST NOT (call it out; do not silently rewrite).

### Reviewable diffs

Prefer one sentence per line for new or substantially revised normative text. That is a review convention, not a protocol rule.

## Decision log

The log lives in `GOVERNANCE.md` under **Decision log**. Columns:

| Column | Required content |
|---|---|
| Date | Month or day of the merge / publication |
| Decision | One-line outcome |
| Rationale | One paragraph; record sustained objections even when overruled |
| Thread | Link to the originating Discussion, Issue, or PR |

Current entry:

| Date | Decision | Rationale | Thread |
|---|---|---|---|
| 2026-08 | Publish RFC #1; decompose into living specs (this repo structure) | Separate immutable narrative from evolving normative text; give the community focused surfaces for comment | — |

<Note>
Rough consensus is not unanimity. The responsible editor records that objections were considered and either addressed or explicitly overruled. Overruled objections still go in the log.
</Note>

The Task Force, not individual editors, resolves cross-document conflicts, appoints editors, sets milestone dates, and approves publication of new RFCs.

## License and acknowledgment on comments

| Contribution kind | License |
|---|---|
| Specification text (Issue, Discussion, or PR) | CC BY 4.0; may be incorporated into G2TF publications |
| Code in this repository | Apache-2.0 (`LICENSE-CODE`) |

Substantive contributors are acknowledged in subsequent RFC publications, following RFC #1's acknowledgments section. Neither license grants trademark rights in "Grid 2.0"™, "G2TF"™, "G2P"™, "GCAP"™, or "DESP"™.

## Common misroutes

| Symptom | Fix |
|---|---|
| PR edits `rfcs/grid-2-rfc-1.pdf` or `rfcs/README.md` to "correct" RFC #1 | Close the PR. File an `errata` Issue and patch the living spec. |
| Discussion used for a contradiction between two MUSTS | Convert to an Issue. Discussions do not close defects. |
| Issue used for "should class count be extensible?" | Move to Discussion: Commercial terms (already flagged in DESP). |
| Normative PR with no MUST/MAY and no compatibility sentence | Request changes; two-editor review cannot complete. |
| Informative PR (`Status: Informative`) that adds MUST | Strip keywords or move the text into a normative file. |
| Merge without a decision-log row | Add the row before considering the cycle complete. |

## Next

<CardGroup>
  <Card title="Contributing" href="/contributing">
    Open individual participation, writing conventions, and Phase 0 implementation reports.
  </Card>
  <Card title="Document lifecycle" href="/document-lifecycle">
    Draft → Proposed → Stable → RFC, YY.N versions, and when a compatibility statement is mandatory.
  </Card>
  <Card title="How to read the specs" href="/how-to-read-the-specs">
    Status headers, RFC 2119 as a reader, living files versus immutable RFCs.
  </Card>
  <Card title="Governance and licenses" href="/governance">
    Editor, contributor, and Task Force roles; rough consensus; CC BY 4.0 and Apache-2.0.
  </Card>
</CardGroup>