diff --git a/.docfx/Dockerfile.docfx b/.docfx/Dockerfile.docfx index 9d42262..465ff57 100644 --- a/.docfx/Dockerfile.docfx +++ b/.docfx/Dockerfile.docfx @@ -1,4 +1,4 @@ -ARG NGINX_VERSION=1.31.0-alpine +ARG NGINX_VERSION=1.31.2-alpine FROM --platform=$BUILDPLATFORM nginx:${NGINX_VERSION} AS base RUN rm -rf /usr/share/nginx/html/* diff --git a/.docfx/api/namespaces/Codebelt.Extensions.Globalization.md b/.docfx/api/namespaces/Codebelt.Extensions.Globalization.md index 473e529..0bdb99b 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.Globalization.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.Globalization.md @@ -2,24 +2,44 @@ uid: Codebelt.Extensions.Globalization summary: *content --- -The `Codebelt.Extensions.Globalization` namespace contains extension methods that is an addition to the `System.Globalization` namespace. +# Codebelt.Extensions.Globalization + +The `Codebelt.Extensions.Globalization` namespace helps you enrich `CultureInfo` instances with Windows NLS formatting behavior when you need culture-aware date and number patterns that behave more like the Windows runtime than the ICU defaults. + +Use it when you want to adapt a culture for consumer-facing formatting in applications that rely on Windows-style patterns, especially for `DateTimeFormat` and `NumberFormat` values. + +If you are trying to switch a culture to NLS-style formatting, start with `CultureInfoExtensions`. [!INCLUDE [availability-default](../../includes/availability-default.md)] Complements: [System.Globalization namespace](https://docs.microsoft.com/en-us/dotnet/api/system.globalization) 🔗 -### Extension Methods +## Extension Members |Type|Ext|Methods| |--:|:-:|---| -|CultureInfo|⬇️|`UseNationalLanguageSupport`| +|`CultureInfo`|⬇️|`UseNationalLanguageSupport()`| +|`IEnumerable`|⬇️|`UseNationalLanguageSupport()`| -### CSharp Example +### Example ```csharp -var danishCultureIcu = new CultureInfo("da-dk", false); -var danishCultureNls = new CultureInfo("da-dk", false).UseNationalLanguageSupport(); +using System; +using System.Globalization; +using Codebelt.Extensions.Globalization; + +namespace Demo; + +public static class Sample +{ + public static void Run() + { + var danishCultureIcu = new CultureInfo("da-dk", false); + var danishCultureNls = new CultureInfo("da-dk", false).UseNationalLanguageSupport(); + -// danishCultureIcu outputs dd.MM.yyyy from danishCultureIcu.DateTimeFormat.ShortDatePattern -// danishCultureNls outputs dd-MM-yyyy from danishCultureNls.DateTimeFormat.ShortDatePattern + Console.WriteLine(danishCultureIcu.DateTimeFormat.ShortDatePattern); // danishCultureIcu outputs dd.MM.yyyy from danishCultureIcu.DateTimeFormat.ShortDatePattern + Console.WriteLine(danishCultureNls.DateTimeFormat.ShortDatePattern); // danishCultureNls outputs dd-MM-yyyy from danishCultureNls.DateTimeFormat.ShortDatePattern + } +} ``` diff --git a/.docfx/api/types/Codebelt.Extensions.Globalization.CultureInfoExtensions.md b/.docfx/api/types/Codebelt.Extensions.Globalization.CultureInfoExtensions.md new file mode 100644 index 0000000..813d73e --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Globalization.CultureInfoExtensions.md @@ -0,0 +1,27 @@ +--- +uid: Codebelt.Extensions.Globalization.CultureInfoExtensions +example: +- *content +--- +# CultureInfoExtensions + +The following example shows how to enrich a culture with Windows NLS formatting information for consumer-facing date and number patterns. + +```csharp +using System; +using System.Globalization; +using Codebelt.Extensions.Globalization; + +namespace Demo; + +public static class Sample +{ + public static void Run() + { + CultureInfo culture = CultureInfo.GetCultureInfo("da-DK"); + CultureInfo enriched = culture.UseNationalLanguageSupport(); + + Console.WriteLine(enriched.DateTimeFormat.ShortDatePattern); + } +} +``` diff --git a/.docfx/docfx.json b/.docfx/docfx.json index d30682c..aadc464 100644 --- a/.docfx/docfx.json +++ b/.docfx/docfx.json @@ -25,14 +25,15 @@ { "files": [ "api/**/*.yml", - "api/**/*.md", "packages/**/*.md", "toc.yml", "*.md" ], "exclude": [ "bin/**", - "obj/**" + "obj/**", + "api/namespaces/**", + "api/types/**" ] } ], @@ -67,7 +68,8 @@ "overwrite": [ { "files": [ - "api/namespaces/**.md" + "api/namespaces/**/*.md", + "api/types/**/*.md" ], "exclude": [ "obj/**", diff --git a/.github/workflows/ci-pipeline.yml b/.github/workflows/ci-pipeline.yml index 7110572..0b9ecf1 100644 --- a/.github/workflows/ci-pipeline.yml +++ b/.github/workflows/ci-pipeline.yml @@ -210,7 +210,8 @@ jobs: security-events: write deploy: - if: github.event_name != 'pull_request' + # Avoid skipped optional jobs (for example disabled macOS matrix runs) from suppressing deployment. + if: ${{ always() && github.event_name != 'pull_request' && needs.build.result == 'success' && needs.pack.result == 'success' && needs.test_qualitygate.result == 'success' && needs.sonarcloud.result == 'success' && needs.codecov.result == 'success' && needs.codeql.result == 'success' }} name: call-nuget needs: [build, pack, test_qualitygate, sonarcloud, codecov, codeql] uses: codebeltnet/jobs-nuget-push/.github/workflows/default.yml@v3 diff --git a/.nuget/Codebelt.Extensions.Globalization/PackageReleaseNotes.txt b/.nuget/Codebelt.Extensions.Globalization/PackageReleaseNotes.txt index 9859117..1b94304 100644 --- a/.nuget/Codebelt.Extensions.Globalization/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Extensions.Globalization/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 10.0.9 +Availability: .NET 10, .NET 9 and .NET Standard 2.0 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 10.0.8 Availability: .NET 10, .NET 9 and .NET Standard 2.0 diff --git a/AGENTS.md b/AGENTS.md index 4e567c1..c3d67ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,8 +62,62 @@ Agents must never automatically commit code changes or push to remote repositori **Rationale:** Automatic commits can clutter history with incomplete work, temporary debugging code, or unintended changes. Unexpected remote operations risk overwriting or losing commits on shared branches. Always require explicit user approval before performing these actions. -## Official Documentation + +## DocFX Documentation Maintenance -- Public API conventions belong in `.docfx/api/namespaces/` and should be treated as the official documentation source for library behavior and naming vocabulary. -- When adding or renaming public APIs, update the relevant namespace page in `.docfx/api/namespaces/` if the change introduces or clarifies a convention. -- Keep internal reasoning, exploratory notes, and agent discussion out of DocFX pages; summarize only stable public guidance. +When changing public .NET APIs, keep the DocFX documentation current in the same change set. + +Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API. + +Public non-abstraction types — including enums, structs, records, plain classes, and static extension containers — are valid documentation targets. Generic public types and generic extension methods are valid documentation targets too. Do not exclude a type solely because it is generic or because reflection reports it as abstract and sealed (that is the IL pattern for a static class). + +For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage. + +Missing type examples must be added through per-type DocFX overwrite files under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples. + +Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough. + +All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior. + +Compilation is necessary but not sufficient. Do not present runtime implementation names such as `services.GetType().Name` or `host.GetType().FullName` as the example outcome. Show application behavior, configured state, a resolved domain service, an HTTP response, or another result that explains why a caller uses the API. Application-entry-point examples must not declare an empty local `Program` type merely to compile; show a real entry point or clearly identify the referenced application project. + +Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, under `.docfx/api/namespaces/`, using DocFX overwrite front matter with the namespace `uid`. + +Namespace pages must identify key entry points from release notes, package documentation, public factories/builders, and strong functional tests, then help readers choose among adjacent workflows. When the package complements a well-known upstream API, compare concrete acquisition, customization, lifecycle, and sharing tradeoffs from current official guidance; do not claim drop-in replacement compatibility without evidence. + +Namespaces exposing public extension methods must document those extension members at namespace level. The namespace page must include an `Extension Members` table listing the extended type, the extension marker, and the public extension methods. Extension members are rendered under the heading `Extension Members`. + +Both namespace overwrite files and type overwrite files are required deliverables in the same run. Generating only namespace pages or only type pages is incomplete. + +`docfx.json` must keep namespace and type overwrite files in separate subdirectories. `build.overwrite` must include both `api/namespaces/**/*.md` (for namespace pages) and `api/types/**/*.md` (for type pages). `build.content` must exclude both `api/namespaces/**` and `api/types/**` to prevent overwrite Markdown from being treated as conceptual content. Do not use `api/**/*.md` under `build.overwrite` or `build.content`. + +Availability must be documented by referencing the appropriate include file when one exists, or by adding explicit availability text when no suitable include exists. Availability must reflect the actual target frameworks, conditional compilation, and project configuration. + +For conditionally compiled APIs, choose the executable test framework from the asset that contains the API. Inspect the preprocessor condition, project TFMs, package `lib/` assets, and resolved consumer asset before changing a sample. For APIs under `NETSTANDARD2_0` or `NETSTANDARD2_0_OR_GREATER`, when modern `lib/netX.0/` assets also exist, use `net48` (or another supported .NET Framework target from `net462` onward) so the consumer selects `lib/netstandard2.0/`. Never use `netstandard*` as an executable target, and never use a modern `netX.0` target when it selects an asset where the API is absent. For other TFM guards, select a runnable consumer TFM that resolves to the containing asset and confirm that selection from restore or build evidence. + +Preserve manual documentation edits. Prefer additive changes, but correct stale or contradictory information so documentation remains accurate. + +Preserve working Markdown links, `Related:` references, and historical URL citations during prose rewrites. Remove or replace a URL only after directly verifying that the current destination returns HTTP 404. Timeouts, 403s, rate limits, DNS failures, and other lookup problems are not removal evidence. + +Interim scratch artifacts do not belong in the repository working tree. Store assessment queues, project manifests, review reports, captured validator output, progress notes, and one-off helper scripts in temp or session storage instead. New working-tree files are only legitimate when they are the managed `AGENTS.md` block, the active `docfx.json`, the deterministic `skip-compile-allowlist.json` waiver file when one is truly required, or DocFX-authored namespace/type Markdown that maps to a real public namespace or type. Everything else is blocking cleanup work, not a documentation deliverable. The validator auto-detects generic-arity type families (such as `MutableTuple`1`..`MutableTuple`N`) and skips redundant sibling examples from the public API surface alone, so no family-skip manifest is ever written into the repository. + +Skip markers are waivers, not fixes. A skip marker only suppresses compilation when it both existed before the current run and matches an entry in `.docfx/skip-compile-allowlist.json`. Each allowlist entry must include `diagnosticCode`, `filePath`, `uid` or `symbol`, `reason`, `approval`, and `lifetime` (`temporary` or `permanent`). Newly introduced or unallowlisted skip markers remain fail-level diagnostics and do not permit a completion claim. + +Do not emit a final report, audit result, completion summary, or handoff while `summary.canClaimCompletion` is false, `summary.remainingWorkItems` is greater than zero, `summary.remainingGates` is non-empty, `summary.fullVerificationRan` is false, fail-level diagnostics remain, `summary.newlyIntroducedSkipMarkers` is non-zero, or `summary.interimArtifacts` is non-zero. Large queues, many changed files, repetitive next steps, long runtimes, context pressure, session length, task size, or a "stable queue" are not valid stop reasons; the next action must be another remediation batch, a validator rerun, a validator/tooling fix, or a true blocker with exact evidence. + +Context pressure is not a completion condition. If the session feels constrained while work remains, continue with a smaller deterministic batch, regenerate deterministic queue state such as `--assessment-queue`, `--project-manifest`, or the active dry-run manifest/review pair, or report a true tooling failure with the exact command, exit code, and output. When naming a queue-state regeneration command, resolve it to a concrete temp/session path instead of leaving `` as a placeholder. Do not stop with phrases like "given context constraints", "best done in a follow-up", "remaining work requires authoring", "this is a massive task", or "I will provide a focused summary". A context-sized handoff while work remains is `FAIL_CONTEXT_HANDOFF_WITH_REMAINING_WORK`; the remediation is to continue with a smaller deterministic batch. + +Before completing documentation work, run the relevant verification commands, normally: + +```bash +dotnet build +dotnet test +dotnet run --file /scripts/docfx.cs -- --repo-root . --build-api-model --validate-samples --verify-docfx-build +``` + +Codebelt repositories are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. Preserve and copy that root `.snk` file when building a temporary copy. If the repository or temp copy has no root `.snk`, run build and test verification with `-p:SkipSignAssembly=true`, for example `dotnet build -p:SkipSignAssembly=true` and `dotnet test -p:SkipSignAssembly=true`. + +The final DocFX verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status. Do not call the work complete until the final JSON reports `summary.fullVerificationRan: true`, `summary.canClaimCompletion: true`, `summary.remainingWorkItems: 0`, an empty `summary.remainingGates`, an empty `summary.remainingDiagnosticsByCode`, `summary.newlyIntroducedSkipMarkers: 0`, and `summary.interimArtifacts: 0`. + +If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified. + diff --git a/CHANGELOG.md b/CHANGELOG.md index d346886..d22de6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,26 @@ For more details, please refer to `PackageReleaseNotes.txt` on a per assembly ba > [!NOTE] > Changelog entries prior to version 9.0.1 was migrated from previous versions of Cuemon.Extensions.Globalization. +## [10.0.9] - 2026-07-01 + +This is a patch release focused on API documentation improvements, CI/tooling enhancements, and maintenance updates to build and test dependencies. + +### Added + +- Comprehensive type documentation for `CultureInfoExtensions` with realistic, copy-paste-ready examples showing how to adapt a culture for NLS-style formatting, +- DocFX documentation maintenance guidelines in `AGENTS.md` establishing standards for API documentation, namespace pages, type examples, availability notes, and verification procedures. + +### Changed + +- Enhanced namespace overview with clearer purpose statement and use-case guidance for when to use culture NLS adaptation, +- Updated nginx Docker image from 1.31.0 to 1.31.2, +- Upgraded Microsoft.NET.Test.SDK from 18.6.0 to 18.7.0, +- Configured DocFX to properly exclude namespace and type overwrite files from conceptual content to prevent duplication and incorrect rendering. + +### Fixed + +- CI deployment job condition now explicitly validates all required jobs succeeded before proceeding, preventing skipped optional jobs from allowing deployment to proceed. + ## [10.0.8] - 2026-06-06 This is a service update that focuses on package dependencies. @@ -122,7 +142,11 @@ This is a service update that primarily focuses on package dependencies and mino - CultureInfoExtensions class in the Codebelt.Extensions.Globalization namespace that consist of extension methods for the CultureInfo class: UseNationalLanguageSupport -[Unreleased]: https://github.com/codebeltnet/globalization/compare/v10.0.5...HEAD +[Unreleased]: https://github.com/codebeltnet/globalization/compare/v10.0.9...HEAD +[10.0.9]: https://github.com/codebeltnet/globalization/compare/v10.0.8...v10.0.9 +[10.0.8]: https://github.com/codebeltnet/globalization/compare/v10.0.7...v10.0.8 +[10.0.7]: https://github.com/codebeltnet/globalization/compare/v10.0.6...v10.0.7 +[10.0.6]: https://github.com/codebeltnet/globalization/compare/v10.0.5...v10.0.6 [10.0.5]: https://github.com/codebeltnet/globalization/compare/v10.0.4...v10.0.5 [10.0.4]: https://github.com/codebeltnet/globalization/compare/v10.0.3...v10.0.4 [10.0.3]: https://github.com/codebeltnet/globalization/compare/v10.0.2...v10.0.3 diff --git a/Directory.Packages.props b/Directory.Packages.props index 0d3a494..fbc9d4a 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -3,9 +3,9 @@ true - - - + + +