mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-21 17:16:16 +08:00
Marc Schier
0f710adc8e
# Description This PR is a documentation overhaul for OPC UA .NET Standard 2.0. It splits the monolithic `Docs/MigrationGuide.md` into per-version sub-docs (so a coding agent can load only the relevant section), adds a new "What's New in 2.0" landing doc, rewrites `Docs/Profiles.md` and the repo-root `README.md` to reflect what master actually implements, and renames the misnamed `Docs/ALiasNames.md` to `Docs/AliasNames.md`. The branch is `docupdates` and contains **6 commits** stacked on top of `master`. All changes are doc-only except for `HelpLinkUri` string updates in `Opc.Ua.MigrationAnalyzer` (all 119 analyzer tests still pass × 5 TFMs). ## What changed ### `Docs/MigrationGuide.md` is now a thin landing page Before: a single ~144 KB / 1,549-line document covering 22 distinct migration topics in one file. After: a small 3.8 KB / 64-line landing page that introduces general principles, lists a per-version table, and keeps the tiny `1.05.377 → 1.05.378` and `1.04 → 1.05` legacy sections inline. The 1.5.378 → 2.0 content moves to a new **`Docs/migrate/2.0.x/`** folder with a README index plus 12 thematic sub-docs, mapped 1-to-1 to the existing H3 sections: | Sub-doc | Folded H3 sections | | --- | --- | | `telemetry.md` | Telemetry and Logging | | `packages.md` | Package, Target Framework and Dependency Changes | | `source-generation.md` | Source Generation | | `types.md` | Improved Type safety | | `encoders.md` | Encodeable Factory + Encoders/Decoders + Complex Types | | `node-states.md` | Node States + INodeCache changes | | `identity.md` | User Identity Token Handlers + User Identity Providers + Secrets | | `certificates.md` | Certificate Management + ICertificateProvider | | `configuration.md` | Configuration + Session/Browser State Persistence | | `sessions-subscriptions.md` | GDS Client API modernisation + ManagedSession + Subscriptions/Transports | | `alarms-model-change.md` | Alarms and Conditions + Address-space model change tracking | | `timeprovider.md` | Time and Timer abstraction (TimeProvider) | Each sub-doc starts with a **"When to read this"** lead paragraph (analyzer rules / symptoms / API areas it covers) and ends with a sibling-links footer. `Docs/migrate/2.0.x/README.md` has a symptom → sub-doc index table reused as-is in the agent skill. ### `opcua-v20-migration` agent skill is now context-efficient `.agents/skills/opcua-v20-migration/SKILL.md` gains a "Migration sub-doc index — load only what you need" section near the top with an explicit *"Do not load `Docs/MigrationGuide.md` into context"* instruction and a table keyed by symptom / API area / analyzer rule ID, so an agent loads at most one sub-doc per migration scenario. Path references in `README.md`, `references/analyzer-rules.md`, `references/migration-patterns.md`, and `references/source-generator.md` are updated to point at the new sub-doc locations. ### New `Docs/WhatsNewIn2.0.md` Developer-facing narrative tour of the 1.5.378 → 2.0 delta (~320 lines, hybrid grouping: cross-cutting themes first — type system & immutability, async/cancellation/TimeProvider, DI & hosting, Native AOT, source generators, companion specs Part 9/11/13/16/17/18/20/100 + WoT + LDS, performance, security — then by layer: Server, Client/Sessions/Subscriptions, PubSub, GDS, Tooling, CI). Paragraph per feature, no PR/commit references, links to the deeper per-feature docs. Linked from `Docs/README.md` between `Profiles.md` and `MigrationGuide.md`. ### `Docs/Profiles.md` rewritten to reflect master Adds Functional Facets for newly-implemented features (Part 9 Alarms, Part 11 Historical Access, Part 13 Aggregates, Part 16 State Machines, Part 17 Alias Names, Part 18 Role Management, Part 20 FileSystem server, Part 100 Device Integration / Software Update, OPC 10100-1 WoT, Node Management, Local Discovery Server, Auditing, Model Change Tracking). Expands Client Profiles (classic `Session` vs `ManagedSession`, V2 subscription engine, `FileSystemClient`, `HistoryClient`, `AlarmClient`, NodeSet export, source-generated typed `ObjectType` proxies). Adds a Reference Applications section listing all of `Applications/*` (Quickstarts/Ctt/Mono configs, Reference Client, LDS, MCP, Minimal* / Pump* samples). Security policies and transport profiles confirmed against `Stack/Opc.Ua.Core/Security/Constants/*` — no changes needed there. For new facets whose canonical URI could not be confidently verified against `profiles.opcfoundation.org` (the registry is fully SPA-rendered), the doc describes the facet by name and points readers at the OPC Foundation registry rather than fabricating URIs. The `ServerProfileArray` in the reference-server configs is intentionally left unchanged to avoid CTT-compliance regressions from advertising an unverified URI. ### Repo-root `README.md` cleaned up Front page now makes the 2.0 / `master378` context explicit. New 5-section structure with one emoji per heading: 🆕 version callout → 📦 What it is → 🚀 Getting started (grouped sample list linking to each sample's own README) → 🔧 Migrating from 1.5.378 → 🤝 Contributing & license → 📚 Further reading. Removes the "New in 1.04.368 / 1.05.373 / .374 / .375 / .376 / .378 / 2.0" laundry list, the dated "Key Features and Updates in OPC UA 1.05" section, inline VS / `dotnet run` build instructions, the "Start the server" walkthrough, the "Remarks" (self-signed certs + LDS) notes, and the inaccurate `.NET Standard 2.1` overview claim. Trims the 11 status badges down to 5 essentials (release, NuGet downloads, build, tests, codecov). ### File rename — `Docs/ALiasNames.md` → `Docs/AliasNames.md` The on-disk filename had a stray capital `L` while every link in `Docs/README.md`, `Docs/Profiles.md`, etc. used the lowercase spelling. Renamed via case-only `git mv` (Windows two-step). Existing links across the docs now resolve on GitHub's case-sensitive filesystem. ### `Opc.Ua.MigrationAnalyzer` `HelpLinkUri` updates - `Tools/Opc.Ua.MigrationAnalyzer/Diagnostics/DiagnosticIds.cs` — `HelpLinkUriBase` repointed from `Docs/MigrationGuide.md#` to `Docs/migrate/2.0.x/README.md#` so the rule-ID help links land on the symptom → sub-doc index instead of a generic landing page. - `Tools/Opc.Ua.MigrationAnalyzer/Diagnostics/DiagnosticDescriptors.cs` — UA0021 / UA0022 message strings reference the new `Docs/migrate/2.0.x/certificates.md`. - `Tools/Opc.Ua.MigrationAnalyzer/Analyzers/UA0021CertificateValidatorRenameAnalyzer.cs` — XML-doc path updated. - `Tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md` and `AnalyzerReleases.Unshipped.md` — references repointed. ## Verification - `Opc.Ua.MigrationAnalyzer` builds with **0 Warning(s), 0 Error(s)** in Release. - `Opc.Ua.MigrationAnalyzer.Tests`: **119/119 tests pass × 5 TFMs** (net48, net472, net8.0, net9.0, net10.0). - `ConsoleReferenceServer` builds with **0 Warning(s), 0 Error(s)** in Release on net10.0 (verifies the reference-server config XML still parses cleanly after our doc-touching). - **Every relative markdown link** in the new / changed docs (the new `Docs/migrate/2.0.x/*`, `Docs/MigrationGuide.md`, `Docs/WhatsNewIn2.0.md`, `Docs/Profiles.md`, `Docs/Sessions.md`, `Docs/IdentityProviders.md`, the agent skill files, and the new `README.md`) was walked programmatically — **0 broken links**. - Deep heading anchors verified to match GitHub-generated slugs (`MigrationGuide.md#encoders-and-decoders`, `Sessions.md#1-session--the-opc-ua-session-primitive`, `Sessions.md#3-managedsession--the-connection-state-machine-facade`, `migrate/2.0.x/identity.md#user-identity-providers`, `migrate/2.0.x/identity.md#user-identity-token-handlers`, `migrate/2.0.x/encoders.md#encoders-and-decoders`, `migrate/2.0.x/node-states.md#inodecache-changes`, `migrate/2.0.x/certificates.md#certificatemanager-and-segregated-interfaces`, `migrate/2.0.x/sessions-subscriptions.md#managedsession-and-automatic-reconnection`). - No `ALiasNames` (capital L) references remain anywhere in the repo (case-sensitive search). ## Commit history (6 commits) 1. `548d0b5ed` — Docs: rename `ALiasNames.md` to `AliasNames.md` 2. `8a8db8c30` — Docs: add `WhatsNewIn2.0.md` (1.5.378 → 2.0 highlights) 3. `e69b2169e` — Docs: rewrite `Profiles.md` to reflect master implementation 4. `5fb8a282b` — Merge remote-tracking branch `origin/master` into `docupdates` (resolves overlap with #3854's `Docs/Subscriptions.md` rename of `StreamingSubscription.md`) 5. `d853fbc74` — Docs: split `MigrationGuide.md` into per-version sub-docs (#3745) 6. `65d6e6851` — Docs: rewrite repo-root `README.md` for 2.0 ## Related Issues - Fixes #3745 (MigrationGuide.md document structure) ## Checklist - [x] I have signed the [CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf) and read the [CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md) doc. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. *(N/A — documentation change; existing `Opc.Ua.MigrationAnalyzer.Tests` (119 tests × 5 TFMs) still pass after the `DiagnosticDescriptors` / `DiagnosticIds` text updates.)* - [x] I have added all necessary documentation. *(this PR is the documentation; all internal links verified)* - [x] I have verified that my changes do not introduce (new) build or analyzer warnings. *(both `Opc.Ua.MigrationAnalyzer` and `ConsoleReferenceServer` build with 0 warnings / 0 errors)* - [ ] I ran **all** tests locally using the **UA.slnx** solution against at least .net **framework** and .net **10**, and all passed. *(only the migration-analyzer test suite was rerun, since this PR is doc + a few `HelpLinkUri` strings; full UA.slnx run pending CI)* - [ ] I fixed **all** failing and flaky tests in the CI pipelines and **all** CodeQL warnings. *(pending CI)* - [ ] I have addressed **all** PR feedback received.