diff --git a/.github/agents/changelog.agent.md b/.github/agents/changelog.agent.md new file mode 100644 index 000000000..f6eabb4be --- /dev/null +++ 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 new file mode 100644 index 000000000..ba7a74e46 --- /dev/null +++ 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. \ No newline at end of file diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 000000000..846081bbc --- /dev/null +++ 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": [] +} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ddc78d36..bc2fc9658 100644 --- 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 index b14204e9a..e6c3bc85d 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -100,12 +100,4 @@ false - - README.md - - - - - - diff --git a/src/Directory.Build.props b/src/Directory.Build.props index ccb00dbd4..1382f5466 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -27,6 +27,7 @@ icon.png https://raw.githubusercontent.com/dotnet/Open-XML-SDK/master/icon.png + README.md @@ -43,6 +44,10 @@ + diff --git a/src/DocumentFormat.OpenXml.Features/README.md b/src/DocumentFormat.OpenXml.Features/README.md new file mode 100644 index 000000000..96c61d37f --- /dev/null +++ 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 new file mode 100644 index 000000000..1371af6cf --- /dev/null +++ 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 new file mode 100644 index 000000000..78ac5d0ea --- /dev/null +++ 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 new file mode 100644 index 000000000..662a0d326 --- /dev/null +++ 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