Drop proper noun status for middleware - #37348
Conversation
There was a problem hiding this comment.
Pull request overview
Standardizes ASP.NET Core docs by dropping proper-noun capitalization for middleware names (for example, “Static File Middleware” → “static file middleware”), including related headings, image alt text, and cross-references across the doc set.
Changes:
- Lowercased “{Something} Middleware” references across articles, includes, and sample READMEs.
- Updated related headings/link text (for example, HSTS section wording/anchors) to match the new casing.
- Normalized some section headings to sentence case / imperative phrasing.
Reviewed changes
Copilot reviewed 167 out of 168 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/3.x/TodoApi.Swashbuckle/readme.md | Lowercases “Static File Middleware” reference. |
| aspnetcore/tutorials/razor-pages/razor-pages-start/includes/razor-pages-start9.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/tutorials/razor-pages/razor-pages-start/includes/razor-pages-start8.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/tutorials/razor-pages/razor-pages-start/includes/razor-pages-start7.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/tutorials/razor-pages/razor-pages-start/includes/razor-pages-start6.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/tutorials/razor-pages/razor-pages-start.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field9.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field8.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field7.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field6.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field5.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/razor-pages/new-field/includes/new-field3.md | Updates heading casing/phrasing. |
| aspnetcore/tutorials/getting-started-with-swashbuckle/includes/getting-started-with-swashbuckle8.md | Lowercases “Static File Middleware” references and related headings. |
| aspnetcore/test/integration-tests/includes/integration-tests9.md | Lowercases “HTTPS Redirection Middleware” reference. |
| aspnetcore/test/integration-tests/includes/integration-tests8.md | Lowercases “HTTPS Redirection Middleware” reference. |
| aspnetcore/test/integration-tests/includes/integration-tests7.md | Lowercases “HTTPS Redirection Middleware” reference. |
| aspnetcore/test/integration-tests.md | Lowercases “HTTPS Redirection Middleware” reference. |
| aspnetcore/security/enforcing-ssl/includes/enforcing-ssl8.md | Lowercases middleware references; updates HSTS section link/anchor wording. |
| aspnetcore/security/enforcing-ssl/includes/enforcing-ssl7.md | Lowercases middleware references; updates HSTS section link/anchor wording. |
| aspnetcore/security/enforcing-ssl.md | Lowercases middleware references; updates HSTS section heading wording. |
| aspnetcore/security/cors/includes/cors7.md | Lowercases “CORS Middleware” and related middleware references. |
| aspnetcore/security/cors.md | Lowercases “CORS Middleware” and related middleware references. |
| aspnetcore/security/authorization/policies/includes/policies5.md | Lowercases “Authorization Middleware” reference. |
| aspnetcore/security/authorization/policies.md | Lowercases “Authorization Middleware” reference. |
| aspnetcore/security/authorization/iauthorizationpolicyprovider.md | Lowercases “Authorization Middleware” reference. |
| aspnetcore/security/authentication/windowsauth.md | Lowercases multiple middleware references (IIS integration, status code pages, authentication). |
| aspnetcore/security/authentication/social/social-without-identity.md | Lowercases “Authorization Middleware” phrasing in auth pipeline text. |
| aspnetcore/security/authentication/social/includes/forwarded-headers-middleware.md | Lowercases “Forwarded Headers Middleware” reference. |
| aspnetcore/security/authentication/social/additional-claims.md | Lowercases middleware naming; contains typos that need fixing (see comments). |
| aspnetcore/security/authentication/passkeys/index.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/security/authentication/certauth.md | Lowercases certificate forwarding middleware references. |
| aspnetcore/release-notes/aspnetcore-9/includes/keyedDI.md | Fixes heading spacing/casing. |
| aspnetcore/release-notes/aspnetcore-8.0.md | Lowercases exception handling middleware reference. |
| aspnetcore/release-notes/aspnetcore-6.0.md | Lowercases developer exception page middleware reference. |
| aspnetcore/release-notes/aspnetcore-5.0.md | Lowercases authorization middleware reference. |
| aspnetcore/release-notes/aspnetcore-3.0.md | Lowercases connection/forwarded headers middleware references. |
| aspnetcore/release-notes/aspnetcore-2.2.md | Lowercases CORS/response compression middleware references. |
| aspnetcore/release-notes/aspnetcore-2.1.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/release-notes/aspnetcore-11/includes/blazor.md | Lowercases CSRF protection middleware reference. |
| aspnetcore/release-notes/aspnetcore-10/includes/blazor.md | Lowercases status code pages re-execution middleware references. |
| aspnetcore/release-notes/aspnetcore-1.1.md | Lowercases URL rewriting/response caching middleware references. |
| aspnetcore/performance/response-compression/samples/3.x/SampleApp/README.md | Lowercases response compression middleware reference. |
| aspnetcore/performance/response-compression/samples/2.x/SampleApp/README.md | Lowercases response compression middleware reference. |
| aspnetcore/performance/rate-limit.md | Updates section heading casing. |
| aspnetcore/performance/memory.md | Lowercases response caching middleware reference. |
| aspnetcore/performance/caching/output.md | Lowercases “ASP.NET Core Middleware” link text. |
| aspnetcore/performance/caching/middleware/samples/3.x/ResponseCachingMiddleware/README.md | Lowercases response caching middleware reference. |
| aspnetcore/performance/caching/middleware/samples/2.x/ResponseCachingMiddleware/README.md | Lowercases response caching middleware reference. |
| aspnetcore/mvc/controllers/routing.md | Lowercases routing middleware mention in description metadata. |
| aspnetcore/mvc/controllers/filters/includes/filters7.md | Lowercases middleware terms in alt text; contains a typo that needs fixing (see comments). |
| aspnetcore/mvc/controllers/filters.md | Lowercases middleware terms in image alt text. |
| aspnetcore/migration/fx-to-core/areas/http-modules.md | Lowercases middleware terms in image alt text. |
| aspnetcore/migration/fx-to-core/areas/http-handlers.md | Lowercases middleware terms in image alt text. |
| aspnetcore/migration/fx-to-core/areas/authentication.md | Lowercases middleware terms; contains a typo that needs fixing (see comments). |
| aspnetcore/migration/70-to-80.md | Lowercases middleware references in migration instructions. |
| aspnetcore/migration/50-to-60-samples.md | Lowercases static file middleware references. |
| aspnetcore/migration/22-to-30.md | Lowercases connection/CORS/authorization/endpoints middleware references. |
| aspnetcore/migration/20-to-21.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/migration/1x-to-2x/identity-2x.md | Updates heading casing for “Authentication middleware and services”. |
| aspnetcore/includes/scaffold-identity/hsts.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/host-and-deploy/linux-nginx.md | Lowercases forwarded headers/HTTPS redirection middleware references; updates HSTS xref anchor. |
| aspnetcore/host-and-deploy/index.md | Lowercases health checks middleware reference. |
| aspnetcore/host-and-deploy/iis/out-of-process-hosting.md | Lowercases IIS integration/forwarded headers middleware references in table/text. |
| aspnetcore/host-and-deploy/iis/modules.md | Lowercases middleware references; contains a typo that needs fixing (see comments). |
| aspnetcore/host-and-deploy/iis/development-time-iis-support.md | Lowercases HTTPS redirection/HSTS middleware references. |
| aspnetcore/host-and-deploy/iis/advanced.md | Lowercases IIS middleware references; lowercases static file middleware references. |
| aspnetcore/host-and-deploy/health-checks/samples/5.x/HealthChecksSample/README.md | Lowercases health checks middleware reference. |
| aspnetcore/host-and-deploy/health-checks/samples/3.x/HealthChecksSample/README.md | Lowercases health checks middleware reference. |
| aspnetcore/host-and-deploy/health-checks/includes/health-checks6-7.md | Lowercases health checks/CORS/authorization middleware references. |
| aspnetcore/host-and-deploy/health-checks.md | Lowercases health checks/CORS/authorization middleware references. |
| aspnetcore/host-and-deploy/azure-apps/index.md | Lowercases IIS integration/forwarded headers/cookie middleware references. |
| aspnetcore/host-and-deploy/aspnet-core-module.md | Lowercases IIS integration middleware references. |
| aspnetcore/grpc/migration.md | Lowercases “Middleware” in section/link text. |
| aspnetcore/grpc/interceptors.md | Lowercases “Middleware” in section headings/text. |
| aspnetcore/grpc/configuration.md | Lowercases “Middleware” in table link text. |
| aspnetcore/fundamentals/url-rewriting/samples/6.x/SampleApp/README.md | Lowercases URL rewriting/static file middleware references. |
| aspnetcore/fundamentals/url-rewriting/samples/3.x/SampleApp/README.md | Lowercases URL rewriting/static file middleware references. |
| aspnetcore/fundamentals/url-rewriting/samples/2.x/SampleApp/README.md | Lowercases URL rewriting/static file middleware references. |
| aspnetcore/fundamentals/startup/includes/startup56.md | Updates HSTS xref anchor. |
| aspnetcore/fundamentals/servers/yarp/transforms.md | Updates heading casing (“Add transforms”). |
| aspnetcore/fundamentals/servers/yarp/timeouts.md | Lowercases request timeouts middleware reference. |
| aspnetcore/fundamentals/servers/yarp/middleware.md | Lowercases title/description/headings. |
| aspnetcore/fundamentals/servers/yarp/extensibility.md | Lowercases “middleware pipeline” and “HTTP forwarder” references. |
| aspnetcore/fundamentals/servers/yarp/dests-health-checks.md | Adjusts passive health checks middleware wording. |
| aspnetcore/fundamentals/servers/yarp/cors.md | Lowercases CORS middleware reference. |
| aspnetcore/fundamentals/servers/yarp/config-files.md | Lowercases “ASP.NET Core middleware” in note link text. |
| aspnetcore/fundamentals/servers/kestrel/security-considerations.md | Lowercases host-filtering/security middleware references (including table links). |
| aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md | Lowercases forwarded headers/connection/host-filtering middleware references. |
| aspnetcore/fundamentals/servers/kestrel/host-filtering.md | Lowercases host-filtering/forwarded headers middleware references. |
| aspnetcore/fundamentals/servers/kestrel/endpoints/includes/endpoints5-7.md | Lowercases “Connection middleware” heading/link text. |
| aspnetcore/fundamentals/servers/index.md | Lowercases IIS integration middleware reference. |
| aspnetcore/fundamentals/portable-object-localization.md | Updates heading casing/phrasing. |
| aspnetcore/fundamentals/minimal-apis/security.md | Replaces relative middleware link with xref and lowercases link text. |
| aspnetcore/fundamentals/minimal-apis/middleware.md | Lowercases “ASP.NET Core middleware” link text. |
| aspnetcore/fundamentals/minimal-apis/includes/webapplication9.md | Lowercases static file middleware references; updates heading casing. |
| aspnetcore/fundamentals/minimal-apis/includes/webapplication8.md | Lowercases static file middleware references; updates heading casing. |
| aspnetcore/fundamentals/minimal-apis/includes/webapplication7.md | Lowercases static file middleware references; updates heading casing. |
| aspnetcore/fundamentals/minimal-apis/includes/webapplication10.md | Lowercases static file middleware references; updates heading casing. |
| aspnetcore/fundamentals/minimal-apis/includes/minimal-apis9.md | Lowercases “ASP.NET Core middleware” heading. |
| aspnetcore/fundamentals/minimal-apis/includes/minimal-apis8.md | Lowercases “ASP.NET Core middleware” heading. |
| aspnetcore/fundamentals/minimal-apis/includes/minimal-apis7.md | Lowercases “ASP.NET Core middleware” heading. |
| aspnetcore/fundamentals/minimal-apis/includes/minimal-apis6.md | Lowercases static file middleware references; updates headings. |
| aspnetcore/fundamentals/minimal-apis/handle-errors/includes/handle-errors7.md | Lowercases exception handler middleware references. |
| aspnetcore/fundamentals/minimal-apis.md | Lowercases “ASP.NET Core middleware” heading. |
| aspnetcore/fundamentals/logging/index.md | Lowercases host-filtering middleware phrasing in log category descriptions. |
| aspnetcore/fundamentals/localization/includes/localization35.md | Lowercases routing/localization middleware references. |
| aspnetcore/fundamentals/localization-extensibility.md | Lowercases localization middleware link text. |
| aspnetcore/fundamentals/index/includes/index8.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/fundamentals/index/includes/index3-7.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/fundamentals/index.md | Updates HSTS link text/xref anchor wording. |
| aspnetcore/fundamentals/host/generic-host.md | Lowercases host-filtering middleware reference. |
| aspnetcore/fundamentals/file-providers.md | Lowercases static file middleware reference. |
| aspnetcore/fundamentals/error-handling/includes/error-handling9.md | Lowercases exception handling/static file/endpoints middleware references. |
| aspnetcore/fundamentals/error-handling/includes/error-handling8.md | Lowercases exception handling/static file/endpoints middleware references. |
| aspnetcore/fundamentals/error-handling.md | Lowercases exception handling/static file/endpoints middleware references; updates subsection heading casing. |
| aspnetcore/fundamentals/error-handling-api.md | Lowercases exception handler middleware references. |
| aspnetcore/fundamentals/environments.md | Lowercases exception handler and HSTS middleware references; updates HSTS xref anchor. |
| aspnetcore/fundamentals/configuration/index.md | Lowercases host-filtering/forwarded headers middleware references. |
| aspnetcore/fundamentals/app-state.md | Lowercases session middleware reference. |
| aspnetcore/diagnostics/mvc1005.md | Lowercases authorization/CORS middleware references. |
| aspnetcore/client-side/spa/includes/intro6-7.md | Lowercases static file middleware reference. |
| aspnetcore/client-side/spa-services.md | Lowercases webpack dev middleware headings/references. |
| aspnetcore/breaking-changes/9/overview.md | Lowercases forwarded headers middleware entry. |
| aspnetcore/breaking-changes/8/overview.md | Lowercases forwarded headers middleware entry. |
| aspnetcore/breaking-changes/8/forwarded-headers-unknown-proxies.md | Lowercases forwarded headers middleware title/description/heading text. |
| aspnetcore/breaking-changes/6/overview.md | Lowercases HTTPS redirection middleware entry. |
| aspnetcore/breaking-changes/6/middleware-ambiguous-https-ports-exception.md | Lowercases HTTPS redirection middleware references throughout. |
| aspnetcore/breaking-changes/5/static-files-csv-content-type-changed.md | Lowercases static file middleware reference. |
| aspnetcore/breaking-changes/5/middleware-exception-handler-throws-original-exception.md | Lowercases exception handler middleware title/description/heading text. |
| aspnetcore/blazor/tutorials/signalr-blazor.md | Lowercases response compression middleware references. |
| aspnetcore/blazor/tutorials/movie-database-app/part-1.md | Lowercases multiple middleware references (exception handler, HSTS, status code pages, HTTPS redirection, antiforgery, static files). |
| aspnetcore/blazor/security/webassembly/standalone-with-authentication-library.md | Lowercases forwarded headers middleware reference in resource list. |
| aspnetcore/blazor/security/webassembly/index.md | Lowercases forwarded headers middleware reference in resource list. |
| aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md | Lowercases IdentityServer/auth/authz/JWT bearer middleware references; lowercases forwarded headers middleware in resource list. |
| aspnetcore/blazor/security/qrcodes-for-authenticator-apps.md | Updates heading casing/phrasing. |
| aspnetcore/blazor/security/interactive-server-side-rendering.md | Lowercases CORS middleware reference. |
| aspnetcore/blazor/security/index.md | Lowercases antiforgery/forwarded headers middleware references. |
| aspnetcore/blazor/security/gdpr.md | Lowercases cookie policy middleware reference. |
| aspnetcore/blazor/security/additional-scenarios.md | Lowercases authentication middleware references. |
| aspnetcore/blazor/javascript-interoperability/index.md | Lowercases HTTP response caching middleware reference. |
| aspnetcore/blazor/host-and-deploy/webassembly/multiple-hosted-webassembly.md | Lowercases static file middleware reference. |
| aspnetcore/blazor/host-and-deploy/index.md | Lowercases static file middleware reference. |
| aspnetcore/blazor/host-and-deploy/app-base-path.md | Lowercases routing/static file middleware references. |
| aspnetcore/blazor/fundamentals/static-files.md | Lowercases static file middleware references throughout. |
| aspnetcore/blazor/fundamentals/startup.md | Lowercases “ASP.NET Core middleware” link text. |
| aspnetcore/blazor/fundamentals/signalr.md | Lowercases response compression middleware reference. |
| aspnetcore/blazor/fundamentals/routing.md | Lowercases status code pages re-execution middleware reference. |
| aspnetcore/blazor/fundamentals/navigation.md | Lowercases status code pages re-execution middleware references. |
| aspnetcore/blazor/forms/index.md | Lowercases antiforgery middleware references. |
| aspnetcore/blazor/components/rendering.md | Lowercases status code pages re-execution middleware references. |
| aspnetcore/blazor/components/render-modes.md | Lowercases authorization middleware references. |
wadepickett
left a comment
wadepickett
left a comment
There was a problem hiding this comment.
@guardrex,
Approved, but do see my suggestion for a link fix.
|
@guardrex, I re-approved since there was one more commit and another approval required. |
|
Thanks, @wadepickett. Let's see if @danroth27 really wants to proceed with this. If so, I'll merge it; and from now on, all middlewares will be treated as general nouns with the only uppercase letters being part of proper adjectives. I'll 😢 in my 🍺 over it 😆, but that's what we'll do from now on. |
😂. I honestly don't feel strongly about this either way. We should of course be consistent. I believe our Microsoft style guides say to reserve capitals for true proper nouns and branded product/feature names. I think of middleware names as largely descriptive (authorization, rate limiting, etc.), not proper feature names, but I get the readability argument. If it's less disruptive to standardize on treating middleware names as proper nouns, I'm fine with that. |
|
I guess that we'll leave it to @wadepickett and @tdykstra to decide. 🧑⚖️ I'll adopt whatever style they want to use. IMO, these are proper nouns by definition ... specific, named things in the framework. In some cases, it seems to me that dropping the caps makes it hard to understand which words are adjectives and which words are part of the name. If we don't proceed with this PR, I made a couple of updates that I'd like to put on a new PR ... things that I spotted for a quick fix along the way. I'm 👂 for the ruling! 😄 |
|
I am aligned with Dan here: "I believe our Microsoft style guides say to reserve capitals for true proper nouns and branded product/feature names. I think of middleware names as largely descriptive (authorization, rate limiting, etc.), not proper feature names" In our case, we want to call out proper feature names with a cap, and what you changed in this PR from what I saw was removing caps from middleware things we were describing and referring to, not proper feature names. The guide reserves capitalization for genuine proper nouns and branded names. "response caching middleware," "exception handling middleware," etc., are descriptive phrases, not brand names. I also agree with you, Luke, on adopting hyphenation for compound -ing adjectives where ambiguity is real (host-filtering), but leave clear ones like "exception handling middleware" and "URL rewriting middleware" unhyphenated. I don't think this is necessarily the highest priority issue at the moment per se, but it's also one of those where if we don't clean house once in a while, it builds on itself as a problem. People look to previously published content to determine how to proceed with an update, etc. So I am happy it's being addressed, thanks. I will help by also adding some rules to our repo agent skills to help keep this clean, tracking issue here: #37360, will have a PR going soon. |
|
I don't agree with that analysis 😄, but I'll adopt and enforce the rule that you set. For the record, I was following the well-established convention on this that the FTEs put into place many years ago, which was based on Chicago and standard written English ... and to avoid confusion over adjectives and parts of the name. If you want me to provide more info on how Chicago and other style manuals treat this subject, I can add a little more discussion. Anyway, I guess we're just waiting for @tdykstra's feedback. |
|
Thanks Luke, and genuinely, thank you for tackling 800+ of these by hand. That's not fun work, and the cleanup matters. Your reasoning is sound and well-grounded in Chicago and the original FTE convention, and Dan said he doesn't feel strongly either way. This really is a close call, and I don't want to over-index on something that isn't a huge deal. My preference for lowercasing the descriptive phrases is mostly about consistency with the Microsoft Style Guide and matching what readers see across the rest of the .NET ecosystem, blogs, and source: less context-switching for them. I think your concern over adjective ambiguity would be good to bake into a rule. I'd rather solve that with hyphenation than with caps: "host-filtering middleware" where the meaning is truly ambiguous, while leaving clear ones open ("exception handling middleware," "URL rewriting middleware"). That directly addresses the confusion you're worried about without reintroducing inconsistent casing. Exact casing still stays for true brand/feature names and API identifiers (HSTS, UseHsts, etc.). Let's still get Tom's read before we call it settled, since you're deferring to us and Dan's neutral. I'll fold the lowercase + hyphenation-for-ambiguity guidance into the repo agent skills (see #37360) so future contributors don't just copy older capitalized patterns. It's in draft, and we can update based on the outcome here after Tom chimes in. |
|
@tdykstra, could use your input on guidance going forward. |
tdykstra
left a comment
tdykstra
left a comment
There was a problem hiding this comment.
I'm 100% in agreement with dropping proper noun status for middleware. I expect it will result in less confusion, not more. I'm open to looking at examples where proper noun status seems to be a better fit than the alternative. but they will be hard to find.
The most important argument in favor of this change is what Dan says about the style guide's conservative attitude towards capitalization. Dropping proper noun status puts us more in line with the style guide and with the rest of the published ASP.NET Core docs, which tend to follow the style guide.
|
😄 The "Ayes" have it! The motion is carried! |
Fixes #37345
Pinging you, Dan, just to sign off on the order for this set of changes. Pinging Wade and Tom for review, but we only need one to get it in.
I think this gets them all 😅. There were something to the tune of 800+ of these to change, and they had to be checked individually to deal with table entries and first words of sentences. I also updated a few other NITs along the way. Copilot flagged two misspellings, which I updated ... coookie 👉 cookie and outing 👉 routing."
I'm concerned about confusing readers with this change, especially for the multiple-word middleware names, where it's probably challenging to distinguish adjectives from words that are part of a middleware's name. I also don't think this is standard written English because these are specific, named pieces of the framework (i.e., they aren't general nouns in the context of referring to any of them explicitly). Those are the reasons that they were made proper nouns at the outset, and it was discussed and approved by the FTEs in charge at the time.
To proceed with the PR, get the eye drops out for review! 👁️💧😬😆 [... but I kind'a expect that only a scan of this will do.]
Editorial note Wade and Tom: For a couple of -ing ending words, I hyphenated them because I think they're being treating as adjectives from now on with these changes. It would be even more confusing (and grammatically incorrect I think) to not hyphenate ordinary adjectives in naming if they're confusing. For example, consider "host filtering middleware," excluding the context of the sentence. Is it "filtering middleware" on a host, or is it middleware that filters hosts? It has to be "host-filtering middleware" to make it clear that it's the latter. Even if the context of the sentence resolves the meaning of "host filtering middleware," there's a good chance that it will slow the reader down. Others didn't require a hyphen (e.g., exception handling middleware, error handling middleware, URL rewriting middleware). However, let's discuss this further if there are concerns. I can compile a list of all -ing-ending adjectives in middleware names for discussion here. Let me know what you think. 👂
Internal previews
Toggle expand/collapse
Note
This table shows preview links for the 30 files with the most changes. For preview links for other files in this PR, select OpenPublishing.Build Details within checks.