Better changlog syntax, agent instructions

Author: andystaples

.github/copilot-instructions.md

@@ -8,6 +8,17 @@ building durable orchestrations. The repo contains two packages:
 - `durabletask` — core SDK (in `durabletask/`)
 - `durabletask.azuremanaged` — Azure Durable Task Scheduler provider (in `durabletask-azuremanaged/`)
 
+## Changelog Requirements
+
+- ALWAYS document user-facing changes in the appropriate changelog under
+  `## Unreleased`.
+- Update `CHANGELOG.md` for core SDK changes and
+  `durabletask-azuremanaged/CHANGELOG.md` for provider changes.
+- If a change affects both packages, update both changelogs.
+- Do NOT document internal-only changes in changelogs, including CI/workflow
+  updates, test-only changes, refactors with no user-visible behavior change,
+  and implementation details that do not affect public behavior or API.
+
 ## Language and Style
 
 - Python 3.10+ is required.

.github/skills/release-prep/SKILL.md

@@ -52,9 +52,12 @@ Update azuremanaged dependency floors:
 - Add a new `## v<version>` section directly under `## Unreleased` in:
   - `CHANGELOG.md`
   - `durabletask-azuremanaged/CHANGELOG.md`
-- Ensure all commits since the previous release tags are represented.
+- Ensure user-facing changes since the previous release tags are represented.
 - Keep entries concise and grouped by type (`ADDED`, `CHANGED`, `FIXED`, `REMOVED`) where
   applicable.
+- Exclude internal-only changes from changelogs (for example CI/workflow-only
+  updates, test-only changes, and implementation refactors with no public
+  behavior or API impact).
 
 ### 4. Validate
 
@@ -96,6 +99,8 @@ Include:
 - Contributor handles from the commit range
 - Keep drafts in the assistant response (or PR comment) so they can be pasted
   directly into the Releases section
+- Keep the release body focused on user-facing changes and avoid internal-only
+  details (CI/test updates or implementation-only notes)
 
 
 ## Output

CHANGELOG.md

@@ -117,72 +117,72 @@ FIXED:
 
 ## v0.3.0
 
-### New (v0.3.0)
+ADDED
 
 - Added `ConcurrencyOptions` class for fine-grained concurrency control with separate limits for activities and orchestrations. The thread pool worker count can also be configured.
 
-### Fixed (v0.3.0)
+FIXED
 
 - Fixed an issue where a worker could not recover after its connection was interrupted or severed
 
 ## v0.2.1
 
-### New (v0.2.1)
+ADDED
 
 - Added `set_custom_status` orchestrator API ([#31](https://github.com/microsoft/durabletask-python/pull/31)) - contributed by [@famarting](https://github.com/famarting)
 - Added `purge_orchestration` client API ([#34](https://github.com/microsoft/durabletask-python/pull/34)) - contributed by [@famarting](https://github.com/famarting)
 - Added new `durabletask-azuremanaged` package for use with the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) - by [@RyanLettieri](https://github.com/RyanLettieri)
 
-### Changes (v0.2.1)
+CHANGED
 
 - Protos are compiled with gRPC 1.62.3 / protobuf 3.25.X instead of the latest release. This ensures compatibility with a wider range of grpcio versions for better compatibility with other packages / libraries ([#36](https://github.com/microsoft/durabletask-python/pull/36)) - by [@berndverst](https://github.com/berndverst)
 - Http and grpc protocols and their secure variants are stripped from the host name parameter if provided. Secure mode is enabled if the protocol provided is https or grpcs ([#38](https://github.com/microsoft/durabletask-python/pull/38) - by [@berndverst)(https://github.com/berndverst)
 - Improve ProtoGen by downloading proto file directly instead of using submodule ([#39](https://github.com/microsoft/durabletask-python/pull/39) - by [@berndverst](https://github.com/berndverst)
 
-### Updates (v0.2.1)
+CHANGED
 
 - Updated `durabletask-protobuf` submodule reference to latest
 
 ## v0.1.1a1
 
-### New (v0.1.1a1)
+ADDED
 
 - Add recursive flag in terminate_orchestration to support cascade terminate ([#27](https://github.com/microsoft/durabletask-python/pull/27)) - contributed by [@shivamkm07](https://github.com/shivamkm07)
 
 ## v0.1.0
 
-### New (v0.1.0)
+ADDED
 
 - Retry policies for activities and sub-orchestrations ([#11](https://github.com/microsoft/durabletask-python/pull/11)) - contributed by [@DeepanshuA](https://github.com/DeepanshuA)
 
-### Fixed (v0.1.0)
+FIXED
 
 - Fix try/except in orchestrator functions not being handled correctly ([#21](https://github.com/microsoft/durabletask-python/pull/21)) - by [@cgillum](https://github.com/cgillum)
 - Updated `durabletask-protobuf` submodule reference to latest distributed tracing commit - by [@cgillum](https://github.com/cgillum)
 
 ## v0.1.0a5
 
-### New (v0.1.0a5)
+ADDED
 
 - Adds support for secure channels ([#18](https://github.com/microsoft/durabletask-python/pull/18)) - contributed by [@elena-kolevska](https://github.com/elena-kolevska)
 
-### Fixed (v0.1.0a5)
+FIXED
 
 - Fix zero argument values sent to activities as None ([#13](https://github.com/microsoft/durabletask-python/pull/13)) - contributed by [@DeepanshuA](https://github.com/DeepanshuA)
 
 ## v0.1.0a3
 
-### New (v0.1.0a3)
+ADDED
 
 - Add gRPC metadata option ([#16](https://github.com/microsoft/durabletask-python/pull/16)) - contributed by [@DeepanshuA](https://github.com/DeepanshuA)
 
-### Changes (v0.1.0a3)
+CHANGED
 
 - Removed Python 3.7 support due to EOL ([#14](https://github.com/microsoft/durabletask-python/pull/14)) - contributed by [@berndverst](https://github.com/berndverst)
 
 ## v0.1.0a2
 
-### New (v0.1.0a2)
+ADDED
 
 - Continue-as-new ([#9](https://github.com/microsoft/durabletask-python/pull/9))
 - Support for Python 3.7+ ([#10](https://github.com/microsoft/durabletask-python/pull/10)) - contributed by [@DeepanshuA](https://github.com/DeepanshuA)