From c8cc0435f8f587c051a7d3253d35b28be3bebeaf Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 13:36:12 +0000 Subject: [PATCH 1/5] plan(#114): initial brief from issue --- plan/planning/brief.md | 118 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 plan/planning/brief.md diff --git a/plan/planning/brief.md b/plan/planning/brief.md new file mode 100644 index 0000000..99fbd82 --- /dev/null +++ b/plan/planning/brief.md @@ -0,0 +1,118 @@ +# Issue #114: Add .editorconfig with project coding conventions + +## Summary + +Add a `.editorconfig` file at the repository root to codify the coding conventions already present in the codebase. +This is a foundation step for subsequent code-style enforcement and does not reformat any existing code. + +The file must reflect observed conventions — not impose new ones — and must not break the build. +Severity levels must be `suggestion` or `warning`, never `error`. + +## What needs to change and why + +Currently the repository has no `.editorconfig`. +Editors and tooling have no machine-readable source of truth for indentation, line endings, charset, or C# style rules. +Adding `.editorconfig` at the root: + +- Gives editors (VS, Rider, VS Code) automatic style feedback without CI enforcement. +- Codifies what is already in the codebase so future contributors follow the same conventions. +- Is a prerequisite for subsequent automated style-enforcement issues. + +No existing file is reformatted as part of this issue. + +## Affected files (confirmed by exploration) + +| File | Change | +|------|--------| +| `.editorconfig` | **New file** — created at repository root | + +No existing source files are modified. +The new `.editorconfig` is picked up automatically by .NET SDK / Roslyn for any file it covers. + +## Conventions observed in the codebase + +These settings must be reflected in `.editorconfig`: + +### General (all files) + +- Charset: `utf-8` +- Line endings: `lf` (enforced by `.gitattributes`; `.editorconfig` should agree) +- Insert final newline: `true` +- Trim trailing whitespace: `true` + +### C# files (`.cs`) + +- Indent style: spaces +- Indent size: 4 +- Namespace style: block-scoped (traditional `namespace Foo { }`) +- `using` directives: outside the namespace block +- `var` usage: consistent with existing code (used where type is apparent, explicit otherwise) +- Private fields: `_camelCase` (underscore prefix + camelCase) +- Public members: PascalCase +- Interfaces: `I` prefix + PascalCase +- Constants / static readonly: PascalCase +- Parameters / local variables: camelCase +- Brace style: opening brace on same line (K&R / Allman — confirm from files) + +### XML / project files (`.csproj`, `.props`, `.targets`) + +- Indent style: spaces +- Indent size: 2 + +### JSON files (`.json`) + +- Indent style: spaces +- Indent size: 2 + +### YAML files (`.yml`, `.yaml`) + +- Indent style: spaces +- Indent size: 2 + +### Markdown files (`.md`) + +- Trim trailing whitespace: `true` +- Insert final newline: `true` + +### Solution files (`.sln`) + +- Indent style: tabs (Visual Studio default — leave as-is or omit) + +## Acceptance criteria + +- [ ] `.editorconfig` file added at repository root +- [ ] Settings reflect the conventions already used in the existing codebase (no new rules invented) +- [ ] All severity levels for C# style rules set to `suggestion` or `warning` — never `error` +- [ ] `dotnet build` succeeds without new errors after the file is added +- [ ] Settings are documented with inline comments where the convention might not be obvious +- [ ] `root = true` is present so the file applies from the repository root + +## Test strategy + +### Build verification + +Run `dotnet build` from the repository root and confirm: + +- Exit code is 0 +- No new errors introduced +- New warnings (if any) are at `suggestion` / `warning` severity only + +### Manual inspection + +- Open a C# file in an editor that respects `.editorconfig` (VS Code / VS / Rider) and confirm style hints appear as expected. +- Verify that the file is valid `.editorconfig` syntax (no parse errors reported by editor tooling). + +### No automated test changes + +No unit tests need to be added or modified. +The `.editorconfig` is tooling configuration, not logic. + +## Risks and open questions + +| Risk / Question | Notes | +|----------------|-------| +| Brace style (K&R vs Allman) | C# conventionally uses Allman (opening brace on new line). The existing code should be confirmed before setting `csharp_new_line_before_open_brace`. | +| `var` preference | The codebase mixes explicit types and `var`; severity must stay at `suggestion` to avoid noisy warnings. | +| Solution file indentation | `.sln` files use tab indentation by Visual Studio convention; either omit `.sln` from `.editorconfig` rules or match tabs to avoid false positives. | +| Severity escalation | Future issues will raise severity to `warning` or `error`; this issue intentionally stays at `suggestion`. Do NOT pre-empt that work here. | +| `dotnet format` | Must NOT be run as part of this issue. Reformatting is a separate subsequent issue. | From f2e6a14c8170a9df4500c88315353bcb42abda77 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 13:39:18 +0000 Subject: [PATCH 2/5] plan(#114): review brief --- plan/{planning => ready}/brief.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename plan/{planning => ready}/brief.md (100%) diff --git a/plan/planning/brief.md b/plan/ready/brief.md similarity index 100% rename from plan/planning/brief.md rename to plan/ready/brief.md From 0db59fda79bcef230f7697f4d93dc251fe2c631c Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 13:43:08 +0000 Subject: [PATCH 3/5] plan(#114): create task breakdown --- plan/ready/task.md | 122 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 plan/ready/task.md diff --git a/plan/ready/task.md b/plan/ready/task.md new file mode 100644 index 0000000..3d8d63d --- /dev/null +++ b/plan/ready/task.md @@ -0,0 +1,122 @@ +# Task Checklist — Issue #114: Add `.editorconfig` + +## Exploration findings + +From codebase inspection: + +- **Brace style**: K&R (opening brace on same line — not Allman) +- **`using` placement**: outside namespace blocks +- **Namespace style**: block-scoped (`namespace Foo { }`) +- **`var` usage**: used where type is apparent from RHS; explicit otherwise +- **Private fields**: `_camelCase` +- **Public members**: PascalCase +- **Interfaces**: `I` prefix + PascalCase +- **Indent — C# files**: 4 spaces +- **Indent — XML/JSON/YAML**: 2 spaces +- **Line endings**: LF (CRLF only for `.cmd`/`.bat`) +- **Solution file**: tabs (Visual Studio default) +- **No `.editorconfig` currently exists** + +--- + +## Tasks + +### 1. Confirm brace style from source files + +- [ ] Read 3–5 representative C# files (e.g. `HdrHistogram/HistogramBase.cs`, `HdrHistogram/Recorder.cs`, `HdrHistogram/HistogramLogWriter.cs`) to confirm K&R brace style throughout. + - **File**: existing source files (read-only) + - **Why**: The brief lists this as an open question; exploration says K&R — confirm before writing the rule. + - **Verify**: The `csharp_new_line_before_open_brace` setting in the final `.editorconfig` matches what is seen. + +### 2. Create `.editorconfig` at repository root + +- [ ] Create `/workspace/repo/.editorconfig` with the following sections, each annotated with inline comments: + + **`[*]` — all files** + - `root = true` + - `charset = utf-8` + - `end_of_line = lf` + - `insert_final_newline = true` + - `trim_trailing_whitespace = true` + + **`[*.cs]` — C# source files** + - `indent_style = space` + - `indent_size = 4` + - Roslyn naming rules: `_camelCase` for private fields (suggestion) + - `csharp_using_directive_placement = outside_namespace:suggestion` + - `csharp_style_namespace_declarations = block_scoped:suggestion` + - `csharp_new_line_before_open_brace = none` (K&R style, confirmed above):suggestion + - `csharp_prefer_var_elsewhere = true:suggestion` + - `csharp_prefer_var_when_type_is_apparent = true:suggestion` + - Naming: PascalCase for public symbols, `I`-prefix for interfaces, `_camelCase` for private fields — all at `suggestion` + + **`[*.{csproj,props,targets,xml}]` — XML/project files** + - `indent_style = space` + - `indent_size = 2` + + **`[*.{json,yml,yaml}]` — JSON and YAML** + - `indent_style = space` + - `indent_size = 2` + + **`[*.md]` — Markdown** + - `trim_trailing_whitespace = true` + - `insert_final_newline = true` + + **`[*.sln]` — Solution files** + - `indent_style = tab` (Visual Studio convention) + + **`[*.{cmd,bat}]` — Windows scripts** + - `end_of_line = crlf` + + - **File**: `/workspace/repo/.editorconfig` (new file) + - **Why**: Core deliverable of issue #114; codifies conventions without reformatting code. + - **Verify**: File exists at repo root; `root = true` is present; all sections listed above are present; every C# severity is `suggestion` or `warning`. + +### 3. Verify all C# severity levels are `suggestion` or `warning` + +- [ ] Grep the new `.editorconfig` for any occurrence of `:error` to confirm none are present. + - **File**: `/workspace/repo/.editorconfig` + - **Why**: Acceptance criterion — severity must never be `error`. + - **Verify**: Zero matches for `:error`. + +### 4. Verify `root = true` is present + +- [ ] Confirm the first non-comment line in `.editorconfig` is `root = true`. + - **File**: `/workspace/repo/.editorconfig` + - **Why**: Acceptance criterion — ensures the file is treated as the root configuration. + - **Verify**: `root = true` appears before any section header. + +### 5. Run `dotnet build` and confirm success + +- [ ] Run `dotnet build` from `/workspace/repo` and check exit code is 0 with no new errors. + - **Why**: Acceptance criterion — the new file must not break the build. + - **Verify**: Build output shows 0 errors; any new diagnostics are at `suggestion` / `warning` level only. + +### 6. Inspect inline comments for non-obvious rules + +- [ ] Read the finished `.editorconfig` and confirm every non-obvious rule (e.g. `_camelCase` naming, `csharp_new_line_before_open_brace`, `csharp_using_directive_placement`) has an explanatory comment. + - **File**: `/workspace/repo/.editorconfig` + - **Why**: Acceptance criterion — "Settings are documented with inline comments where the convention might not be obvious." + - **Verify**: Each Roslyn/C# style rule has at least a brief `#` comment. + +--- + +## Acceptance criteria cross-reference + +| Criterion (from brief) | Covered by task(s) | +|---|---| +| `.editorconfig` file added at repository root | Task 2 | +| Settings reflect conventions already used (no new rules invented) | Tasks 1 + 2 | +| All C# severity levels `suggestion` or `warning` — never `error` | Tasks 2 + 3 | +| `dotnet build` succeeds without new errors | Task 5 | +| Settings documented with inline comments where non-obvious | Tasks 2 + 6 | +| `root = true` is present | Tasks 2 + 4 | + +--- + +## Out of scope (per brief) + +- No existing source files are reformatted. +- No unit tests are added or modified. +- `dotnet format` must NOT be run. +- Severity must NOT be escalated beyond `suggestion`; that is a future issue. From 954101f9a367f0bedc83abeeb3425e9133ca531b Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 13:52:22 +0000 Subject: [PATCH 4/5] feat(#114): implement tasks --- .editorconfig | 125 ++++++++++++++++++++++++++++++++++ plan/{ready => done}/brief.md | 0 plan/{ready => done}/task.md | 22 ++++-- 3 files changed, 141 insertions(+), 6 deletions(-) create mode 100644 .editorconfig rename plan/{ready => done}/brief.md (100%) rename plan/{ready => done}/task.md (79%) diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..d31e55f --- /dev/null +++ b/.editorconfig @@ -0,0 +1,125 @@ +# EditorConfig: https://editorconfig.org +# Root config — stops editors searching parent directories for further .editorconfig files. +root = true + +# ────────────────────────────────────────────── +# All files +# ────────────────────────────────────────────── +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +# ────────────────────────────────────────────── +# C# source files +# ────────────────────────────────────────────── +[*.cs] +indent_style = space +indent_size = 4 + +# --- Using directives --- +# Keep using directives outside the namespace block (Java/traditional C# style). +csharp_using_directive_placement = outside_namespace:suggestion + +# --- Namespace declarations --- +# Use traditional block-scoped namespaces: namespace Foo { } rather than file-scoped. +csharp_style_namespace_declarations = block_scoped:suggestion + +# --- Brace placement --- +# Allman style: opening brace on its own line after the declaration. +# Applies to all constructs (types, methods, control flow, etc.). +csharp_new_line_before_open_brace = all + +# --- var usage --- +# Use var when the type is already obvious from the right-hand side (e.g. new, cast). +csharp_style_var_when_type_is_apparent = true:suggestion +# Use explicit types everywhere else so the reader does not need to infer them. +csharp_style_var_elsewhere = false:suggestion + +# ────────────────────────────────────────────── +# Roslyn naming rules — private fields +# Naming symbols: any private field +# Style: _camelCase prefix +# ────────────────────────────────────────────── + +dotnet_naming_rule.private_fields_should_be_camel_case.symbols = private_fields +dotnet_naming_rule.private_fields_should_be_camel_case.style = camel_case_underscore_prefix +dotnet_naming_rule.private_fields_should_be_camel_case.severity = suggestion + +dotnet_naming_symbols.private_fields.applicable_kinds = field +dotnet_naming_symbols.private_fields.applicable_accessibilities = private +dotnet_naming_symbols.private_fields.required_modifiers = + +dotnet_naming_style.camel_case_underscore_prefix.capitalization = camel_case +dotnet_naming_style.camel_case_underscore_prefix.required_prefix = _ + +# ────────────────────────────────────────────── +# Roslyn naming rules — public members +# Naming symbols: public/internal/protected members (types, methods, properties, events) +# Style: PascalCase +# ────────────────────────────────────────────── + +dotnet_naming_rule.public_members_should_be_pascal_case.symbols = public_members +dotnet_naming_rule.public_members_should_be_pascal_case.style = pascal_case +dotnet_naming_rule.public_members_should_be_pascal_case.severity = suggestion + +dotnet_naming_symbols.public_members.applicable_kinds = class, struct, enum, property, method, event, delegate +dotnet_naming_symbols.public_members.applicable_accessibilities = public, internal, protected, protected_internal + +dotnet_naming_style.pascal_case.capitalization = pascal_case + +# ────────────────────────────────────────────── +# Roslyn naming rules — interfaces +# Naming symbols: interfaces at any accessibility +# Style: PascalCase with I prefix +# ────────────────────────────────────────────── + +dotnet_naming_rule.interfaces_should_be_prefixed_with_i.symbols = interfaces +dotnet_naming_rule.interfaces_should_be_prefixed_with_i.style = i_prefix_pascal_case +dotnet_naming_rule.interfaces_should_be_prefixed_with_i.severity = suggestion + +dotnet_naming_symbols.interfaces.applicable_kinds = interface +dotnet_naming_symbols.interfaces.applicable_accessibilities = * + +dotnet_naming_style.i_prefix_pascal_case.capitalization = pascal_case +dotnet_naming_style.i_prefix_pascal_case.required_prefix = I + +# ────────────────────────────────────────────── +# XML / MSBuild project files +# ────────────────────────────────────────────── +[*.{csproj,props,targets,xml}] +indent_style = space +indent_size = 2 + +# ────────────────────────────────────────────── +# JSON and YAML +# ────────────────────────────────────────────── +[*.{json,yml,yaml}] +indent_style = space +indent_size = 2 + +# ────────────────────────────────────────────── +# Markdown +# Trailing whitespace is meaningful in some Markdown renderers (two trailing +# spaces produce a hard line break), but this project follows the convention +# of trimming it and using blank lines for paragraph breaks instead. +# ────────────────────────────────────────────── +[*.md] +trim_trailing_whitespace = true +insert_final_newline = true + +# ────────────────────────────────────────────── +# Visual Studio solution files +# Visual Studio generates solution files with tab indentation; preserve that +# convention to avoid spurious diffs when the IDE regenerates the file. +# ────────────────────────────────────────────── +[*.sln] +indent_style = tab + +# ────────────────────────────────────────────── +# Windows batch / command scripts +# Windows tools require CRLF line endings in .cmd/.bat files. +# ────────────────────────────────────────────── +[*.{cmd,bat}] +end_of_line = crlf diff --git a/plan/ready/brief.md b/plan/done/brief.md similarity index 100% rename from plan/ready/brief.md rename to plan/done/brief.md diff --git a/plan/ready/task.md b/plan/done/task.md similarity index 79% rename from plan/ready/task.md rename to plan/done/task.md index 3d8d63d..6181c2f 100644 --- a/plan/ready/task.md +++ b/plan/done/task.md @@ -23,14 +23,14 @@ From codebase inspection: ### 1. Confirm brace style from source files -- [ ] Read 3–5 representative C# files (e.g. `HdrHistogram/HistogramBase.cs`, `HdrHistogram/Recorder.cs`, `HdrHistogram/HistogramLogWriter.cs`) to confirm K&R brace style throughout. +- [x] Read 3–5 representative C# files (e.g. `HdrHistogram/HistogramBase.cs`, `HdrHistogram/Recorder.cs`, `HdrHistogram/HistogramLogWriter.cs`) to confirm K&R brace style throughout. - **File**: existing source files (read-only) - **Why**: The brief lists this as an open question; exploration says K&R — confirm before writing the rule. - **Verify**: The `csharp_new_line_before_open_brace` setting in the final `.editorconfig` matches what is seen. ### 2. Create `.editorconfig` at repository root -- [ ] Create `/workspace/repo/.editorconfig` with the following sections, each annotated with inline comments: +- [x] Create `/workspace/repo/.editorconfig` with the following sections, each annotated with inline comments: **`[*]` — all files** - `root = true` @@ -74,27 +74,27 @@ From codebase inspection: ### 3. Verify all C# severity levels are `suggestion` or `warning` -- [ ] Grep the new `.editorconfig` for any occurrence of `:error` to confirm none are present. +- [x] Grep the new `.editorconfig` for any occurrence of `:error` to confirm none are present. - **File**: `/workspace/repo/.editorconfig` - **Why**: Acceptance criterion — severity must never be `error`. - **Verify**: Zero matches for `:error`. ### 4. Verify `root = true` is present -- [ ] Confirm the first non-comment line in `.editorconfig` is `root = true`. +- [x] Confirm the first non-comment line in `.editorconfig` is `root = true`. - **File**: `/workspace/repo/.editorconfig` - **Why**: Acceptance criterion — ensures the file is treated as the root configuration. - **Verify**: `root = true` appears before any section header. ### 5. Run `dotnet build` and confirm success -- [ ] Run `dotnet build` from `/workspace/repo` and check exit code is 0 with no new errors. +- [x] Run `dotnet build` from `/workspace/repo` and check exit code is 0 with no new errors. - **Why**: Acceptance criterion — the new file must not break the build. - **Verify**: Build output shows 0 errors; any new diagnostics are at `suggestion` / `warning` level only. ### 6. Inspect inline comments for non-obvious rules -- [ ] Read the finished `.editorconfig` and confirm every non-obvious rule (e.g. `_camelCase` naming, `csharp_new_line_before_open_brace`, `csharp_using_directive_placement`) has an explanatory comment. +- [x] Read the finished `.editorconfig` and confirm every non-obvious rule (e.g. `_camelCase` naming, `csharp_new_line_before_open_brace`, `csharp_using_directive_placement`) has an explanatory comment. - **File**: `/workspace/repo/.editorconfig` - **Why**: Acceptance criterion — "Settings are documented with inline comments where the convention might not be obvious." - **Verify**: Each Roslyn/C# style rule has at least a brief `#` comment. @@ -114,6 +114,16 @@ From codebase inspection: --- +### 7. Fix brace style setting and var property names + +- [x] Fix two bugs found during code review: + 1. `csharp_new_line_before_open_brace = none` → `= all` with comment corrected to "Allman style" (brace style is Allman — confirmed by reading source files directly, overriding the incorrect initial exploration finding) + 2. `csharp_prefer_var_when_type_is_apparent` → `csharp_style_var_when_type_is_apparent` (correct Roslyn property name) + 3. `csharp_prefer_var_elsewhere` → `csharp_style_var_elsewhere` (correct Roslyn property name) + - **File**: `/workspace/repo/.editorconfig` + - **Why**: Code review identified incorrect brace style value and invalid Roslyn property names that would be silently ignored. + - **Verify**: `grep csharp_new_line_before_open_brace` shows `= all`; property names use `csharp_style_var_*` prefix; `dotnet build` still passes. + ## Out of scope (per brief) - No existing source files are reformatted. From 626a6045b7ab78c2dd4d226965e3e5297000196a Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 13:52:54 +0000 Subject: [PATCH 5/5] feat(#114): complete implementation --- plan/done/brief.md | 118 ---------------------------------------- plan/done/task.md | 132 --------------------------------------------- 2 files changed, 250 deletions(-) delete mode 100644 plan/done/brief.md delete mode 100644 plan/done/task.md diff --git a/plan/done/brief.md b/plan/done/brief.md deleted file mode 100644 index 99fbd82..0000000 --- a/plan/done/brief.md +++ /dev/null @@ -1,118 +0,0 @@ -# Issue #114: Add .editorconfig with project coding conventions - -## Summary - -Add a `.editorconfig` file at the repository root to codify the coding conventions already present in the codebase. -This is a foundation step for subsequent code-style enforcement and does not reformat any existing code. - -The file must reflect observed conventions — not impose new ones — and must not break the build. -Severity levels must be `suggestion` or `warning`, never `error`. - -## What needs to change and why - -Currently the repository has no `.editorconfig`. -Editors and tooling have no machine-readable source of truth for indentation, line endings, charset, or C# style rules. -Adding `.editorconfig` at the root: - -- Gives editors (VS, Rider, VS Code) automatic style feedback without CI enforcement. -- Codifies what is already in the codebase so future contributors follow the same conventions. -- Is a prerequisite for subsequent automated style-enforcement issues. - -No existing file is reformatted as part of this issue. - -## Affected files (confirmed by exploration) - -| File | Change | -|------|--------| -| `.editorconfig` | **New file** — created at repository root | - -No existing source files are modified. -The new `.editorconfig` is picked up automatically by .NET SDK / Roslyn for any file it covers. - -## Conventions observed in the codebase - -These settings must be reflected in `.editorconfig`: - -### General (all files) - -- Charset: `utf-8` -- Line endings: `lf` (enforced by `.gitattributes`; `.editorconfig` should agree) -- Insert final newline: `true` -- Trim trailing whitespace: `true` - -### C# files (`.cs`) - -- Indent style: spaces -- Indent size: 4 -- Namespace style: block-scoped (traditional `namespace Foo { }`) -- `using` directives: outside the namespace block -- `var` usage: consistent with existing code (used where type is apparent, explicit otherwise) -- Private fields: `_camelCase` (underscore prefix + camelCase) -- Public members: PascalCase -- Interfaces: `I` prefix + PascalCase -- Constants / static readonly: PascalCase -- Parameters / local variables: camelCase -- Brace style: opening brace on same line (K&R / Allman — confirm from files) - -### XML / project files (`.csproj`, `.props`, `.targets`) - -- Indent style: spaces -- Indent size: 2 - -### JSON files (`.json`) - -- Indent style: spaces -- Indent size: 2 - -### YAML files (`.yml`, `.yaml`) - -- Indent style: spaces -- Indent size: 2 - -### Markdown files (`.md`) - -- Trim trailing whitespace: `true` -- Insert final newline: `true` - -### Solution files (`.sln`) - -- Indent style: tabs (Visual Studio default — leave as-is or omit) - -## Acceptance criteria - -- [ ] `.editorconfig` file added at repository root -- [ ] Settings reflect the conventions already used in the existing codebase (no new rules invented) -- [ ] All severity levels for C# style rules set to `suggestion` or `warning` — never `error` -- [ ] `dotnet build` succeeds without new errors after the file is added -- [ ] Settings are documented with inline comments where the convention might not be obvious -- [ ] `root = true` is present so the file applies from the repository root - -## Test strategy - -### Build verification - -Run `dotnet build` from the repository root and confirm: - -- Exit code is 0 -- No new errors introduced -- New warnings (if any) are at `suggestion` / `warning` severity only - -### Manual inspection - -- Open a C# file in an editor that respects `.editorconfig` (VS Code / VS / Rider) and confirm style hints appear as expected. -- Verify that the file is valid `.editorconfig` syntax (no parse errors reported by editor tooling). - -### No automated test changes - -No unit tests need to be added or modified. -The `.editorconfig` is tooling configuration, not logic. - -## Risks and open questions - -| Risk / Question | Notes | -|----------------|-------| -| Brace style (K&R vs Allman) | C# conventionally uses Allman (opening brace on new line). The existing code should be confirmed before setting `csharp_new_line_before_open_brace`. | -| `var` preference | The codebase mixes explicit types and `var`; severity must stay at `suggestion` to avoid noisy warnings. | -| Solution file indentation | `.sln` files use tab indentation by Visual Studio convention; either omit `.sln` from `.editorconfig` rules or match tabs to avoid false positives. | -| Severity escalation | Future issues will raise severity to `warning` or `error`; this issue intentionally stays at `suggestion`. Do NOT pre-empt that work here. | -| `dotnet format` | Must NOT be run as part of this issue. Reformatting is a separate subsequent issue. | diff --git a/plan/done/task.md b/plan/done/task.md deleted file mode 100644 index 6181c2f..0000000 --- a/plan/done/task.md +++ /dev/null @@ -1,132 +0,0 @@ -# Task Checklist — Issue #114: Add `.editorconfig` - -## Exploration findings - -From codebase inspection: - -- **Brace style**: K&R (opening brace on same line — not Allman) -- **`using` placement**: outside namespace blocks -- **Namespace style**: block-scoped (`namespace Foo { }`) -- **`var` usage**: used where type is apparent from RHS; explicit otherwise -- **Private fields**: `_camelCase` -- **Public members**: PascalCase -- **Interfaces**: `I` prefix + PascalCase -- **Indent — C# files**: 4 spaces -- **Indent — XML/JSON/YAML**: 2 spaces -- **Line endings**: LF (CRLF only for `.cmd`/`.bat`) -- **Solution file**: tabs (Visual Studio default) -- **No `.editorconfig` currently exists** - ---- - -## Tasks - -### 1. Confirm brace style from source files - -- [x] Read 3–5 representative C# files (e.g. `HdrHistogram/HistogramBase.cs`, `HdrHistogram/Recorder.cs`, `HdrHistogram/HistogramLogWriter.cs`) to confirm K&R brace style throughout. - - **File**: existing source files (read-only) - - **Why**: The brief lists this as an open question; exploration says K&R — confirm before writing the rule. - - **Verify**: The `csharp_new_line_before_open_brace` setting in the final `.editorconfig` matches what is seen. - -### 2. Create `.editorconfig` at repository root - -- [x] Create `/workspace/repo/.editorconfig` with the following sections, each annotated with inline comments: - - **`[*]` — all files** - - `root = true` - - `charset = utf-8` - - `end_of_line = lf` - - `insert_final_newline = true` - - `trim_trailing_whitespace = true` - - **`[*.cs]` — C# source files** - - `indent_style = space` - - `indent_size = 4` - - Roslyn naming rules: `_camelCase` for private fields (suggestion) - - `csharp_using_directive_placement = outside_namespace:suggestion` - - `csharp_style_namespace_declarations = block_scoped:suggestion` - - `csharp_new_line_before_open_brace = none` (K&R style, confirmed above):suggestion - - `csharp_prefer_var_elsewhere = true:suggestion` - - `csharp_prefer_var_when_type_is_apparent = true:suggestion` - - Naming: PascalCase for public symbols, `I`-prefix for interfaces, `_camelCase` for private fields — all at `suggestion` - - **`[*.{csproj,props,targets,xml}]` — XML/project files** - - `indent_style = space` - - `indent_size = 2` - - **`[*.{json,yml,yaml}]` — JSON and YAML** - - `indent_style = space` - - `indent_size = 2` - - **`[*.md]` — Markdown** - - `trim_trailing_whitespace = true` - - `insert_final_newline = true` - - **`[*.sln]` — Solution files** - - `indent_style = tab` (Visual Studio convention) - - **`[*.{cmd,bat}]` — Windows scripts** - - `end_of_line = crlf` - - - **File**: `/workspace/repo/.editorconfig` (new file) - - **Why**: Core deliverable of issue #114; codifies conventions without reformatting code. - - **Verify**: File exists at repo root; `root = true` is present; all sections listed above are present; every C# severity is `suggestion` or `warning`. - -### 3. Verify all C# severity levels are `suggestion` or `warning` - -- [x] Grep the new `.editorconfig` for any occurrence of `:error` to confirm none are present. - - **File**: `/workspace/repo/.editorconfig` - - **Why**: Acceptance criterion — severity must never be `error`. - - **Verify**: Zero matches for `:error`. - -### 4. Verify `root = true` is present - -- [x] Confirm the first non-comment line in `.editorconfig` is `root = true`. - - **File**: `/workspace/repo/.editorconfig` - - **Why**: Acceptance criterion — ensures the file is treated as the root configuration. - - **Verify**: `root = true` appears before any section header. - -### 5. Run `dotnet build` and confirm success - -- [x] Run `dotnet build` from `/workspace/repo` and check exit code is 0 with no new errors. - - **Why**: Acceptance criterion — the new file must not break the build. - - **Verify**: Build output shows 0 errors; any new diagnostics are at `suggestion` / `warning` level only. - -### 6. Inspect inline comments for non-obvious rules - -- [x] Read the finished `.editorconfig` and confirm every non-obvious rule (e.g. `_camelCase` naming, `csharp_new_line_before_open_brace`, `csharp_using_directive_placement`) has an explanatory comment. - - **File**: `/workspace/repo/.editorconfig` - - **Why**: Acceptance criterion — "Settings are documented with inline comments where the convention might not be obvious." - - **Verify**: Each Roslyn/C# style rule has at least a brief `#` comment. - ---- - -## Acceptance criteria cross-reference - -| Criterion (from brief) | Covered by task(s) | -|---|---| -| `.editorconfig` file added at repository root | Task 2 | -| Settings reflect conventions already used (no new rules invented) | Tasks 1 + 2 | -| All C# severity levels `suggestion` or `warning` — never `error` | Tasks 2 + 3 | -| `dotnet build` succeeds without new errors | Task 5 | -| Settings documented with inline comments where non-obvious | Tasks 2 + 6 | -| `root = true` is present | Tasks 2 + 4 | - ---- - -### 7. Fix brace style setting and var property names - -- [x] Fix two bugs found during code review: - 1. `csharp_new_line_before_open_brace = none` → `= all` with comment corrected to "Allman style" (brace style is Allman — confirmed by reading source files directly, overriding the incorrect initial exploration finding) - 2. `csharp_prefer_var_when_type_is_apparent` → `csharp_style_var_when_type_is_apparent` (correct Roslyn property name) - 3. `csharp_prefer_var_elsewhere` → `csharp_style_var_elsewhere` (correct Roslyn property name) - - **File**: `/workspace/repo/.editorconfig` - - **Why**: Code review identified incorrect brace style value and invalid Roslyn property names that would be silently ignored. - - **Verify**: `grep csharp_new_line_before_open_brace` shows `= all`; property names use `csharp_style_var_*` prefix; `dotnet build` still passes. - -## Out of scope (per brief) - -- No existing source files are reformatted. -- No unit tests are added or modified. -- `dotnet format` must NOT be run. -- Severity must NOT be escalated beyond `suggestion`; that is a future issue.