Add comprehensive README to Microsoft.Maui.Controls NuGet package by Copilot · Pull Request #32835 · dotnet/maui

Copilot · 2025-11-24T15:23:36Z

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description of Change

Adds a high-quality README to the Microsoft.Maui.Controls NuGet package following Microsoft's official guidelines. The README will render on NuGet.org's package page.

Changes:

Created /src/Controls/src/NuGet/README.md with:
- Uses product name ".NET MAUI" throughout (not package name)
- NuGet version and License badges (build status badge removed)
- Feature overview (40+ controls, XAML, layouts, navigation, data binding, theming)
- Platform support matrix (Android, iOS, iPadOS, macOS, Windows with minimum versions)
- Getting started guide (installation, project creation, platform-specific run commands)
- Run commands for all platforms: Android, iOS, Mac Catalyst, and Windows
- Quick start section with code example and links to official tutorials
- Key features sections with code snippets AND documentation links:
  - MVVM and Data Binding (code example + comprehensive guides)
  - XAML Enhancements (code examples + compilation, markup extensions, hot reload docs)
  - Shell Navigation (code example + overview, routing, tabs guides)
  - Collections and Lists (CollectionView and CarouselView code examples + docs - ListView removed as obsolete)
  - Responsive Layouts (Grid code example + layout guides)
- Documentation links (Microsoft Learn, API reference, samples, tutorials)
- Support channels (Stack Overflow, GitHub issues, official .NET Discord, community MAUIverse Discord, security reporting)
- Community resources (X/Twitter, YouTube)
- Contributing guidelines and related packages
Updated Controls.NuGet.csproj with:
- PackageReadmeFile property
- ItemGroup to pack README into NuGet package

Structure modeled after OpenAI .NET SDK README.

The README provides a balanced approach with both code snippets for quick start and documentation links for comprehensive learning with visual examples. All documentation links are clean URLs without version markers or local identifiers.

Issues Fixed

Fixes #31969

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

src/Controls/src/NuGet/README.md

jfversluis · 2025-11-24T16:07:40Z

@copilot lets not call it .NET MAUI Controls, although the package is called like that, lets just refer to the product name: .NET MAUI

Copilot · 2025-11-24T16:20:00Z

@copilot lets not call it .NET MAUI Controls, although the package is called like that, lets just refer to the product name: .NET MAUI

Updated to use the product name ".NET MAUI" instead of ".NET MAUI Controls" in the title and section headers. Changes committed in bef71ee.

src/Controls/src/NuGet/README.md

jfversluis · 2025-11-24T19:42:50Z

@copilot address comments

Copilot

Pull request overview

This PR adds a comprehensive, high-quality README.md to the Microsoft.Maui.Controls NuGet package following Microsoft's official guidelines. The README will be displayed on NuGet.org's package page, providing users with essential information about .NET MAUI, getting started instructions, code examples, and community resources.

Key Changes:

Created a professional README following the structure of the OpenAI .NET SDK README as a model
Includes badges, platform support matrix, getting started guide, code examples, and documentation links
Updated Controls.NuGet.csproj to include the README in the NuGet package

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/Controls/src/NuGet/README.md	Comprehensive 291-line README with .NET MAUI overview, supported platforms, installation instructions, quick start examples, key features, documentation links, and community resources
src/Controls/src/NuGet/Controls.NuGet.csproj	Added `PackageReadmeFile` property and `ItemGroup` to pack README.md into the NuGet package

src/Controls/src/NuGet/README.md

jfversluis · 2025-12-05T10:47:39Z

@copilot address comment

github-actions · 2025-12-08T20:22:51Z

Started backporting to release/10.0.1xx-sr2 (link to workflow run)

PureWeen · 2025-12-08T22:07:51Z

/rebase

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

…s, update Discord/social links Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Kartheek Penagamuri <kapenaga@microsoft.com>

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

@PureWeen

