You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a7e5010
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .github/skills/typespec-python-release/SKILL.md
+47-31Lines changed: 47 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,31 +10,31 @@ Prepare a release PR for `@azure-tools/typespec-python` from the repository root
10
10
## Requirements
11
11
12
12
- Run every command from the repository root.
13
-
- Use the current date in `YYYY-MM-DD` format for the branch name.
14
13
- Release only `@azure-tools/typespec-python`.
15
-
- Do not overwrite an existing branch.
14
+
- Use the task branch supplied by the environment when available. Do not require a particular branch name or ask the user to choose one.
15
+
- Do not delete or overwrite an existing branch.
16
+
- Use any available authenticated integration to publish the branch and create the pull request; do not assume GitHub CLI is installed or authenticated.
16
17
17
18
## Workflow
18
19
19
-
### 1. Clean the Repository and Create the Branch
20
+
### 1. Prepare the Repository and Task Branch
20
21
21
-
1. Clean the repository and update `main` with this exact sequence:
22
+
1. If the environment has already supplied a task branch (for example, a cloud agent branch), work on that branch and skip the cleanup and checkout sequence below. Preserve existing task changes.
23
+
2. Otherwise, clean the repository and update `main` with this exact sequence:
22
24
23
25
```bash
24
26
git reset HEAD && git checkout .&& git clean -fd && git checkout origin/main && git pull origin main
25
27
```
26
28
27
29
This intentionally discards all uncommitted tracked and untracked files. Run it only when the user has asked to start the release workflow.
28
30
29
-
2. Create the publish branch from the clean, updated `origin/main` checkout using the current date:
31
+
3. If no task branch was supplied, create a new branch from the clean, updated `origin/main` checkout. Choose an unused branch name without asking the user; do not delete or overwrite existing local or remote branches.
32
+
4. Record the actual task branch name for publishing and PR verification:
30
33
31
34
```bash
32
-
release_date=$(date +%F)
33
-
git switch -c "publish/python-${release_date}"
35
+
release_branch=$(git branch --show-current)
34
36
```
35
37
36
-
If the branch already exists locally or remotely, stop and ask the user whether to reuse it or choose another date. Do not delete or overwrite it.
37
-
38
38
### 2. Update `@typespec/http-client-python`
39
39
40
40
1. Read the latest published version from npm:
@@ -60,7 +60,7 @@ Prepare a release PR for `@azure-tools/typespec-python` from the repository root
60
60
pnpm chronus version --only @azure-tools/typespec-python
61
61
```
62
62
63
-
3. Read the package version again. If Chronus changed it, use the generated changelog entry and do not add another one.
63
+
3. Check Chronus's exit status and inspect its changes before reading the package version again. If it fails, report the error and investigate any partial changes; do not treat a partial version bump as a successful release. If it left the package and changelog unchanged, continue with the manual fallback below. If Chronus succeeds and changed the version, use the generated changelog entry and do not add another one.
64
64
4. If Chronus did not change it:
65
65
- Increment only the patch component in `packages/typespec-python/package.json`, from `a.b.c` to `a.b.(c+1)`.
66
66
- Add this entry immediately below `# Release` in `packages/typespec-python/CHANGELOG.md`. The heading is the new `@azure-tools/typespec-python` package version; the bullet uses `$latest_http_client_python`. These versions are independent and are usually different:
@@ -73,51 +73,67 @@ Prepare a release PR for `@azure-tools/typespec-python` from the repository root
73
73
74
74
5. If the manual fallback was used, confirm the final package version is exactly one patch version above the recorded version. Otherwise, confirm Chronus versioned only `@azure-tools/typespec-python`.
75
75
76
-
### 4. Update and Validate the Lockfile
76
+
### 4. Update Documentation and Validate the Lockfile
77
77
78
78
1. Update dependencies and `pnpm-lock.yaml`:
79
79
80
80
```bash
81
81
pnpm install
82
82
```
83
83
84
-
2. Inspect `git diff --check`, `git diff --stat`, and `git status --short`.
85
-
3. Verify the release includes only expected files:
84
+
2. After installation, build the Python emitter and its workspace dependencies, then regenerate documentation only for `packages/typespec-python`. The dependency build is required in fresh worktrees, where the documentation script's package-only build otherwise fails with missing workspace module declarations. Run these commands from the repository root; `--dir` runs the documentation script in the Python package:
Replace the placeholders with the final package version and dependency version. Inspect `.chronus/changes/` to verify that the command actually created a valid change file; an exit status of zero is not sufficient. Chronus can print `No package changed. Exiting.` and create no file when the release edits are still uncommitted. If the command fails or creates no valid file, report the outcome and manually create a uniquely named `.md` file under `.chronus/changes/` if needed, using this format:
98
+
99
+
```markdown
100
+
---
101
+
changeKind: internal
102
+
packages:
103
+
- "@azure-tools/typespec-python"
104
+
---
105
+
106
+
Release @azure-tools/typespec-python <version> with @typespec/http-client-python <latest-http-client-python-version>.
107
+
```
108
+
109
+
Verify the file has `changeKind: internal` and lists only `@azure-tools/typespec-python`. Do not rerun Chronus versioning after adding it; the file must remain in the release PR.
110
+
111
+
4. Inspect `git diff --check`, `git diff --stat`, and `git status --short`.
112
+
5. Verify the release includes only expected files:
86
113
- `pnpm-workspace.yaml`, when its dependency range changed
3. Publish the actual task branch using an available authenticated mechanism, such as Git, an MCP integration, or the cloud agent's publishing workflow. Use a personal fork when required by repository permissions. Do not assume the remote is named `origin` or the branch follows a particular naming convention.
135
+
4. Create a pull request against `Azure/typespec-azure`, targeting `main` from the published task branch, with the exact title `[python] release <version>` and an empty body. Choose an available authenticated tool or integration; GitHub CLI is optional. If publishing or PR creation is unavailable, stop and report the blocker so the user can finish.
136
+
5. Verify the created pull request's repository, base and head branches, exact title, empty body, and inclusion of the new `internal` change file using the available integration.
Copy file name to clipboardExpand all lines: eng/scripts/doc-updater/knowledge/azure-resource-manager.md
+12-4Lines changed: 12 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -156,20 +156,28 @@ The former multi-purpose `arm-resource-operation` checks are represented by thre
156
156
157
157
Concrete ARM resource identities are seeded only by registered read or createOrUpdate operations with valid ARM resource instance paths. List, action, update, delete, and check-existence operations can attach to an existing resolved resource but do not create resource identities by themselves.
158
158
159
+
Identity paths are matched case-insensitively for literal segments and by position for variable segments. A createOrUpdate operation can establish a resource without a read operation; list-only and action-only operation sets cannot.
160
+
159
161
## ARM Request and Response Rules
160
162
161
163
-`no-query-in-collection` allows only `api-version` and case-sensitive `$filter` on collection GET operations.
162
-
-`no-query-in-point-op` allows only `api-version` on point GET, PUT, PATCH, and DELETE operations.
164
+
-`no-query-in-point-op` allows only `api-version`(case-insensitively) on GET, PUT, PATCH, and DELETE resource-instance paths.
163
165
-`no-query-in-post` allows only `api-version` on POST operations; other inputs belong in the request body.
164
-
-`list-operation-missing-pageable` requires collection GET operations to use TypeSpec paging metadata with a continuation link.
166
+
-`list-operation-missing-pageable` requires collection GET operations to use TypeSpec paging metadata with a continuation link. Standard ARM list operation templates supply this metadata.
165
167
-`list-response-envelope` requires collection GET response models to contain exactly `value` and `nextLink`.
166
168
-`use-application-json-content-type` requires `application/json` request and response bodies in ARM provider namespaces.
167
169
-`use-model-request-body` requires non-multipart request bodies to use plain models without indexers.
168
170
-`no-tenant-level-apis` reports ARM PUT routes beginning with `/providers`, except the `/operations` endpoint.
169
171
-`lro-response-mismatch` validates that PUT and PATCH final results match the resource type, DELETE final results are `void`, and POST final results match successful response bodies.
170
172
173
+
When these rules are added or promoted, update both the generated linter reference and the manually maintained rule evaluation and RPC coverage guides.
174
+
171
175
The `lro-response-mismatch` implementation has a detailed adjacent Markdown file but no `docs` association in its TypeScript rule definition. Consequently, `pnpm regen-docs` generates only its short description. Fixing the association requires an edit under `packages/typespec-azure-resource-manager/src/rules/`.
172
176
173
-
## Relationship Documentation Feedback
177
+
## Feature Files
178
+
179
+
The internal `getFeatureFileSet` accessor returns the enum configured by `@featureFiles`, or `undefined` when the decorator is absent. The `arm-feature-file-usage-discourage` rule tests for `undefined`; an empty or otherwise falsey-looking enum state still represents configured feature files.
180
+
181
+
## Documentation Feedback
174
182
175
-
Use the defaults from `...ResourceNameParameter<RelationshipModel>` unless the API truly requires custom key, segment, or pattern values. Link to canonical samples through the published samples site (`https://azure.github.io/typespec-azure/docs/samples/...`) rather than the repository source tree.
183
+
Use rendered documentation URLs for canonical sample links and link to canonical samples through the published samples site (`https://azure.github.io/typespec-azure/docs/samples/...`) rather than the repository source tree. In examples, omit every template argument that is equal to its declared default, including inferred `ResourceNameParameter` key, segment, and name-pattern values.
0 commit comments