From 2e76a7c841c9a809bff4befce0d672757668196e Mon Sep 17 00:00:00 2001 From: David Ortinau Date: Mon, 18 Aug 2025 11:08:01 -0500 Subject: [PATCH 1/2] Pop-ups (.NET 10): switch to Async-suffixed APIs (DisplayAlertAsync, DisplayActionSheetAsync) per MAUI PR #28053; update xrefs and samples --- docs/user-interface/includes/pop-ups-dotnet10.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/user-interface/includes/pop-ups-dotnet10.md b/docs/user-interface/includes/pop-ups-dotnet10.md index 7d41dcb04..63ef5b97d 100644 --- a/docs/user-interface/includes/pop-ups-dotnet10.md +++ b/docs/user-interface/includes/pop-ups-dotnet10.md @@ -5,6 +5,8 @@ ms.date: 04/01/2025 Displaying an alert, asking a user to make a choice, or displaying a prompt is a common UI task. .NET Multi-platform App UI (.NET MAUI) has three methods on the class for interacting with the user via a pop-up: , , and . Pop-ups are rendered with native controls on each platform. +These methods are asynchronous and should be awaited to keep the UI responsive. Invoke them from UI-thread contexts (for example, page event handlers). + ## Display an alert All .NET MAUI-supported platforms have a pop-up to alert the user or ask simple questions of them. To display alerts, use the method on any . The following example shows a simple message to the user: From 8a1e6a68581b23c07505cbd90f8cfb501e1a98af Mon Sep 17 00:00:00 2001 From: David Ortinau Date: Mon, 18 Aug 2025 13:19:38 -0500 Subject: [PATCH 2/2] Repo docs: switch strategy to PRs directly against main; update branching model and keep preview drift guidance --- .github/copilot-instructions.md | 83 +++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..23d1f03cf --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,83 @@ +# Copilot working instructions: .NET 10 docs staging (docs-maui) + +This document captures our working agreements and checklists for staging .NET 10 updates in this repo. + +## Strategy overview +- We develop each docs update on a short-lived topic branch based off `main`. +- Open individual PRs targeting `main` (no long-lived net10 tracking PR). +- Keep changes small and focused by topic. + +## Branching model +- Base: `main` +- Topic branches: `pr-` or `-` + - Examples: + - `pr01-pop-ups-async-from-main` + - `pr02-mediapicker-multiselect` + - `gestures-tap-click-deprecation` +- Keep branches up-to-date by rebasing on `main` when needed. + +## Moniker guidance +- For content that differs between releases, use DocFX monikers in the top-level article and split content into include partials when it improves clarity. + - Typical pattern: + - `::: moniker range="<=net-maui-9.0"` → include `*-dotnet9.md` + - `::: moniker range=">=net-maui-10.0"` → include `*-dotnet10.md` +- If behavior/API names change in .NET 10 but guidance is otherwise similar, keep <=9 and >=10 content parallel and explicit. +- Keep phrasing and headings consistent across monikered sections to minimize diffs. + +## Quality gates (for each topic PR) +- Monikers + - Build must not emit moniker range warnings. + - Verify xrefs resolve (API names must match the targeted version). +- Samples and snippets + - Ensure code compiles in snippet harness where applicable. + - For async APIs, consistently use `await` in examples and clarify return types. +- Links + - Validate markdown links (no 404s) and image paths. +- Screenshots + - Only update if UI/API presentation changed. Otherwise, reuse. +- Review metadata + - Title/labels: “.NET 10”, “docs”, and area label. + - Reviewers: CODEOWNERS will auto-assign; add relevant owners as needed. + +## Accuracy and preview drift +- Treat the upstream `dotnet/maui` `net10.0` branch as the source of truth. Preview notes may evolve or be reverted in later previews. +- Before merging any .NET 10 docs change, verify the target API/behavior against the current `net10.0` branch: + - Confirm APIs exist (and names/overloads match) using xrefs targeting `view=net-maui-10.0` and/or MAUI source. + - Check whether a previously announced change was modified or reverted; adjust guidance and monikers accordingly. + - Include links to the upstream MAUI PR(s) or commit(s) that introduced/changed the behavior in the docs PR description. +- If behavior differs across previews, keep guidance in `<= net-maui-9.0` vs `>= net-maui-10.0` monikers accurate for GA; avoid documenting transient preview-only behavior unless explicitly called out. + +## Authoring conventions +- Use xref with wildcards for API overloads (for example, `xref:Microsoft.Maui.Controls.Page.DisplayAlertAsync%2A`). +- Prefer small, focused includes per version (e.g., `includes/pop-ups-dotnet9.md`, `includes/pop-ups-dotnet10.md`). +- Keep headings, note/warning blocks, and image alt texts aligned across versions. +- Commit messages: “Area (.NET 10): short summary; specifics”. + +## Known .NET 10 changes already staged / proposed +- Pop-ups (PR01): + - API naming in .NET 10: + - `DisplayAlertAsync` (Task / Task) + - `DisplayActionSheetAsync` (Task) + - `DisplayPromptAsync` (Task) unchanged + - Docs updated in `docs/user-interface/includes/pop-ups-dotnet10.md` to use Async-suffixed APIs and `await` consistently. +- MediaPicker (PR02): + - Multi-select: `PickPhotosAsync` / `PickVideosAsync` return `List`. + - `MediaPickerOptions` includes `SelectionLimit`, `MaximumWidth`, `MaximumHeight`, `CompressionQuality`, `RotateImage`, `PreserveMetaData`, `Title`. + - Platform notes: Android may not enforce `SelectionLimit`; Windows doesn’t support `SelectionLimit`. + +## Opening PRs +- Open PRs directly against `main`. +- PR template contents: + - Title: concise change summary and version (e.g., “Update pop-ups docs for .NET 10: async APIs and monikers”). + - Summary bullets of user-impacting changes. + - Docs touched (paths). + - Checklist: monikers, samples, links, screenshots. + - Notes on API changes (source links to MAUI PRs or release notes when relevant). + +## Maintenance +- Keep PRs small and focused; rebase/merge frequently to avoid conflicts. +- When conflicts arise in monikered pages, prioritize keeping both versioned includes accurate before deduplicating. + +--- + +Last updated: 2025-08-18