Skip to content

Commit a278c92

Browse files
rohityanrohityan
authored
Merge branch 'main' into fix/3246-vertex-v1-api-option
2 parents 48e84f7 + 0f90ff4 commit a278c92

78 files changed

Lines changed: 6515 additions & 990 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/adk-unit-design/SKILL.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
name: adk-unit-design
3+
description: Creates or updates code unit design documents for source code documentation.
4+
---
5+
6+
# ADK Code Unit Design
7+
8+
This skill creates or updates a detailed software engineering design document for new or updated code file or specified code unit. The design document it generates is meant to explain the code to a developer who wants to modify or extend the code unit as part of the ADK development framework. Similar to a *unit test*, a *unit design* provides a generated software engineering design based on the *actual, implemented code* rather than any proposed code design or proposed software architecture.
9+
10+
## Input
11+
12+
- Code files containing new functionality
13+
- Names of new methods and classes (optional)
14+
- Code files for base classes or interfaces that the new functionality depends on (optional)
15+
- Code unit tests (optional)
16+
- Example code files (optional)
17+
18+
## Analysis
19+
20+
- Review specified code files for changes and named methods to determine:
21+
- Purpose and intended use of the new or updated code units
22+
- Any data flows handled by the new or updated code units
23+
- Dependencies required by the new or updated code units
24+
- Approaches for extending or customizing the code unit to add new capabilities
25+
- Classes that depend on the new or updated code units
26+
- Operational limitations of the new or updated code units
27+
28+
## Output
29+
30+
- Look for an existing design document in the `/docs/design/***` directory of this repository.
31+
- If a design already exists, update the existing design incrementally and prioritize preserving the previous content as much as possible.
32+
- If no design document exists, create a design file for the new code unit in the `/docs/design/***` directory of this repository, using the relative path of the code unit. For example, if the code unit is called `/topic/function/class.ext`, create a design document in the location `/docs/design/topic/function/class/index.md`.
33+
- Any links to local code files should be translated to URL links to the `google/adk-python` repository on GitHub. For example, if the local code unit path is `***/adk-python/topic/function/class.ext#L93`, the URL to the code file should be `https://github.com/google/adk-python/blob/main/topic/function/class.ext#L93`.
34+
35+
### Design document structure and content
36+
37+
Use the following structure and instructions to create the design document for the code unit:
38+
39+
```
40+
# (name of code unit or code file) - Code Unit Design
41+
42+
- 2-sentence summary of the code unit
43+
44+
## Introduction
45+
46+
- Paragraph(s) explaining:
47+
- The purpose and application of the code unit, including intended use cases
48+
- Developer problems solved by this code unit
49+
- Agent capabilities enabled by this code unit
50+
51+
## High-level architecture
52+
53+
- Describe the software architecture of this code unit and how it fits into the larger ADK framework
54+
- Explain general execution flow of this code unit
55+
- Describe any data flows handled by the code unit including inputs and outputs
56+
- Explain any cross-class dependencies of the code unit, including upstream dependencies and downstream dependencies
57+
58+
### Extension points
59+
60+
- Describe how the code unit could be extended or customized to add new features or capabilities
61+
- Note specific parts of the code unit that are designed to be extended or customized, including:
62+
- Abstract classes
63+
- Interfaces
64+
- Hooks
65+
- Callbacks
66+
- Configurable parameters
67+
- Plugin architecture
68+
- Other extension points
69+
70+
### Extension constraints
71+
72+
- Describe what parts of the code unit should not be modified, based on:
73+
- architectural constraints
74+
- implementation limitations
75+
- cross-class dependencies
76+
- other constraints
77+
78+
## Limitations
79+
80+
- Mention any limitations of the code unit, if known, such as:
81+
- input constraints
82+
- data structure constraints
83+
- output constraints
84+
- performance limitations
85+
- memory limitations
86+
- other limitations
87+
88+
```

‎.github/workflows/release-cherry-pick.yml‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,29 +12,43 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15-
# Step 3 (optional): Cherry-picks a commit from main to the release/candidate branch.
16-
# Use between step 1 and step 4 to include bug fixes in an in-progress release.
15+
# Step 3 (optional): Cherry-picks a commit from a base branch (main or v1) into the active release candidate branch.
16+
# Use this between step 1 and step 4 to include hotfixes in an in-progress release.
1717
# Note: Does NOT auto-trigger release-please to preserve manual changelog edits.
1818
name: "Release: Cherry-pick"
1919

