| name | azure-ai-projects-update-changelog |
| license | MIT |
| metadata | {"version":"1.0.0","distribution":"local"} |
| description | Update CHANGELOG.md by comparing public APIs between the current branch and the latest released version on PyPI. WHEN: "update changelog", "generate changelog", "add changelog entry", "what changed in this version". DO NOT USE FOR: other Azure SDK packages. INVOKES: PyPI API, GitHub API (for tags), file operations. |
| compatibility | {"requires":"local azure-sdk-for-python clone, git, internet access"} |
Update azure-ai-projects Changelog
This skill guides Copilot through updating the CHANGELOG.md file for the azure-ai-projects package by comparing public APIs between the current branch and the latest released version.
Working directory: sdk/ai/azure-ai-projects
Overview
The skill performs these steps:
- Read the current version from
azure/ai/projects/_version.py
- Fetch the latest released version from PyPI
- Compare public classes, methods, and properties between current branch and released version
- Update CHANGELOG.md with a new section or update the existing "(Unreleased)" section
Step 1: Read the current version
Read the current version from azure/ai/projects/_version.py. The file contains a line like:
VERSION = "X.Y.Z"
Extract this version number and save it as CURRENT_VERSION.
Step 2: Fetch the latest released version from PyPI
Use the PyPI JSON API to get the latest released version:
https://pypi.org/pypi/azure-ai-projects/json
From the JSON response:
- Extract
info.version as LATEST_PYPI_VERSION
- This is the version we will compare against
Step 3: Determine if CHANGELOG needs updating
Check if CHANGELOG.md already has a section for the current version:
- If there's a section
## {CURRENT_VERSION} (Unreleased) — we will update it
- If there's a section
## {CURRENT_VERSION} (YYYY-MM-DD) with an actual date. If the date is in the past, then this version is already released, report this to the user and stop. If it's today's date, we will update it.
- If there's no section for
CURRENT_VERSION — we will create a new one
Step 4: Construct the GitHub tag for the released version
The tag name for a released version follows this pattern:
azure-ai-projects_{VERSION}
For example, for version 2.2.0, the tag is azure-ai-projects_2.2.0.
The source code for that release can be found at:
https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-projects_{VERSION}/sdk/ai/azure-ai-projects
Step 5: Compare public APIs
Compare the public APIs between the current branch and the latest released version. Focus on these locations:
5a. Public classes and enums in azure/ai/projects/models/__init__.py
Compare the __all__ list and imports in both versions to identify:
- New classes/enums: Present in current branch but not in released version
- Removed classes/enums: Present in released version but not in current branch
- Renamed classes/enums: Check if a removed class has a similar new class (likely a rename)
5b. Public operations in azure/ai/projects/operations/__init__.py
Compare the __all__ list to identify new or removed operation classes.
5c. Public methods on sub-clients
For each operations class (like AgentsOperations, BetaOperations, etc.), compare the public methods:
- Look at files under
azure/ai/projects/operations/ and azure/ai/projects/aio/operations/
- Also check
_patch.py files which may define additional public methods
- Public methods are those that don't start with underscore
_
5d. Properties on model classes
For significant model classes, compare public properties (attributes) between versions:
- Properties are defined in
azure/ai/projects/models/_models.py
- Look for new, removed, or renamed properties
- Pay attention to required vs optional changes
5e. Beta sub-clients on BetaOperations
The BetaOperations class exposes beta/preview functionality. Check for:
- New sub-client properties (like
.beta.datasets, .beta.models, .beta.routines, etc.)
- Removed sub-client properties
- Check both
azure/ai/projects/operations/_patch.py and the released version
5f. Sample files in samples/ folder
Compare sample files between the current branch and the released version:
- List all
.py files recursively under samples/ in both versions
- Identify new samples: Files present in current branch but not in released version
- Identify removed samples: Files present in released version but not in current branch
- Ignore async variants: If a sample has both sync and async versions (e.g.,
sample_foo.py and sample_foo_async.py), only report the sync version
- Check existing changelog entries: If a sample is already mentioned in the current changelog section, leave it as is
- Remove stale entries: If a sample mentioned in the changelog has been removed from the codebase, remove it from the changelog
For each new sample, provide a one-line description of what it demonstrates. Read the sample file to understand its purpose — typically the docstring at the top or the if __name__ == "__main__" block explains what it does.
Step 6: Categorize the changes
Organize detected changes into these categories:
Features Added
- New sub-clients (e.g., "New
.beta.routines sub-client with routine operations: create_or_update, get, enable, ...")
- New methods on existing sub-clients (e.g., "New methods on
.beta.agents for optimization jobs: create_optimization_job, get_optimization_job, ...")
- New model classes that represent significant features (e.g., "Support integration of external Agents. See new
ExternalAgentDefinition class.")
- New properties on existing classes (e.g., "New optional
force parameter on agents.delete method.")
- New tools (e.g., "New Agent tool in preview
FabricIQPreviewTool.")
Breaking Changes
List breaking changes in beta methods and classes separately:
- Renamed methods (e.g., "Method
.beta.agents.get_session_files renamed to .beta.agents.list_session_files.")
- Renamed arguments (e.g., "Argument
body in method .beta.skills.create_from_files() renamed to content.")
- Signature changes (e.g., "Method
.beta.skills.create signature changed — now takes name and keyword inline_content: SkillInlineContent; returns SkillVersion.")
- Renamed classes (e.g., "Renamed class
AgentEndpoint to AgentEndpointConfig.")
- Property changes (e.g., "Required property
isolation_key_source removed from class EntraAuthorizationScheme.")
- Renamed properties (e.g., "Property
skill_id renamed to id on class SkillDetails.")
Format for beta changes:
Breaking changes in beta methods:
* ...
Breaking changes in beta classes:
* ...
Bugs Fixed
This section typically contains bug fixes. Leave empty unless you have specific bug fix information to add.
Sample updates
List new sample files that were added, with a one-line description of what they demonstrate:
- Compare sample files in the
samples/ folder between current branch and released version
- Only report the sync version — do not list async samples separately (files ending with
_async.py)
- If a sample is already mentioned in the existing changelog section, preserve that entry
- If a sample mentioned in the changelog has been removed from the codebase, remove it from the changelog
- Group related samples together (e.g., all agent samples, all evaluation samples)
- Use format:
Added \sample_name.py` demonstrating [brief description].`
Step 7: Format the changelog entry
Use this format for the changelog entry:
## {CURRENT_VERSION} (Unreleased)
### Features Added
* [List each feature on its own bullet point]
### Breaking Changes
Breaking changes in beta methods:
* [List method changes]
Breaking changes in beta classes:
* [List class changes]
### Bugs Fixed
* [List bug fixes, if any]
### Sample updates
* [List sample updates, if any]
Guidelines for writing entries:
- For new methods: mention the sub-client and method name, briefly describe what it does. Only report the sync version — do not list both sync and async versions separately.
- For new sub-clients: list all the methods it provides (sync versions only)
- For new tools: just mention the class name
- For property changes: mention the class name and the affected property
- For renames: show "X renamed to Y" format
- Use backticks for code references:
.beta.agents, create_version(), AgentDetails
Step 8: Update CHANGELOG.md
Insert or update the changelog entry in CHANGELOG.md:
-
If updating an existing "(Unreleased)" section:
- Replace the existing section content with the new content
- Preserve any manually-added entries that aren't API-related (like "Sample updates" written by developers)
-
If creating a new section:
- Insert the new section immediately after the
# Release History header
- Keep all previous version sections intact
Step 9: Report to user
After updating the changelog, report:
- The current version and latest PyPI version compared
- Summary of changes detected:
- Number of new classes/enums
- Number of new methods
- Number of breaking changes
- Number of removed items
- Remind the user to:
- Review the generated changelog for accuracy
- Add any bug fixes that were made
- Review sample descriptions for accuracy
- Verify method descriptions are accurate
Tips for API Comparison
Using git to compare files
You can compare files between the current branch and a tag:
git diff azure-ai-projects_{VERSION} -- azure/ai/projects/models/__init__.py
Using GitHub raw URLs
To fetch files from the released version:
https://raw.githubusercontent.com/Azure/azure-sdk-for-python/azure-ai-projects_{VERSION}/sdk/ai/azure-ai-projects/azure/ai/projects/models/__init__.py
Identifying renames vs additions/removals
If a class was removed and a similar class was added, it's likely a rename. Look for:
- Similar names (e.g.,
SkillObject → SkillDetails)
- Similar structure/properties
- Check if there's a corresponding note in the TypeSpec changes
Example Output
Here's an example of a well-formatted changelog entry:
## 2.3.0 (Unreleased)
### Features Added
* Support integration of external Agents (in preview). See new `ExternalAgentDefinition` class.
* New Agent tool in preview `FabricIQPreviewTool`.
* New Agent tool in preview `ToolboxSearchPreviewTool`.
* New methods on `.beta.agents` for
* Code-based hosted agents: `create_version_from_code`, `download_code`.
* Optimization jobs: `create_optimization_job`, `get_optimization_job`, `list_optimization_jobs`, `cancel_optimization_job`, `list_optimization_candidates`.
* Optimization candidate management: `list_optimization_candidates`, `get_optimization_candidate`, `get_optimization_candidate_config`, `get_optimization_candidate_results`, `get_candidate_file`, `promote_candidate`.
* `stop_session` to stop a running agent session.
* New `.beta.datasets` sub-client with data generation job operations: `create_generation_job`, `get_generation_job`, `list_generation_jobs`, `cancel_generation_job`, `delete_generation_job`.
* New `.beta.models` sub-client to handle AI model weights: `create`, `list_versions`, `list`, `get`, `delete`, `update`, `pending_create_version`, `pending_upload`, .
New sub-client with routine operations: , , , , , , , .
New methods on for evaluator generation jobs: , , , , .
New methods on to handle individual memory items: , , , , .
New methods on for versioned skill management: , , , , .
New optional string properties and added to Agent tools classes which did not have them before.
New optional added to Agent tool classes.
New read-only property on , returning the SHA-256 hex digest of the uploaded code zip.
New optional parameter on and methods.
New optional parameters on method.
Breaking changes in beta methods:
Argument in methods and renamed to .
Argument in methods and renamed to .
Argument in method renamed to .
Method renamed to .
Method signature changed — now takes and keyword ; returns .
Method renamed to .
Method signature changed — now takes and ; returns .
Method signature changed — now only accepts keyword ; returns .
Breaking changes in beta classes:
Required property removed from class .
Renamed class to .
Renamed class to .
Renamed class to .
Renamed class to .
Renamed class to . Property renamed to . Properties and were removed.
Renamed class to .
Renamed class to .
Fixed telemetry instrumentor to correctly call isagentiq.pysampleworkasync.pyWorkIQPreviewTool`.
Added new Agent tool samples and demonstrating use of .
Hosted Agents:
Added Hosted Agent creation samples and , demonstrating hosted agent version creation and retrieval with .
Added Hosted Agent code-upload samples and , demonstrating uploading a code package (zip) as a new hosted agent version.
The Hosted Agent creation sample also demonstrates assigning the hosted agent managed identity the Azure AI User RBAC role on the backing Azure AI account.
Updated the other Hosted Agent samples to reuse an existing Hosted Agent as a prerequisite, instead of creating a new hosted agent version in each sample.
Added Toolbox tool-search sample and , demonstrating creating a Toolbox version with and invoking .
Added samples under :
— synchronous end-to-end registration via the helper (uses ), followed by , , , , , and .
— alternative synchronous registration that hand-rolls the spec's three-step flow ( → upload via → + poll), without taking a dependency on .
— asynchronous version of the same three-step flow using and .
Added new evaluation sample demonstrating model evaluation with an instant model.
Refreshed evaluation samples under and (including , , , , , , , , , , , , , , , , , , , and ).
New sample showing an end-to-end flow that generates a QnA dataset via and runs an OpenAI evaluation.
