Skip to main content

​
1. Purpose

This LIP provides authoring conventions for LIP documents. It is non-normative guidance describing the register, structure, normative language, and style expected of LIP content. LIP-1 defines the LIP format (frontmatter fields, status lifecycle, submission mechanics); LIP-3 describes how to write within that format well. Authors are not required to follow LIP-3 strictly. The editor uses LIP-3 as a reference during review and may request revisions when submissions deviate from the conventions in ways that affect clarity or consistency. Significant deviations should have explicit justification. LIP-3 is modeled on similar authoring guidance used by established proposal processes: PEP-7 (Python style guide for C code in PEPs) and PEP-8 (style guide for Python code) demonstrate the pattern of separate documents codifying style beyond format mechanics. This LIP serves the analogous role for LLMO.

​
2. Register

LIPs are written in an RFC-editor register: declarative, specific, and stripped of promotional language. Declarative. LIPs state what is, what must be, or what will happen. They avoid hedging language (“this might be useful”), marketing language (“a revolutionary approach”), and conversational asides. A sentence is declarative when a reader can evaluate it for truth without guessing the author’s intent. Specific. LIPs prefer concrete references over abstract claims. “A DNS TXT record at _llmo-lip.<domain> with value llmo-lip=<number> nonce=<nonce>” is specific. “A mechanism to verify domain control” is abstract. The specific form permits implementation; the abstract form does not. No promotional language. LIPs do not describe the spec or its mechanisms as innovative, elegant, powerful, simple, or any other subjective superlative. The reader evaluates the content on its merits, not on the author’s characterization of it. Examples from LIP-1 and LIP-2:
  • LIP-1 Section 7 states anti-flood provisions declaratively (“DNS TXT proof-of-control at submission is the primary filter”) rather than evaluatively (“Our innovative anti-flood mechanism…”).
  • LIP-2 Section 5 specifies rename automation behavior in operational steps (“Parse the LIP number from the PR description”) rather than descriptively (“The automation handles everything seamlessly”).

​
3. Normative language

LIPs use RFC 2119 / RFC 8174 normative terms (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) when describing requirements. Normative terms are used sparingly and only where the requirement is meaningful for conformance. When to use normative terms:
  • Requirements that implementations or authors must satisfy for conformance
  • Constraints whose violation produces a specific failure mode
When not to use normative terms:
  • Process descriptions that are descriptive rather than required (“The editor reviews the PR” rather than “The editor MUST review the PR”)
  • Informational or advisory content
Case sensitivity: Normative terms are written in uppercase to distinguish them from the common English words (“must”, “should”, etc.). A LIP using “must” in lowercase is describing; a LIP using “MUST” is prescribing. Extension claim types and normative terms: Standards Track LIPs proposing new or modified claim types typically use normative terms to specify claim validity rules, consumer behavior, and producer obligations. Process LIPs use them more rarely, since process descriptions are mostly operational.

​
4. Structure

LIP bodies follow a common section structure, adapted to the LIP’s type. Not all sections are required for every LIP; authors include sections that serve their proposal. Sections common to most LIPs:
  1. Purpose or What this LIP does. Short paragraph stating what the LIP establishes, amends, or describes. Answers “why does this LIP exist?” in two or three sentences.
  2. Substantive content. The body of the LIP, organized into numbered sections. Content varies by LIP type:
    • Standards Track: claim type definition, normative requirements, validity rules
    • Process: mechanism specification, operational steps, role definitions
    • Informational: advisory guidance, conventions, reference material
  3. Backwards compatibility. How the LIP affects existing implementations, existing published documents, and existing LIPs. Standards Track LIPs describe consumer impact; Process LIPs describe whether they break existing LIP workflows; Informational LIPs usually note that they introduce no normative changes.
  4. Prior art. Relevant precedents from other specification processes (BIPs, PEPs, RFCs, W3C specs, IETF drafts) or from LLMO’s own history. Prior art citations ground the LIP in established practice and make adaptations explicit.
Sections specific to certain LIP types:
  • Reference implementation. For LIPs that specify tooling, automation, or infrastructure. Describes LLMO’s current deployment without prescribing it as the only valid implementation. LIP-2 Section 10 demonstrates this pattern.
  • Appendix. For byte-exact amendment text, extended examples, or supporting material that would interrupt the main body’s flow.
Section numbering: top-level sections are numbered (1, 2, 3). Subsections use decimal notation (3.1, 3.2) when hierarchy aids comprehension. Deep nesting (3.1.1.1) should be avoided; if a LIP needs that much nesting, it likely needs to be split.