…trols NuGet package (#33059) Backport of #32835 to release/10.0.1xx-sr2 /cc @PureWeen @Copilot

src/Controls/src/NuGet/README.md

PureWeen · 2025-12-11T17:13:37Z

/backport to release/10.0.1xx-sr2

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>

* Initial plan * Initial plan for syncing PR #32835 to sr2 branch Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com> * Sync PR #32835 platform requirements to match main branch Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com> * Delete src/Core/src/Handlers/HybridWebView/HybridWebView.js.map --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com> Co-authored-by: Shane Neuville <shneuvil@microsoft.com>

… guidance (#33196) - [x] Update Circle sample to use Location/Distance objects instead of string Center and numeric Radius - [ ] Validation (doc-only change; no automated tests run)   <details> <summary>Original prompt</summary> > Take what you did for #32835 and apply it to the Maps NuGet as well. You can add the README in the root of the Maps project folder and link it from there. Make sure it gives a good description on how to get started with the Maps APIs. You can also find more information here: https://learn.microsoft.com/dotnet/maui/user-interface/controls/map?view=net-maui-10.0 make sure to also link there from this README. The README should be part of the NuGet package. </details>  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com> Co-authored-by: Shane Neuville <shneuvil@microsoft.com>

Copilot AI assigned Copilot and jfversluis Nov 24, 2025

Copilot started work on behalf of jfversluis November 24, 2025 15:27 View session

Copilot AI changed the title ~~[WIP] Improve the MAUI NuGet readme.md file~~ Add comprehensive README to Microsoft.Maui.Controls NuGet package Nov 24, 2025

Copilot AI requested a review from jfversluis November 24, 2025 15:46

Copilot finished work on behalf of jfversluis November 24, 2025 15:46

jfversluis reviewed Nov 24, 2025

View reviewed changes

src/Controls/src/NuGet/README.md Outdated Show resolved Hide resolved

Copilot started work on behalf of jfversluis November 24, 2025 16:08 View session

Copilot AI requested a review from jfversluis November 24, 2025 16:21

Copilot finished work on behalf of jfversluis November 24, 2025 16:21

jfversluis reviewed Nov 24, 2025

View reviewed changes

Copilot started work on behalf of jfversluis November 24, 2025 19:43 View session

Copilot finished work on behalf of jfversluis November 24, 2025 19:58

Copilot AI requested a review from jfversluis November 24, 2025 19:58

jfversluis marked this pull request as ready for review November 30, 2025 07:16

jfversluis requested review from PureWeen and Copilot November 30, 2025 07:16

Copilot started reviewing on behalf of jfversluis November 30, 2025 07:17 View session

Copilot finished reviewing on behalf of jfversluis November 30, 2025 07:19

Copilot AI reviewed Nov 30, 2025

View reviewed changes

src/Controls/src/NuGet/README.md Show resolved Hide resolved

src/Controls/src/NuGet/README.md Outdated Show resolved Hide resolved

PureWeen requested a review from davidortinau November 30, 2025 15:35

kartheekp-ms reviewed Dec 5, 2025

View reviewed changes

src/Controls/src/NuGet/README.md Outdated Show resolved Hide resolved

pictos reviewed Dec 5, 2025

View reviewed changes

src/Controls/src/NuGet/README.md Show resolved Hide resolved

Copilot started work on behalf of jfversluis December 5, 2025 08:33 View session

Copilot finished work on behalf of jfversluis December 5, 2025 08:43

Copilot started work on behalf of jfversluis December 5, 2025 10:48 View session

github-actions bot mentioned this pull request Dec 8, 2025

[release/10.0.1xx-sr2] Add comprehensive README to Microsoft.Maui.Controls NuGet package #33059

Merged

Copilot AI and others added 10 commits December 8, 2025 22:08

Initial plan

9dcf4c3

Add comprehensive README for Microsoft.Maui.Controls NuGet package

a79d598

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Update src/Controls/src/NuGet/README.md

9a2ebae

Change title to use product name .NET MAUI instead of .NET MAUI Controls

84eb50e

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Address PR feedback: Update Background property, add XAML enhancement…

f7ef51e

…s, update Discord/social links Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Update src/Controls/src/NuGet/README.md

7398c6a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/Controls/src/NuGet/README.md

3181b90

Co-authored-by: Kartheek Penagamuri <kapenaga@microsoft.com>

Add Mac Catalyst run command and replace code examples with doc links

e9f095a

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Add code snippets alongside doc links and remove ListView reference

7fdae5b

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Remove build status badge from README

0883dbf

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

github-actions bot force-pushed the copilot/improve-maui-nuget-readme branch from 1508a5c to 0883dbf Compare December 8, 2025 22:08

PureWeen added a commit that referenced this pull request Dec 8, 2025

[release/10.0.1xx-sr2] Add comprehensive README to Microsoft.Maui.Con…

3c9214e

…trols NuGet package (#33059) Backport of #32835 to release/10.0.1xx-sr2 /cc @PureWeen @Copilot

jfversluis reviewed Dec 9, 2025

View reviewed changes

src/Controls/src/NuGet/README.md Outdated Show resolved Hide resolved

PureWeen previously approved these changes Dec 11, 2025

View reviewed changes

Update src/Controls/src/NuGet/README.md

57e9c3a

jfversluis dismissed PureWeen’s stale review via 57e9c3a December 11, 2025 15:22

PureWeen approved these changes Dec 11, 2025

View reviewed changes

jfversluis merged commit c6edcd2 into main Dec 11, 2025
67 of 148 checks passed

jfversluis deleted the copilot/improve-maui-nuget-readme branch December 11, 2025 16:16

Copilot AI mentioned this pull request Dec 11, 2025

Sync PR #32835 platform requirements to release/10.0.1xx-sr2 #33125

Merged

Copilot AI added a commit that referenced this pull request Dec 11, 2025

Initial plan for syncing PR #32835 to sr2 branch

72e531f

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>

Copilot AI added a commit that referenced this pull request Dec 11, 2025

Sync PR #32835 platform requirements to match main branch

9c19a30

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>

Copilot AI mentioned this pull request Dec 17, 2025

Add packaged README for Microsoft.Maui.Controls.Maps with quick start guidance #33196

Merged

2 tasks

github-actions bot locked and limited conversation to collaborators Jan 11, 2026

Conversation

Copilot AI commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Issues Fixed

Uh oh!

Uh oh!

jfversluis commented Nov 24, 2025

Uh oh!

Copilot AI commented Nov 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jfversluis commented Nov 24, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jfversluis commented Dec 5, 2025

Uh oh!

github-actions bot commented Dec 8, 2025

Uh oh!

PureWeen commented Dec 8, 2025

Uh oh!

Uh oh!

Uh oh!

PureWeen commented Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Nov 24, 2025 •

edited

Loading