build: update release cadence

[hallvictoria]

Purpose

• Release on changes to src/
  • Only release for functionality changes - not on updates to documentation or pipeline
  • Ignore __init__.py updates - prevent circular releases
  • Auto-updates the version to + b (n+1). Auto-triggered releases only support releasing beta version. Major / minor updates must be done manually.
• Minor default value updates
• Address minor comments from previous PR

Does this introduce a breaking change?

[ ] Yes
[ ] No

Pull Request Type

What kind of change does this Pull Request introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Documentation content changes
[ ] Other... Please describe:

How to Test

• Get the code

git clone https://github.com/Azure/azure-functions-agents-runtime.git
cd azure-functions-agents-runtime
git checkout [branch-name]
pip install -e .

• Test the code

What to Check

Verify that the following are valid

• ...

Other Information

[larohra]

Review Summary

Overall this is a reasonable release-cadence update, but the config-docs auto-generation piece has one critical dead-code bug that should be fixed before merge:

🔴 Critical

• generate_config_reference.py imports new *_DESCRIPTIONS dicts from schema.py, but they're immediately shadowed by pre-existing local dict literals later in the same file — the import has zero effect on generated docs (verified empirically with a marker-string test). See inline comment for details and the fix path.

🟡 Suggestions

• The new schema.py description dicts are also stale/incomplete relative to the local copies they're meant to replace (missing web_request/workflows entries) — worth reconciling now while fresh, since it'll block the eventual cleanup of the dead local dicts.
• docs/AUTO_GENERATION.md now tells contributors to edit schema.py for descriptions, which is misleading until the above is actually fixed.
• versionPattern's default was narrowed to double-quotes-only, inconsistent with the template it calls (which still supports both quote styles) — likely fine today but worth confirming it's intentional.
• Re: the cross-stage variable propagation (also flagged in the existing comment on the Build stage below) — it's not just boilerplate, build-artifacts.yml/publish-release.yml genuinely need libraryVersion before checkout. But ResolveVersion could be folded into BumpVersion's job as its first step, dropping one stage's pool spin-up and trimming the repeated stageDependencies blocks from 3 copies to 2. See inline comment for specifics.

🟢 Looks good

• The new trigger/pr: none block is a well-justified fix for unwanted default-branch pipeline triggers.

Happy to help with the fix for the dead-code issue if useful.

[larohra]

🔴 Critical — these imports have zero effect (dead code)

Lines 47–59 import description dictionaries from schema.py, but the same names are redefined as local dict literals later in this file (e.g. GLOBAL_CONFIG_DESCRIPTIONS at line 241, SYSTEM_TOOLS_CONFIG_DESCRIPTIONS at 255, WEB_REQUEST_DESCRIPTIONS at 265, AGENT_SPEC_OPTIONAL_DESCRIPTIONS at 283, SYSTEM_TOOLS_AGENT_DESCRIPTIONS at 311, etc.). Since Python executes module-level statements top-to-bottom, those later literals silently overwrite the imports before generate_markdown() ever reads them.

Verified empirically: injecting a marker string into schema.py's GLOBAL_CONFIG_DESCRIPTIONS["model"] and regenerating docs/front-matter-reference.md produced no change in the output.

Contrast with TRIGGER_TYPES = schema.TRIGGER_TYPES (line 43) — that name is not redefined later, which is the correct pattern. The new dicts need the same treatment: delete the local literals at lines 241–326 once schema.py is confirmed to have equivalent content (see comment on schema.py — a few keys are currently missing there).

Not caught by ruff (F811/F841 don't fire on plain module-level reassignment) or the --check CI gate (the generated output happens to be unaffected either way, since the local dicts already had correct content).

[larohra]

This line now tells contributors to "edit the appropriate description dictionary in schema.py" to change field descriptions — but per the dead-code issue in generate_config_reference.py (see comment there), edits to schema.py's *_DESCRIPTIONS dicts currently have no effect on the generated docs; the old local dicts in generate_config_reference.py are still what's actually used. Recommend holding this doc update until the migration is completed, or reverting it for now to avoid misleading contributors.

[larohra]

Stale/incomplete copies — these new dicts look like a snapshot taken before main's web_request system tool (#96) merged in, and they're missing entries the still-active local copies in generate_config_reference.py already have:

• SYSTEM_TOOLS_CONFIG_DESCRIPTIONS (here, line 259) is missing "web_request" (present in the local copy at generate_config_reference.py:256)
• SYSTEM_TOOLS_AGENT_DESCRIPTIONS (line 305) is missing "web_request" (local copy at generate_config_reference.py:313)
• AGENT_SPEC_OPTIONAL_DESCRIPTIONS (line 278) is missing "workflows" (local copy at generate_config_reference.py:293)
• WEB_REQUEST_DESCRIPTIONS isn't defined here at all (only exists locally at generate_config_reference.py:265-271)

Because of the shadowing issue this doesn't matter yet — but it will block the "obvious" fix of just deleting the local duplicates, since that would drop these entries from the generated docs. Worth porting them over now while this is fresh.

[larohra]

🟡 Suggestion

This narrows versionPattern's default from matching both quote styles (['\"]) to double-quotes-only ([\"]). The template this feeds, bump-version.yml, still defaults to the dual-quote pattern — so the two are now inconsistent. Harmless today since src/azure_functions_agents/__init__.py uses double quotes, but the PR description ("Minor default value updates") doesn't call out an intentional reason for the narrowing. Consider reverting to the original dual-quote pattern for robustness unless this was deliberate.

[larohra]

🟡 Suggestion (related to the dependsOn comment below on the Build stage)

The version-resolution logic is a single ~40-line PowerShell step in its own stage, whose output then has to be re-declared via stageDependencies.ResolveVersion... in three downstream stages (BumpVersion line 148, Build line 169, Release line 186) — each also needs ResolveVersion added directly to dependsOn, since Azure Pipelines only exposes stageDependencies to direct dependencies.

This plumbing is genuinely necessary, not just boilerplate — I checked build-artifacts.yml/publish-release.yml and both need libraryVersion before checkout (to pick which release/{version} branch to clone), so it can't be replaced by reading the version file after checkout.

One easy simplification though: move this step to be the first step of BumpVersion's job instead of its own stage. That removes an entire stage's pool/agent spin-up (~30-90s) and reduces the repeated stageDependencies block from 3 copies to 2 (Build/Release would reference BumpVersion's output instead of ResolveVersion's).