From 9e06420ceb10c44eaad838c23985a1c1b39d98f7 Mon Sep 17 00:00:00 2001 From: Matthew Parker Date: Sat, 2 May 2026 03:55:26 +0100 Subject: [PATCH 1/3] Refresh README and broaden CI detection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrote README to refresh structure and add NuGet badges, a Contents section, clearer package guidance (PinguApps.RazorStyle and PinguApps.RazorStyle.Cli), Build Integration and CLI usage docs, and expanded rule descriptions for RS0001–RS0003. Broadened CI detection guidance so ContinuousIntegrationBuild is documented to auto-enable for GitHub Actions, Azure DevOps (TF_BUILD), generic CI=true, TeamCity, and Jenkins. Added .diary/docs-refresh.md capturing the session log and next actions. No production or test code was changed; this commit is purely documentation and build guidance updates. --- .diary/docs-refresh.md | 17 +++++ README.md | 139 +++++++++++++++++++++++++---------------- 2 files changed, 101 insertions(+), 55 deletions(-) create mode 100644 .diary/docs-refresh.md diff --git a/.diary/docs-refresh.md b/.diary/docs-refresh.md new file mode 100644 index 0000000..0330b07 --- /dev/null +++ b/.diary/docs-refresh.md @@ -0,0 +1,17 @@ +## Rolling state +- Goal: Refresh README structure and CI/build package guidance for RazorStyle. +- Current plan: Complete README refresh and broaden repo CI detection. +- Open questions/risks: Badge rendering depends on shields.io and NuGet package metadata availability. +- Next actions: Review final README in rendered Markdown if desired. +- Key paths: README.md, Directory.Build.props + +## Session log +### 2026-05-02 03:22 +01:00 (feature/docs-refresh) +- Refresh README [docs] (impact: low) + - Why: User requested badges, contents, clearer package guidance, build integration before CLI, and richer rule descriptions. + - Change: Rewrote README structure with NuGet version/download badges, contents, package choice guidance, build integration, CLI usage, and rule descriptions. (files: README.md | cmds: `git diff --check`) + - Notes: No production or test code changed. +### 2026-05-02 03:32 +01:00 (feature/docs-refresh) +- Broaden CI detection [build] (impact: low) + - Why: Azure DevOps should set CI mode through `TF_BUILD`, with reasonable support for other common CI hosts. + - Change: `ContinuousIntegrationBuild` now auto-enables for GitHub Actions, Azure DevOps, generic `CI=true`, TeamCity, and Jenkins unless explicitly set; README documents the behaviour. (files: Directory.Build.props, README.md | cmds: `dotnet msbuild ... -getProperty:ContinuousIntegrationBuild`, `dotnet build PinguApps.RazorStyle.slnx --no-restore`, `git diff --check`) diff --git a/README.md b/README.md index ff59d75..d6e1d83 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,85 @@ # RazorStyle -RazorStyle is an opinionated Razor style linter and enforcer for Blazor `.razor` files. It exists to make Razor markup consistent across a solution, either by checking files in CI or fixing files during local builds. +[![PinguApps.RazorStyle.Cli version](https://img.shields.io/nuget/v/PinguApps.RazorStyle.Cli?style=for-the-badge&label=PinguApps.RazorStyle.Cli)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) [![PinguApps.RazorStyle.Cli downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle.Cli?style=for-the-badge&label=CLI%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) +[![PinguApps.RazorStyle version](https://img.shields.io/nuget/v/PinguApps.RazorStyle?style=for-the-badge&label=PinguApps.RazorStyle)](https://www.nuget.org/packages/PinguApps.RazorStyle/) [![PinguApps.RazorStyle downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle?style=for-the-badge&label=build%20package%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle/) -It is distributed as two packages: +RazorStyle is an opinionated formatter and linter for Blazor `.razor` files. It exists to make component markup predictable across a codebase by enforcing a small set of layout and attribute-ordering rules that are easy to check in CI and easy to fix locally. The style is deliberately prescriptive: it favours consistency, readable diffs, and low-friction code review over preserving every author's preferred Razor layout. -- `PinguApps.RazorStyle.Cli`: a .NET tool named `razorstyle`. -- `PinguApps.RazorStyle`: an MSBuild integration package that runs RazorStyle during builds. +## Contents + +- [Packages](#packages) +- [Build Integration](#build-integration) +- [CLI Usage](#cli-usage) +- [Rules](#rules) + - [RS0001 Attribute Wrapping](#rs0001-attribute-wrapping) + - [RS0002 Child Content Lines](#rs0002-child-content-lines) + - [RS0003 Attribute Order](#rs0003-attribute-order) + +## Packages + +RazorStyle is distributed in two forms: + +- [`PinguApps.RazorStyle`](https://www.nuget.org/packages/PinguApps.RazorStyle/) is the NuGet build integration package. Use this when you want RazorStyle to run automatically as part of project builds. It is the best fit for shared enforcement because every developer and CI agent gets the same behaviour through `PackageReference`. By default, local builds fix files and CI builds check files when `ContinuousIntegrationBuild=true`. You can control whether it runs, whether it checks or fixes, and which rules are disabled through MSBuild properties. +- [`PinguApps.RazorStyle.Cli`](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) is a .NET tool named `razorstyle`. Use this when you want an explicit command for local formatting, repository-wide checks, scripts, or CI jobs that should not depend on MSBuild. It is useful for one-off cleanup, pre-commit workflows, and direct control over the target path and disabled rules. + +## Build Integration + +Install the build package into a project that contains `.razor` files: + +```powershell +dotnet add package PinguApps.RazorStyle +``` + +By default: + +- local builds run `fix` +- CI builds run `check` when `ContinuousIntegrationBuild=true` +- `bin` and `obj` folders are excluded +- projects without `.razor` files are skipped + +Override behaviour with MSBuild properties: + +```xml + + true + check + false + false + false + +``` + +Use the build package when the formatting rule should be part of the project contract. It keeps enforcement close to the project, works naturally in CI, and avoids relying on each developer remembering to run a separate tool command. + +This repository sets `ContinuousIntegrationBuild=true` automatically when it detects GitHub Actions, Azure DevOps, a generic `CI=true` environment, TeamCity, or Jenkins. If your own consuming project does not already do that, add the same property in your build or CI configuration so the build package switches from `fix` to `check` during CI. + +## CLI Usage + +Install the tool: + +```powershell +dotnet tool install --global PinguApps.RazorStyle.Cli +``` + +Check files: + +```powershell +razorstyle check .\src +``` + +Fix files: + +```powershell +razorstyle fix .\src +``` + +Disable specific rules for a run: + +```powershell +razorstyle check .\src --disable RS0001 --disable RS0003 +``` + +Use the CLI when you want direct control over when RazorStyle runs. It is a good fit for local cleanup, manual checks before opening a PR, custom CI steps, and scripts that should target a particular folder. ## Rules @@ -15,6 +89,8 @@ It is distributed as two packages: ### RS0001 Attribute Wrapping +`RS0001` keeps multi-attribute start tags readable by putting each additional attribute on its own aligned line. Tags with no attributes, or with a single attribute, stay inline so simple markup remains compact. + Before: ```razor @@ -38,6 +114,8 @@ Single-attribute and attribute-free tags remain inline: ### RS0002 Child Content Lines +`RS0002` separates child content from the opening and closing tags. This makes inline element bodies easier to scan, gives nested markup room to breathe, and avoids small edits turning into noisy one-line diffs. + Before: ```razor @@ -61,6 +139,8 @@ Self-closing tags are already valid: ### RS0003 Attribute Order +`RS0003` applies a stable attribute order so the important identity, styling, binding, event, content, accessibility, and fallback attributes appear in a predictable place. In broad terms, unique identity-style attributes such as `@key`, `@ref`, `name`, and `id` come first, followed by `class` and `style`, binding and value-related attributes, event callbacks, common HTML/component attributes, templated or child-content attributes, general attributes, `aria-*`, `data-*`, splatted `@attributes`, and boolean or conditional attributes near the end. + Before: ```razor @@ -76,54 +156,3 @@ After: data-track="save" disabled /> ``` - -## CLI Usage - -Install the tool: - -```powershell -dotnet tool install --global PinguApps.RazorStyle.Cli -``` - -Check files: - -```powershell -razorstyle check .\src -``` - -Fix files: - -```powershell -razorstyle fix .\src -``` - -## Build Integration - -Install the build package into a project that contains `.razor` files: - -```powershell -dotnet add package PinguApps.RazorStyle -``` - -By default: - -- local builds run `fix` -- CI builds run `check` when `ContinuousIntegrationBuild=true` - -Override behavior with MSBuild properties: - -```xml - - true - check - false - false - false - -``` - -The CLI also supports per-rule disables: - -```powershell -razorstyle check .\src --disable RS0001 --disable RS0003 -``` From 25fe962cb19f0dd7bb95fb71884e174a0e701a24 Mon Sep 17 00:00:00 2001 From: Matthew Parker Date: Sat, 2 May 2026 03:55:36 +0100 Subject: [PATCH 2/3] Improve CI detection in Directory.Build.props Expand ContinuousIntegrationBuild logic to detect multiple CI environments (GITHUB_ACTIONS, TF_BUILD, CI, TEAMCITY_VERSION, JENKINS_URL) and only set it to true when not already defined. Previously it only checked GITHUB_ACTIONS; this prevents overriding an explicit setting and ensures builds on various CI systems are recognized. --- Directory.Build.props | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Directory.Build.props b/Directory.Build.props index 9a76c39..77188cb 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -17,7 +17,15 @@ git Debug;Release false - true + true PinguApps PinguApps Copyright (c) PinguApps From 03c8666ec3f60f68eb1c651b7f65d298c3ae3ab0 Mon Sep 17 00:00:00 2001 From: Matthew Parker Date: Sat, 2 May 2026 11:10:17 +0100 Subject: [PATCH 3/3] Reformat README badges into table Group and reformat the README badges into a Markdown table to separate CLI tool and build package badges into Version/Downloads rows. Also record the docs refresh entry in .diary/docs-refresh.md with timestamp and brief rationale. (files: README.md, .diary/docs-refresh.md) --- .diary/docs-refresh.md | 4 ++++ README.md | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.diary/docs-refresh.md b/.diary/docs-refresh.md index 0330b07..598d2eb 100644 --- a/.diary/docs-refresh.md +++ b/.diary/docs-refresh.md @@ -15,3 +15,7 @@ - Broaden CI detection [build] (impact: low) - Why: Azure DevOps should set CI mode through `TF_BUILD`, with reasonable support for other common CI hosts. - Change: `ContinuousIntegrationBuild` now auto-enables for GitHub Actions, Azure DevOps, generic `CI=true`, TeamCity, and Jenkins unless explicitly set; README documents the behaviour. (files: Directory.Build.props, README.md | cmds: `dotnet msbuild ... -getProperty:ContinuousIntegrationBuild`, `dotnet build PinguApps.RazorStyle.slnx --no-restore`, `git diff --check`) +### 2026-05-02 11:09 +01:00 (feature/docs-refresh) +- Reformat badges [docs] (impact: low) + - Why: User requested README badges grouped by package type with version/download rows. + - Change: Replaced inline badges under the README title with a Markdown table headed `CLI Tool` and `Build Package`. (files: README.md | cmds: `git diff --check -- README.md`) diff --git a/README.md b/README.md index d6e1d83..89ef9f3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # RazorStyle -[![PinguApps.RazorStyle.Cli version](https://img.shields.io/nuget/v/PinguApps.RazorStyle.Cli?style=for-the-badge&label=PinguApps.RazorStyle.Cli)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) [![PinguApps.RazorStyle.Cli downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle.Cli?style=for-the-badge&label=CLI%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) -[![PinguApps.RazorStyle version](https://img.shields.io/nuget/v/PinguApps.RazorStyle?style=for-the-badge&label=PinguApps.RazorStyle)](https://www.nuget.org/packages/PinguApps.RazorStyle/) [![PinguApps.RazorStyle downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle?style=for-the-badge&label=build%20package%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle/) +| | CLI Tool | Build Package | +| --- | --- | --- | +| Version | [![PinguApps.RazorStyle.Cli version](https://img.shields.io/nuget/v/PinguApps.RazorStyle.Cli?style=for-the-badge&label=PinguApps.RazorStyle.Cli)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) | [![PinguApps.RazorStyle version](https://img.shields.io/nuget/v/PinguApps.RazorStyle?style=for-the-badge&label=PinguApps.RazorStyle)](https://www.nuget.org/packages/PinguApps.RazorStyle/) | +| Downloads | [![PinguApps.RazorStyle.Cli downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle.Cli?style=for-the-badge&label=CLI%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle.Cli/) | [![PinguApps.RazorStyle downloads](https://img.shields.io/nuget/dt/PinguApps.RazorStyle?style=for-the-badge&label=build%20package%20downloads)](https://www.nuget.org/packages/PinguApps.RazorStyle/) | RazorStyle is an opinionated formatter and linter for Blazor `.razor` files. It exists to make component markup predictable across a codebase by enforcing a small set of layout and attribute-ordering rules that are easy to check in CI and easy to fix locally. The style is deliberately prescriptive: it favours consistency, readable diffs, and low-friction code review over preserving every author's preferred Razor layout.