2020
on:
2121
workflow_dispatch:
2222
inputs:
23+
branch:
24+
description: 'Branch line of the release candidate (main or v1)'
25+
required: true
26+
default: 'main'
27+
type: choice
28+
options:
29+
- main
30+
- v1
2331
commit_sha:
2432
description: 'Commit SHA to cherry-pick'
2533
required: true
26-
type: string
27-
28-
permissions:
29-
contents: write
3034

3135
jobs:
3236
cherry-pick:
3337
runs-on: ubuntu-latest
3438
steps:
39+
- name: Determine Branch Configurations
40+
id: config
41+
run: |
42+
BRANCH="${{ inputs.branch }}"
43+
if [ "$BRANCH" = "v1" ]; then
44+
echo "candidate_branch=release/v1-candidate" >> $GITHUB_OUTPUT
45+
else
46+
echo "candidate_branch=release/candidate" >> $GITHUB_OUTPUT
47+
fi
48+
3549
- uses: actions/checkout@v6
3650
with:
37-
ref: release/candidate
51+
ref: ${{ steps.config.outputs.candidate_branch }}
3852
fetch-depth: 0
3953

4054
- name: Configure git
@@ -44,14 +58,16 @@ jobs:
4458
4559
- name: Cherry-pick commit
4660
run: |
47-
echo "Cherry-picking ${INPUTS_COMMIT_SHA} to release/candidate"
61+
CANDIDATE_BRANCH="${{ steps.config.outputs.candidate_branch }}"
62+
echo "Cherry-picking ${INPUTS_COMMIT_SHA} to $CANDIDATE_BRANCH"
4863
git cherry-pick ${INPUTS_COMMIT_SHA}
4964
env:
5065
INPUTS_COMMIT_SHA: ${{ inputs.commit_sha }}
5166

5267
- name: Push changes
5368
run: |
54-
git push origin release/candidate
55-
echo "Successfully cherry-picked commit to release/candidate"
56-
echo "Note: Release Please is NOT auto-triggered to preserve manual changelog edits."
57-
echo "Run release-please.yml manually if you want to regenerate the changelog."
69+
CANDIDATE_BRANCH="${{ steps.config.outputs.candidate_branch }}"
70+
git push origin "$CANDIDATE_BRANCH"
71+
echo "Successfully cherry-picked commit to $CANDIDATE_BRANCH"
72+
echo "If you want to regenerate the changelog PR, run the 'Release: Cut' workflow manually"
73+
echo "with action='regenerate' and branch='${{ inputs.branch }}'."

‎.github/workflows/release-cut.yml‎

Lines changed: 72 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -12,49 +12,98 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15-
# Step 1: Starts the release process by creating a release/candidate branch.
16-
# Generates a changelog PR for review (step 2).
15+
# Unified release manager. Supports:
16+
# 1. Cutting a new release candidate branch from main or v1.
17+
# 2. Regenerating/updating the changelog PR on an existing candidate branch.
1718
name: "Release: Cut"
1819

1920
on:
2021
workflow_dispatch:
2122
inputs:
23+
action:
24+
description: 'Action to perform'
25+
required: true
26+
default: 'cut'
27+
type: choice
28+
options:
29+
- cut
30+
- regenerate
31+
branch:
32+
description: 'Branch to release from (main or v1)'
33+
required: true
34+
default: 'main'
35+
type: choice
36+
options:
37+
- main
38+
- v1
2239
commit_sha:
23-
description: 'Commit SHA to cut from (leave empty for latest main)'
40+
description: 'Optional Commit SHA (only used for "cut" action; overrides branch latest)'
2441
required: false
2542
type: string
2643

2744
permissions:
2845
contents: write
29-
actions: write
46+
pull-requests: write
3047