​
5. Length

LIPs should be as long as necessary and no longer. There is no strict upper bound, but three rules of thumb:
  • Informational LIPs typically run 200 to 500 lines. Longer if they compile extensive reference material.
  • Process LIPs typically run 300 to 600 lines. Longer if they amend multiple sections of LIP-1 or introduce substantial new mechanisms.
  • Standards Track LIPs vary most. Extension claim type proposals may be as short as 100 lines for simple claims. Core claim type proposals affecting existing normative text may run longer.
When a LIP exceeds these ranges, the author should consider whether the scope could be split across multiple LIPs. When a LIP is significantly shorter, the author should verify that all required sections (purpose, substantive content, backwards compatibility, prior art) are adequately addressed.

​
6. Project-wide style rules

LLMO enforces several style rules across all repository content, including LIPs: No em dashes. LIPs use commas, parentheses, colons, or separate sentences in place of em dashes (U+2014) or en dashes (U+2013). This rule applies repository-wide and is enforced by convention; LIPs that introduce em dashes will be flagged during editor review. No marketing language. Specific to LIPs, the RFC-editor register described in Section 2 prohibits promotional terms (“innovative,” “seamless,” “powerful,” etc.). Conventional commit style. Commits associated with LIPs use conventional commit prefixes (feat(spec):, docs(spec):, fix(spec):). This convention is enforced repository-wide; see CONTRIBUTING.md. DCO sign-off. All commits to the LLMO repository require DCO sign-off. This is enforced at the repository level and applies to LIP-related commits.

​
7. Citations and external references

LIPs cite external references (standards documents, prior art, tools) with full context, not bare URLs. Formal specifications: cited by their standard identifier (e.g., “RFC 2119”, “BIP-2”, “PEP-1”) with title and author when first introduced. Subsequent references may use the identifier alone. Tools and platforms: named explicitly when part of the reference implementation. The behavioral specification and the reference implementation are separable (LIP-2 demonstrates this pattern in Sections 5 and 10); citations in the reference implementation section may name specific tools, while citations in the behavioral specification should not. External URLs: used when the citation target is not a formally identified standard. URLs are permitted but should be stable. Citations to volatile sources (blog posts, Twitter threads) are discouraged.

​
8. Prior art conventions

Include a Prior art section when your LIP proposes a new mechanism, convention, or process. Cite relevant precedents (BIPs, PEPs, RFCs, W3C specs, or LLMO’s own prior LIPs), explain your adaptations, and justify deviations. Avoid tangentially related citations; if a precedent does not meaningfully inform your proposal, omit it.

​
9. Self-consistency

A LIP should demonstrate the conventions it describes. LIP-3 is an Informational LIP; its register, structure, and citations should all match what Sections 2 through 8 prescribe. Authors drafting a LIP can use LIP-3 as a checklist:
  • Is the register declarative and specific?
  • Are normative terms used appropriately and in uppercase?
  • Are the common sections present?
  • Is the length appropriate for the LIP type?
  • Are em dashes absent?
  • Are external references cited with context?
  • Is prior art described?
A LIP that fails several of these checks may need revision before editor review.

​
10. Revisions to this LIP

Authoring conventions evolve as the LIP corpus grows. When LIP-3 is superseded by a later Informational LIP (e.g., LIP-N with updated conventions), LIP-3 transitions to Superseded status per LIP-1 Section 3, and the replacing LIP becomes the active authoring guide. Minor revisions to LIP-3 (clarifications, typo fixes) may be made via editorial revisions per the governance page’s editorial policy. Substantive changes (new sections, changed conventions) require a superseding LIP.

​
11. Prior art

PEP-1 defines the Python Enhancement Proposal process; PEP-7 and PEP-8 provide style guides for C code in PEPs and for Python code, respectively. LLMO adapts the pattern of separating format mechanics (in the main process LIP) from authoring conventions (in a dedicated style LIP). BIP-2 defines the current Bitcoin Improvement Proposal process and includes some format guidance inline. LLMO’s choice to separate authoring conventions into their own LIP follows PEP more closely than BIP, on the view that authoring guidance benefits from a dedicated document it can evolve within. RFC 2119 and RFC 8174 define normative language conventions used across IETF specifications. LIP-3 Section 3 references these directly for normative term usage in LIPs. LIP-2 Section 10 demonstrates the behavioral-specification-versus-reference-implementation pattern that LIP-3 Section 4 describes as appropriate for LIPs specifying tooling or automation.