From de3554706326aa49947e43e92ceb2829c6cba935 Mon Sep 17 00:00:00 2001 From: Henry Grech-Cini Date: Sat, 14 Nov 2026 13:35:47 +0000 Subject: [PATCH] Published unsigned: the gate does not ask this graph for signatures Since throughline 5.1 tl check --strict fails on every item no person has signed. This standard is published for others to use and is not signed, so the rule unratified is turned off here, with the reason beside it; every other rule stays on. docs/spec.md is regenerated: the status each item is shown in had gone stale behind the failing check. Co-Authored-By: Claude Fable 5.2 --- docs/spec.md | 126 +++++++++++++++++++++++------------------------ throughline.toml | 6 +++ 2 files changed, 69 insertions(+), 63 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index c58f2d1..d6eb99c 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -15,7 +15,7 @@ It carries ## Purpose -**INT-0001 — Java is written in one consistent, readable, maintainable style** — `intent`, status `approved` +**INT-0001 — Java is written in one consistent, readable, maintainable style** — `intent`, status `proposed` > The Google Java Style Guide exists so that Java across a large codebase reads as though written by one author: consistent source structure, formatting, naming and programming practices, so that any engineer can read and change code they did not write, and so that mechanical style questions are settled once rather than argued in every review. @@ -25,7 +25,7 @@ It carries ## Source File Basics -**UR-0001 — Source File Basics** — `user_requirement`, status `approved` +**UR-0001 — Source File Basics** — `user_requirement`, status `proposed` > Rules governing a source file's name, encoding, whitespace and escape sequences. @@ -37,17 +37,17 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0001 | system_requirement | approved | Name the file after its top-level class | -| SR-0002 | system_requirement | approved | Encode source files in UTF-8 | -| SR-0003 | system_requirement | approved | Use only the ASCII space and never tabs for whitespace | -| SR-0004 | system_requirement | approved | Use special escape sequences over numeric escapes | -| SR-0005 | system_requirement | approved | Choose actual character or Unicode escape for readability | +| SR-0001 | system_requirement | proposed | Name the file after its top-level class | +| SR-0002 | system_requirement | proposed | Encode source files in UTF-8 | +| SR-0003 | system_requirement | proposed | Use only the ASCII space and never tabs for whitespace | +| SR-0004 | system_requirement | proposed | Use special escape sequences over numeric escapes | +| SR-0005 | system_requirement | proposed | Choose actual character or Unicode escape for readability | ## Source File Structure -**UR-0002 — Source File Structure** — `user_requirement`, status `approved` +**UR-0002 — Source File Structure** — `user_requirement`, status `proposed` > Rules governing the order of a file's contents, its package and import statements and its top-level class. @@ -59,21 +59,21 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0006 | system_requirement | approved | Put license or copyright information first | -| SR-0007 | system_requirement | approved | Give every file a non-wrapped package declaration | -| SR-0008 | system_requirement | approved | Never use wildcard imports | -| SR-0009 | system_requirement | approved | Do not line-wrap import statements | -| SR-0010 | system_requirement | approved | Order imports as static then non-static, ASCII-sorted | -| SR-0011 | system_requirement | approved | Import static nested classes with normal imports | -| SR-0012 | system_requirement | approved | Keep exactly one top-level class per file | -| SR-0013 | system_requirement | approved | Order class contents by a logical, explicable order | -| SR-0014 | system_requirement | approved | Keep overloaded methods in one contiguous group | +| SR-0006 | system_requirement | proposed | Put license or copyright information first | +| SR-0007 | system_requirement | proposed | Give every file a non-wrapped package declaration | +| SR-0008 | system_requirement | proposed | Never use wildcard imports | +| SR-0009 | system_requirement | proposed | Do not line-wrap import statements | +| SR-0010 | system_requirement | proposed | Order imports as static then non-static, ASCII-sorted | +| SR-0011 | system_requirement | proposed | Import static nested classes with normal imports | +| SR-0012 | system_requirement | proposed | Keep exactly one top-level class per file | +| SR-0013 | system_requirement | proposed | Order class contents by a logical, explicable order | +| SR-0014 | system_requirement | proposed | Keep overloaded methods in one contiguous group | ## Formatting — Braces and Blocks -**UR-0003 — Formatting — Braces and Blocks** — `user_requirement`, status `approved` +**UR-0003 — Formatting — Braces and Blocks** — `user_requirement`, status `proposed` > Rules governing braces, block indentation, statements per line and the column limit. @@ -85,18 +85,18 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0015 | system_requirement | approved | Always brace if, else, for, do and while | -| SR-0016 | system_requirement | approved | Format nonempty blocks in K&R style | -| SR-0017 | system_requirement | approved | Only close an empty block concisely when it stands alone | -| SR-0018 | system_requirement | approved | Indent each new block by two spaces | -| SR-0019 | system_requirement | approved | Follow each statement with a line break | -| SR-0020 | system_requirement | approved | Keep lines within the 100-character column limit | +| SR-0015 | system_requirement | proposed | Always brace if, else, for, do and while | +| SR-0016 | system_requirement | proposed | Format nonempty blocks in K&R style | +| SR-0017 | system_requirement | proposed | Only close an empty block concisely when it stands alone | +| SR-0018 | system_requirement | proposed | Indent each new block by two spaces | +| SR-0019 | system_requirement | proposed | Follow each statement with a line break | +| SR-0020 | system_requirement | proposed | Keep lines within the 100-character column limit | ## Formatting — Whitespace and Wrapping -**UR-0004 — Formatting — Whitespace and Wrapping** — `user_requirement`, status `approved` +**UR-0004 — Formatting — Whitespace and Wrapping** — `user_requirement`, status `proposed` > Rules governing line-wrapping, vertical and horizontal whitespace, alignment and grouping parentheses. @@ -108,18 +108,18 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0021 | system_requirement | approved | Break lines at the highest syntactic level | -| SR-0022 | system_requirement | approved | Indent continuation lines at least four spaces | -| SR-0023 | system_requirement | approved | Separate class members with a single blank line | -| SR-0024 | system_requirement | approved | Use single ASCII spaces for horizontal separation | -| SR-0025 | system_requirement | approved | Do not require horizontal alignment | -| SR-0026 | system_requirement | approved | Add grouping parentheses unless there is no ambiguity | +| SR-0021 | system_requirement | proposed | Break lines at the highest syntactic level | +| SR-0022 | system_requirement | proposed | Indent continuation lines at least four spaces | +| SR-0023 | system_requirement | proposed | Separate class members with a single blank line | +| SR-0024 | system_requirement | proposed | Use single ASCII spaces for horizontal separation | +| SR-0025 | system_requirement | proposed | Do not require horizontal alignment | +| SR-0026 | system_requirement | proposed | Add grouping parentheses unless there is no ambiguity | ## Formatting — Specific Constructs -**UR-0005 — Formatting — Specific Constructs** — `user_requirement`, status `approved` +**UR-0005 — Formatting — Specific Constructs** — `user_requirement`, status `proposed` > Rules governing enums, variable and array declarations, switch statements, annotations, comments, modifiers and literals. @@ -131,20 +131,20 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0027 | system_requirement | approved | Format an enum class like other classes | -| SR-0028 | system_requirement | approved | Declare only one variable per declaration | -| SR-0029 | system_requirement | approved | Put array brackets on the type, not the variable | -| SR-0030 | system_requirement | approved | Terminate or comment every switch statement group | -| SR-0031 | system_requirement | approved | Place each type-level annotation on its own line | -| SR-0032 | system_requirement | approved | Indent block comments with the surrounding code | -| SR-0033 | system_requirement | approved | Order modifiers as recommended by the language specification | -| SR-0034 | system_requirement | approved | Suffix long literals with an uppercase L | +| SR-0027 | system_requirement | proposed | Format an enum class like other classes | +| SR-0028 | system_requirement | proposed | Declare only one variable per declaration | +| SR-0029 | system_requirement | proposed | Put array brackets on the type, not the variable | +| SR-0030 | system_requirement | proposed | Terminate or comment every switch statement group | +| SR-0031 | system_requirement | proposed | Place each type-level annotation on its own line | +| SR-0032 | system_requirement | proposed | Indent block comments with the surrounding code | +| SR-0033 | system_requirement | proposed | Order modifiers as recommended by the language specification | +| SR-0034 | system_requirement | proposed | Suffix long literals with an uppercase L | ## Naming -**UR-0006 — Naming** — `user_requirement`, status `approved` +**UR-0006 — Naming** — `user_requirement`, status `proposed` > Rules governing the characters, casing and choice of identifiers by kind. @@ -156,23 +156,23 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0035 | system_requirement | approved | Use only ASCII letters, digits and permitted underscores in identifiers | -| SR-0036 | system_requirement | approved | Do not use special prefixes or suffixes on identifiers | -| SR-0037 | system_requirement | approved | Name packages in lowercase with no underscores | -| SR-0038 | system_requirement | approved | Name classes in UpperCamelCase as nouns | -| SR-0039 | system_requirement | approved | Name methods in lowerCamelCase as verbs | -| SR-0040 | system_requirement | approved | Name constants in UPPER_SNAKE_CASE | -| SR-0041 | system_requirement | approved | Name non-constant fields in lowerCamelCase | -| SR-0042 | system_requirement | approved | Name parameters in lowerCamelCase and avoid one-character public names | -| SR-0043 | system_requirement | approved | Name local variables in lowerCamelCase, never as constants | -| SR-0044 | system_requirement | approved | Name type variables in one of the two accepted styles | -| SR-0045 | system_requirement | approved | Derive camel case by the defined algorithm | +| SR-0035 | system_requirement | proposed | Use only ASCII letters, digits and permitted underscores in identifiers | +| SR-0036 | system_requirement | proposed | Do not use special prefixes or suffixes on identifiers | +| SR-0037 | system_requirement | proposed | Name packages in lowercase with no underscores | +| SR-0038 | system_requirement | proposed | Name classes in UpperCamelCase as nouns | +| SR-0039 | system_requirement | proposed | Name methods in lowerCamelCase as verbs | +| SR-0040 | system_requirement | proposed | Name constants in UPPER_SNAKE_CASE | +| SR-0041 | system_requirement | proposed | Name non-constant fields in lowerCamelCase | +| SR-0042 | system_requirement | proposed | Name parameters in lowerCamelCase and avoid one-character public names | +| SR-0043 | system_requirement | proposed | Name local variables in lowerCamelCase, never as constants | +| SR-0044 | system_requirement | proposed | Name type variables in one of the two accepted styles | +| SR-0045 | system_requirement | proposed | Derive camel case by the defined algorithm | ## Programming Practices -**UR-0007 — Programming Practices** — `user_requirement`, status `approved` +**UR-0007 — Programming Practices** — `user_requirement`, status `proposed` > Rules governing @Override, caught exceptions, static-member access and finalizers. @@ -184,16 +184,16 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0046 | system_requirement | approved | Mark every legal override with @Override | -| SR-0047 | system_requirement | approved | Never silently ignore a caught exception | -| SR-0048 | system_requirement | approved | Qualify a static member through its class | -| SR-0049 | system_requirement | approved | Do not override or use finalizers | +| SR-0046 | system_requirement | proposed | Mark every legal override with @Override | +| SR-0047 | system_requirement | proposed | Never silently ignore a caught exception | +| SR-0048 | system_requirement | proposed | Qualify a static member through its class | +| SR-0049 | system_requirement | proposed | Do not override or use finalizers | ## Javadoc -**UR-0008 — Javadoc** — `user_requirement`, status `approved` +**UR-0008 — Javadoc** — `user_requirement`, status `proposed` > Rules governing the formatting, summary and placement of Javadoc. @@ -205,10 +205,10 @@ It carries | UID | Type | Status | Title | |---|---|---|---| -| SR-0050 | system_requirement | approved | Use the correct Javadoc block form | -| SR-0051 | system_requirement | approved | Separate Javadoc paragraphs with a p tag | -| SR-0052 | system_requirement | approved | Order Javadoc block tags and never leave them empty | -| SR-0053 | system_requirement | approved | Open Javadoc with a summary fragment | -| SR-0054 | system_requirement | approved | Document every visible class and member with the stated exceptions | +| SR-0050 | system_requirement | proposed | Use the correct Javadoc block form | +| SR-0051 | system_requirement | proposed | Separate Javadoc paragraphs with a p tag | +| SR-0052 | system_requirement | proposed | Order Javadoc block tags and never leave them empty | +| SR-0053 | system_requirement | proposed | Open Javadoc with a summary fragment | +| SR-0054 | system_requirement | proposed | Document every visible class and member with the stated exceptions | diff --git a/throughline.toml b/throughline.toml index 54fe900..8cd2c2a 100644 --- a/throughline.toml +++ b/throughline.toml @@ -60,3 +60,9 @@ ratified = "ratified" invalidated = "rejected" suspect = "suspect" tombstone = "deleted" + +[rules] +# This graph is published unsigned: its items are offered as they stand and are +# not ratified by a named person, so the gate does not ask for signatures here +# (the rule `unratified`). Every other rule stays on. +unratified = "off"