3148
jobs:
32-
cut-release:
49+
cut-or-regenerate:
3350
runs-on: ubuntu-latest
3451
steps:
35-
- uses: actions/checkout@v6
52+
- name: Determine Branch Configurations
53+
id: config
54+
run: |
55+
BRANCH="${{ inputs.branch }}"
56+
if [ "$BRANCH" = "v1" ]; then
57+
echo "base_ref=v1" >> $GITHUB_OUTPUT
58+
echo "candidate_branch=release/v1-candidate" >> $GITHUB_OUTPUT
59+
echo "config_file=.github/release-please-config-v1.json" >> $GITHUB_OUTPUT
60+
echo "manifest_file=.github/.release-please-manifest-v1.json" >> $GITHUB_OUTPUT
61+
else
62+
echo "base_ref=main" >> $GITHUB_OUTPUT
63+
echo "candidate_branch=release/candidate" >> $GITHUB_OUTPUT
64+
echo "config_file=.github/release-please-config.json" >> $GITHUB_OUTPUT
65+
echo "manifest_file=.github/.release-please-manifest.json" >> $GITHUB_OUTPUT
66+
fi
67+
68+
# Action: CUT NEW RELEASE
69+
- name: Checkout base ref (Cut)
70+
if: inputs.action == 'cut'
71+
uses: actions/checkout@v6
3672
with:
37-
ref: ${{ inputs.commit_sha || 'main' }}
73+
ref: ${{ inputs.commit_sha || steps.config.outputs.base_ref }}
74+
token: ${{ secrets.RELEASE_PAT }}
3875

39-
- name: Check for existing release/candidate branch
40-
env:
41-
GH_TOKEN: ${{ github.token }}
76+
- name: Check for existing candidate branch (Cut)
77+
if: inputs.action == 'cut'
4278
run: |
43-
if git ls-remote --exit-code --heads origin release/candidate &>/dev/null; then
44-
echo "Error: release/candidate branch already exists"
45-
echo "Please finalize or delete the existing release candidate before starting a new one"
79+
CANDIDATE_BRANCH="${{ steps.config.outputs.candidate_branch }}"
80+
if git ls-remote --exit-code --heads origin "$CANDIDATE_BRANCH" &>/dev/null; then
81+
echo "Error: Branch $CANDIDATE_BRANCH already exists."
82+
echo "Please finalize or delete the existing release candidate before starting a new one."
4683
exit 1
4784
fi
4885
49-
- name: Create and push release/candidate branch
86+
- name: Create and push candidate branch (Cut)
87+
if: inputs.action == 'cut'
5088
run: |
51-
git checkout -b release/candidate
52-
git push origin release/candidate
53-
echo "Created branch: release/candidate"
89+
CANDIDATE_BRANCH="${{ steps.config.outputs.candidate_branch }}"
90+
git checkout -b "$CANDIDATE_BRANCH"
91+
git push origin "$CANDIDATE_BRANCH"
92+
echo "Created and pushed branch: $CANDIDATE_BRANCH"
5493
55-
- name: Trigger Release Please
56-
env:
57-
GH_TOKEN: ${{ github.token }}
58-
run: |
59-
gh workflow run release-please.yml --repo ${{ github.repository }} --ref release/candidate
60-
echo "Triggered Release Please workflow"
94+
# Action: REGENERATE EXISTING PR
95+
- name: Checkout existing candidate branch (Regenerate)
96+
if: inputs.action == 'regenerate'
97+
uses: actions/checkout@v6
98+
with:
99+
ref: ${{ steps.config.outputs.candidate_branch }}
100+
token: ${{ secrets.RELEASE_PAT }}
101+
102+
# Run Release Please
103+
- name: Run Release Please
104+
uses: googleapis/release-please-action@v4
105+
with:
106+
token: ${{ secrets.RELEASE_PAT }}
107+
config-file: ${{ steps.config.outputs.config_file }}
108+
manifest-file: ${{ steps.config.outputs.manifest_file }}
109+
target-branch: ${{ steps.config.outputs.candidate_branch }}

‎.github/workflows/release-finalize.yml‎

Lines changed: 37 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,16 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15-
# Step 4: Triggers when the changelog PR is merged to release/candidate.
16-
# Records last-release-sha and renames release/candidate to release/v{version}.
15+
# Triggers automatically when the changelog PR is merged to a candidate branch.
16+
# Records the last-release-sha for Release Please and renames the branch to release/v{version}.
1717
name: "Release: Finalize"
1818

1919
on:
2020
pull_request:
2121
types: [closed]
2222
branches:
2323
- release/candidate
24+
- release/v1-candidate
2425

