dotnet · twsouthwick · Dec 16, 2025 · Dec 10, 2025 · Dec 10, 2025 · Dec 10, 2025
diff --git a/.github/agents/changelog.agent.md b/.github/agents/changelog.agent.md
@@ -0,0 +1,72 @@
+---
+name: changelog-maintainer
+description: Identify changes since last release and update CHANGELOG.md
+tools: ['edit/editFiles', 'search', 'list_tags', 'get_release_by_tag', 'get_latest_release', 'list_commits', 'search_pull_requests', 'search_issues', 'fetch']
+---
+
+# Changelog Creator Instructions
+
+You are a changelog creator assistant. Your role is to systematically identify changes since the last release and update the CHANGELOG.md file following the project's established format.
+
+## Your Process
+
+1. **Identify the Last Release**
+   - Use #tool:list_tags to find the most recent release tag
+   - Use #tool:github/get_release_by_tag or #tool:github/get_latest_release to get release details and date
+   - Note the release date and version number
+
+2. **Gather Changes Since Last Release**
+   - Use #tool:github/search_pull_requests to search for merged pull requests since that date
+   - Use #tool:github/search_issues to search for closed issues that were fixed
+   - Collect information about:
+     - Merged pull requests with their descriptions and PR numbers
+     - Closed issues that were fixed
+     - New features added
+     - Breaking changes or deprecations
+   - **Filter out infrastructure-only changes** such as:
+     - CI/CD pipeline updates
+     - Build system changes
+     - Development tooling updates
+     - Test infrastructure modifications
+     - Documentation-only updates
+     - Repository configuration changes
+   - **Review borderline changes with the user** before including them to ensure they are product-facing
+
+3. **Categorize Changes**
+   - Organize changes into these categories (following Keep a Changelog format):
+     - **Added**: New features, namespaces, methods, or functionality
+     - **Changed**: Changes to existing functionality, updates to dependencies
+     - **Fixed**: Bug fixes and issue resolutions
+     - **Deprecated**: Features marked for future removal
+     - **Removed**: Features that were removed
+     - **Security**: Security-related fixes or improvements
+
+4. **Format the Changelog Entry**
+   - Follow the existing CHANGELOG.md format:
+     - Version header: `## [X.Y.Z] - YYYY-MM-DD`
+     - Group changes by category with `### Category` headers
+     - List each change with a brief description
+      - Include PR/issue numbers in parentheses at the end of the line, with no trailing period and no extra words (for example: `Added X feature (#1234, #5678)`)
+     - Reference related issues or PRs for context
+     - Add contributor acknowledgments at the end if applicable
+
+5. **Update CHANGELOG.md**
+   - Insert the new version entry at the top of the changelog, right after the main header
+   - Ensure proper spacing and formatting matches existing entries
+   - Add the version to the links section at the bottom if needed
+   - Maintain the existing style and markdown structure
+
+## Important Guidelines
+
+- Be thorough: Review ALL commits and PRs since the last release
+- Be accurate: Verify categorization is correct (e.g., a bug fix goes under "Fixed", not "Changed")
+- Be concise: Write clear, brief descriptions that explain what changed and why it matters
+- Be consistent: Match the writing style and format of existing changelog entries
+- Include context: Reference PR/issue numbers so readers can find more details
+- Acknowledge contributors: List GitHub usernames of contributors at the end of the entry
+- **Focus on product-facing changes only**: Exclude infrastructure, build system, CI/CD, and development tooling changes unless they directly impact end users
+- **When in doubt, ask**: Present questionable changes to the user for review to confirm they should be included in the changelog
+
+## Before Making Changes
+
+Always present the proposed changelog entry to the user for review before updating the file. This ensures accuracy and allows for any necessary adjustments.
diff --git a/.github/agents/readme.agent.md b/.github/agents/readme.agent.md
@@ -0,0 +1,42 @@
+---
+name: readme-maintainer
+description: Keeps README files accurate, concise, and aligned with project and NuGet documentation.
+tools: ['edit/createFile', 'edit/editFiles', 'search']
+---
+
+You are a specialized documentation agent focused on README files in this repository.
+
+Base your behavior on the patterns established in this repo and this project’s conventions:
+
+- Focus first on the shipped packages under `src/` (`DocumentFormat.OpenXml`, `DocumentFormat.OpenXml.Framework`, `DocumentFormat.OpenXml.Linq`, and `DocumentFormat.OpenXml.Features`).
+- Keep NuGet package READMEs short and scenario-focused, similar to the existing package READMEs in `src/`.
+
+Your responsibilities:
+
+- Identify relevant README files (for example, in `src/`, `samples/`, `docs/`, and the repository root).
+- Ensure package READMEs (especially under `src/`) stay in sync with:
+  - The public Open XML SDK documentation at https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+  - The project structure and current feature set
+  - NuGet package conventions for README content
+- Keep READMEs simple, clear, and concise. Prefer short sections and bullet lists over long prose.
+- Avoid redundant content that is already clearly covered in the main docs or in other READMEs; link instead of duplicating.
+- For NuGet-focused READMEs, follow these conventions from this repository:
+  - Briefly describe what the package is for and when to use it.
+  - Summarize key scenarios or capabilities rather than providing exhaustive reference docs.
+  - Do not add install commands (such as `dotnet add package`) unless someone explicitly asks for them.
+  - Prefer lightweight samples or short code snippets only when they demonstrate a key scenario (for example, a minimal `WordprocessingDocument` sample or a simple LINQ query).
+  - Use a single "Documentation and feedback" section that links to:
+    - Official docs: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+    - The GitHub repository and any relevant samples, linking directly to the appropriate `samples/` subdirectory on GitHub (for example, https://github.com/dotnet/Open-XML-SDK/tree/main/samples/Linq)
+    - The GitHub issues page for feedback: https://github.com/dotnet/Open-XML-SDK/issues
+- Maintain consistency in tone, section ordering, and terminology across package READMEs, aligning with the existing READMEs in `src/`.
+- For the `DocumentFormat.OpenXml.Features` package, ensure its README clearly lists the main feature scenarios (paragraph ID management, random number generation as a feature, element/part change events, and shared/composed features) without going into low-level implementation details.
+
+When making changes:
+
+- Prefer small, focused edits that improve clarity, correctness, or alignment with the patterns above.
+- Preserve existing structure and style where practical instead of rewriting from scratch.
+- Do not change code, configuration, or tests unless explicitly asked; focus on documentation.
+- When unsure about behavior or APIs, look for existing docs, samples, or README patterns in this repo before inventing new patterns.
+
+Always explain briefly in your response which READMEs you inspected and what changes you made or decided not to make, so maintainers can review your work quickly.
diff --git a/.vscode/mcp.json b/.vscode/mcp.json
@@ -0,0 +1,11 @@
+{
+	"servers": {
+		"github": {
+			"type": "http",
+			"url": "https://api.githubcopilot.com/mcp",
+			"gallery": "https://1es-mcp.data.eastus.azure-apicenter.ms/workspaces/default",
+			"version": "original"
+		}
+	},
+	"inputs": []
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.4.0] - 2025-12-10
+
+### Added
+
+- Added `MediaDataPartType.Mp4` to support MP4 video media parts in presentations and documents (#1866)
+- Updated bundled Open XML schemas to the Q3 2025 Office release, enabling newer document and presentation features (#1963)
+
+### Changed
+
+- Reduced JIT and AOT size and improved document load performance by removing the generic builder pattern from element metadata creation (#1842, #1843)
+- Optimized `FromChunkedBase64String` to significantly reduce allocations and improve throughput when decoding chunked base64 content (≈2.4× faster, ≈70% less memory) (#1868)
+
+### Fixed
+
+- Switched to `XmlDOMTextWriter` instead of `XmlWriter.Create` to correctly handle serialization of certain XML content (#1869, #1961)
+- Added a clear error when attempting to open encrypted documents that the SDK cannot process (#1635, #1969)
+- Improved exception messages when required package parts are missing by including the name of the missing part (#1971, #1974)
+
+### Documentation
+
+- Clarified the README SDK description and simplified the note on 3.0.0 breaking changes (#1858)
+- Documented that disposing a package with `AutoSave` set to `false` does not persist changes (#1873)
+- Removed the PowerPoint modern comments sample, which now lives on learn.microsoft.com (#1861)
+
+Thanks to the following for their contributions:
+
+@QuocDatHoang
+@Varorbc
+
 ## [3.3.0] - 2025-03-06
 
 ### Added
@@ -83,7 +112,7 @@ Thanks to the following for their contributions:
 
 ### Added
 
-- Packages can now be saved on .NET Core and .NET 5+ if constructed with a path or stream (#1307).
+- Packages can now be saved on .NET Core and .NET 5+ if constructed with a path or stream (#1307)
 - Packages can now support malformed URIs (such as relationships with a URI such as `mailto:person@`)
 - Introduce equality comparers for `OpenXmlElement` (#1476)
 - `IFeatureCollection` can now be enumerated and has a helpful debug view to see what features are registered (#1452)
@@ -227,7 +256,7 @@ Thanks to the following for their contribution:
 - Added samples for strongly typed classes and Linq-to-XML in the `./samples` directory (#1101, #1087)
 - Shipping additional libraries for some additional functionality in `DocumentFormat.OpenXml.Features` and `DocumentFormat.OpenXml.Linq`. See documentation in repo for additional details.
 - Added extension method to support getting image part type (#1082)
-- Added generated classes and `FileFormatVersions.Microsoft365` for new subscription model types and constraints (#1097).
+- Added generated classes and `FileFormatVersions.Microsoft365` for new subscription model types and constraints (#1097)
 
 ### Fixed
 
@@ -375,7 +404,7 @@ Thanks to the following for their contributions:
 ### Added
 
 - Added `FileFormatVersions.2019` enum (#695)
-- Added `ChartSpace` and chart elements for the new 2016 namespaces. This allows the connecting pieces for building a chart part with chart styles like "Sunburst" (#687).
+- Added `ChartSpace` and chart elements for the new 2016 namespaces. This allows the connecting pieces for building a chart part with chart styles like "Sunburst" (#687)
 - Added `OpenXmlElementFunctionalExtensions.With(...)` extension methods, which offer flexible means for constructing `OpenXmlElement` instances in the context of pure functional transformations (#679)
 - Added minimum Office versions for enum types and values (#707)
 - Added additional `CompatSettingNameValues` values: `UseWord2013TrackBottomHyphenation`, `AllowHyphenationAtTrackBottom`, and `AllowTextAfterFloatingTableBreak` (#706)

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -100,12 +100,4 @@
     <IsBenchmarkProject Condition=" '$(IsBenchmarkProject)' == '' ">false</IsBenchmarkProject>
   </PropertyGroup>
 
-  <PropertyGroup>
-    <PackageReadmeFile>README.md</PackageReadmeFile>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <None Include="..\..\README.md" Pack="true" PackagePath="\"/>
-  </ItemGroup>
-
 </Project>
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
@@ -27,6 +27,7 @@
     <PackageIcon>icon.png</PackageIcon>
     <!-- For backwards compatibility. See https://aka.ms/deprecateIconUrl -->
     <PackageIconUrl>https://raw.githubusercontent.com/dotnet/Open-XML-SDK/master/icon.png</PackageIconUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -43,6 +44,10 @@
 
   <ItemGroup>
     <None Include="$(MSBuildThisFileDirectory)..\icon.png" Pack="true" PackagePath="\" />
+    <None Include="$(MSBuildProjectDirectory)\README.md"
+          Pack="true"
+          PackagePath="\"
+          Condition="Exists('$(MSBuildProjectDirectory)\\README.md')" />
   </ItemGroup>
 
   <ItemGroup>

diff --git a/src/DocumentFormat.OpenXml.Features/README.md b/src/DocumentFormat.OpenXml.Features/README.md
@@ -0,0 +1,18 @@
+# DocumentFormat.OpenXml.Features
+
+Optional feature extensions that add incremental functionality on top of the core Open XML SDK.
+
+This package is intended for advanced scenarios where you need specific feature sets layered over `DocumentFormat.OpenXml`.
+
+## Scenarios
+
+- Paragraph ID management for Word documents (generate and track unique paragraph IDs, optionally ensuring uniqueness across existing content and new paragraphs).
+- Random number generation as a reusable feature attached to an `OpenXmlPackage`, used by higher-level features such as paragraph ID generation.
+- Element and part change events so you can react when parts or elements are added, removed, or reloaded in a package.
+- Shared/composed features that aggregate the same feature type (for example, paragraph ID tracking) across multiple documents.
+
+## Documentation and feedback
+
+- Official SDK docs: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+- Source and feature examples: https://github.com/dotnet/Open-XML-SDK
+- Issues and ideas: https://github.com/dotnet/Open-XML-SDK/issues
diff --git a/src/DocumentFormat.OpenXml.Framework/README.md b/src/DocumentFormat.OpenXml.Framework/README.md
@@ -0,0 +1,15 @@
+# DocumentFormat.OpenXml.Framework
+
+Low-level infrastructure and shared primitives used by the Open XML SDK libraries.
+
+Most consumers should reference `DocumentFormat.OpenXml` (and optionally `DocumentFormat.OpenXml.Linq`) directly. This package is intended primarily for advanced scenarios and library authors extending the SDK.
+
+## Getting started
+
+Typical usage is indirect, via `DocumentFormat.OpenXml` types such as `OpenXmlElement`, `OpenXmlPart`, and related infrastructure.
+
+## Documentation and feedback
+
+- Official SDK docs: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+- Source and infrastructure details: https://github.com/dotnet/Open-XML-SDK
+- Issues and feedback: https://github.com/dotnet/Open-XML-SDK/issues
diff --git a/src/DocumentFormat.OpenXml.Linq/README.md b/src/DocumentFormat.OpenXml.Linq/README.md
@@ -0,0 +1,22 @@
+# DocumentFormat.OpenXml.Linq
+
+LINQ-friendly extensions for the Open XML SDK, providing XLINQ-based APIs for querying and transforming Open XML documents.
+
+## Getting started
+
+Basic usage with LINQ to XML:
+
+```csharp
+using (var doc = WordprocessingDocument.Open("example.docx", false))
+{
+    var xDoc = doc.MainDocumentPart!.GetXDocument();
+    var paragraphs = from p in xDoc.Descendants(W.p)
+                     select p;
+}
+```
+
+## Documentation and feedback
+
+- Official SDK docs: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+- LINQ samples: https://github.com/dotnet/Open-XML-SDK/tree/main/samples/Linq
+- Issues and suggestions: https://github.com/dotnet/Open-XML-SDK/issues
diff --git a/src/DocumentFormat.OpenXml/README.md b/src/DocumentFormat.OpenXml/README.md
@@ -0,0 +1,22 @@
+# DocumentFormat.OpenXml
+
+The core Open XML SDK library for working with Office Word, Excel, and PowerPoint documents using strongly-typed .NET APIs.
+
+## Getting started
+
+Create a simple Word document:
+
+```csharp
+using (var doc = WordprocessingDocument.Create("example.docx", WordprocessingDocumentType.Document))
+{
+    var mainPart = doc.AddMainDocumentPart();
+    mainPart.Document = new Document(new Body(new Paragraph(new Run(new Text("Hello, Open XML!")))));
+}
+```
+
+## Documentation and feedback
+
+- Official SDK docs: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
+- Source: https://github.com/dotnet/Open-XML-SDK
+- Samples: https://github.com/dotnet/Open-XML-SDK/tree/main/samples
+- Issues and feature requests: https://github.com/dotnet/Open-XML-SDK/issues