2526
permissions:
2627
contents: write
@@ -43,18 +44,33 @@ jobs:
4344
echo "is_release_pr=false" >> $GITHUB_OUTPUT
4445
fi
4546
47+
- name: Determine Branch Configurations
48+
if: steps.check.outputs.is_release_pr == 'true'
49+
id: config
50+
run: |
51+
CANDIDATE_BRANCH="${{ github.event.pull_request.base.ref }}"
52+
if [ "$CANDIDATE_BRANCH" = "release/v1-candidate" ]; then
53+
echo "base_branch=v1" >> $GITHUB_OUTPUT
54+
echo "config_file=.github/release-please-config-v1.json" >> $GITHUB_OUTPUT
55+
echo "manifest_file=.github/.release-please-manifest-v1.json" >> $GITHUB_OUTPUT
56+
else
57+
echo "base_branch=main" >> $GITHUB_OUTPUT
58+
echo "config_file=.github/release-please-config.json" >> $GITHUB_OUTPUT
59+
echo "manifest_file=.github/.release-please-manifest.json" >> $GITHUB_OUTPUT
60+
fi
61+
4662
- uses: actions/checkout@v6
4763
if: steps.check.outputs.is_release_pr == 'true'
4864
with:
49-
ref: release/candidate
65+
ref: ${{ github.event.pull_request.base.ref }}
5066
token: ${{ secrets.RELEASE_PAT }}
5167
fetch-depth: 0
5268

5369
- name: Extract version from manifest
5470
if: steps.check.outputs.is_release_pr == 'true'
5571
id: version
5672
run: |
57-
VERSION=$(jq -r '.["."]' .github/.release-please-manifest.json)
73+
VERSION=$(jq -r '.["."]' "${{ steps.config.outputs.manifest_file }}")
5874
echo "version=$VERSION" >> $GITHUB_OUTPUT
5975
echo "Extracted version: $VERSION"
6076
@@ -70,21 +86,28 @@ jobs:
7086
- name: Record last-release-sha for release-please
7187
if: steps.check.outputs.is_release_pr == 'true'
7288
run: |
73-
git fetch origin main
74-
CUT_SHA=$(git merge-base origin/main HEAD)
75-
echo "Release was cut from main at: $CUT_SHA"
89+
BASE_BRANCH="${{ steps.config.outputs.base_branch }}"
90+
CONFIG_FILE="${{ steps.config.outputs.config_file }}"
91+
CANDIDATE_BRANCH="${{ github.event.pull_request.base.ref }}"
92+
93+
git fetch origin "$BASE_BRANCH"
94+
CUT_SHA=$(git merge-base "origin/$BASE_BRANCH" HEAD)
95+
echo "Release was cut from $BASE_BRANCH at: $CUT_SHA"
96+
7697
jq --arg sha "$CUT_SHA" '. + {"last-release-sha": $sha}' \
77-
.github/release-please-config.json > tmp.json && mv tmp.json .github/release-please-config.json
78-
git add .github/release-please-config.json
79-
git commit -m "chore: update last-release-sha for next release"
80-
git push origin release/candidate
98+
"$CONFIG_FILE" > tmp.json && mv tmp.json "$CONFIG_FILE"
99+
100+
git add "$CONFIG_FILE"
101+
git commit -m "chore: update last-release-sha for next $BASE_BRANCH release"
102+
git push origin "$CANDIDATE_BRANCH"
81103
82-
- name: Rename release/candidate to release/v{version}
104+
- name: Rename candidate to release/v{version}
83105
if: steps.check.outputs.is_release_pr == 'true'
84106
run: |
85107
VERSION="v${STEPS_VERSION_OUTPUTS_VERSION}"
86-
git push origin "release/candidate:refs/heads/release/$VERSION" ":release/candidate"
87-
echo "Renamed release/candidate to release/$VERSION"
108+
CANDIDATE_BRANCH="${{ github.event.pull_request.base.ref }}"
109+
git push origin "$CANDIDATE_BRANCH:refs/heads/release/$VERSION" ":$CANDIDATE_BRANCH"
110+
echo "Renamed $CANDIDATE_BRANCH to release/$VERSION"
88111
env:
89112
STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
90113

0 commit comments

Comments
 (0)