Skip to content

Commit 249d990

Browse files
VictowolfVictowolf
committed
Resolve merge conflict in release notes
2 parents 49aa68b + 4f6a8e8 commit 249d990

116 files changed

Lines changed: 2408 additions & 700 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/adding-release-notes/SKILL.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: adding-release-notes
3+
description: Adds user-facing change descriptions to DevTools release notes. Use when documenting improvements, fixes, or new features in the NEXT_RELEASE_NOTES.md file.
4+
---
5+
6+
# Adding Release Notes
7+
8+
This skill helps automate adding release notes to `packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md`.
9+
10+
## Workflow
11+
Copy this checklist into your response to track progress:
12+
13+
```markdown
14+
Release Notes Progress:
15+
- [ ] Step 1: Formulate the entry (past tense)
16+
- [ ] Step 2: Find the PR number (if not already known)
17+
- [ ] Step 3: Determine the section (Inspector, Memory, etc.)
18+
- [ ] Step 4: Add the entry (use scripts/add_note.dart)
19+
- [ ] Step 5: Add images (if applicable)
20+
```
21+
22+
## Guidelines
23+
24+
### 1. Identify the PR Number
25+
If the PR number is unknown, use the following methods to find it:
26+
- **Local Branch**: Identify the branch name using `git branch` or `git log`. If the branch is pushed to origin, it often has a linked PR.
27+
- **GitHub CLI (`gh`)**: Use the GitHub CLI to find the PR associated with the current branch.
28+
- **IMPORTANT**: Always use `PAGER=cat` to prevent `gh` from hanging in non-interactive terminals.
29+
- Command: `PAGER=cat gh pr list --head <branch_name> --json number,title`
30+
- **Search by Change Description**: Search open PRs using keywords from your change title or description.
31+
- Command: `PAGER=cat gh pr list --search "<keywords>" --limit 5`
32+
- **Web Search**: If CLI tools fail, use `search_web` to find the PR on GitHub:
33+
- Query: `site:github.com/flutter/devtools "Add support for searching within the log details view"`
34+
35+
### 2. Formulate the Entry
36+
- **Tense**: Always use **past tense** (e.g., "Added", "Improved", "Fixed").
37+
- **Punctuation**: Always end entries with a **period**.
38+
- **Template**: `* <Description>. [#<PR_NUMBER>](https://github.com/flutter/devtools/pull/<PR_NUMBER>)`
39+
- **Placeholder**: Use `TODO` if you have exhausted all search methods and the PR has not been created yet.
40+
- **Images**: If adding an image, indent it by two spaces to align with the bullet point, and ensure there is only one newline between the text and the image.
41+
- Correct Format:
42+
```markdown
43+
- Added support for XYZ. [#TODO](https://github.com/flutter/devtools/pull/TODO)
44+
![](images/my_feature.png)
45+
```
46+
- **Examples**:
47+
- `* Added support for XYZ. [#12345](https://github.com/flutter/devtools/pull/12345)`
48+
- `* Fixed a crash in the ABC screen. [#67890](https://github.com/flutter/devtools/pull/67890)`
49+
50+
### 3. User-Facing Changes Only
51+
- **Criteria**: Focus on **what** changed for the user, not **how** it was implemented.
52+
- **Avoid**: Technical details like "Implemented XYZ with a new controller", "Updated the build method", or naming internal classes.
53+
- **Example (Bad)**: `* Implemented log details search using SearchControllerMixin. [#TODO](https://github.com/flutter/devtools/pull/TODO)`
54+
- **Example (Good)**: `* Added search support to the log details view. [#TODO](https://github.com/flutter/devtools/pull/TODO)`
55+
56+
### 4. Determine Section
57+
Match the change to the section in `NEXT_RELEASE_NOTES.md`:
58+
- `General updates`
59+
- `Inspector updates`
60+
- `Performance updates`
61+
- `CPU profiler updates`
62+
- `Memory updates`
63+
- `Debugger updates`
64+
- `Network profiler updates`
65+
- `Logging updates`
66+
- `App size tool updates`
67+
- `Deep links tool updates`
68+
- `VS Code sidebar updates`
69+
- `DevTools extension updates`
70+
- `Advanced developer mode updates`
71+
72+
### 5. Add to NEXT_RELEASE_NOTES.md
73+
Use the provided utility script to insert the note safely. The script handles replacing the TODO placeholder if it's the first entry in that section.
74+
75+
```bash
76+
dart .agents/skills/adding-release-notes/scripts/add_note.dart "Inspector updates" "Added XYZ support" TODO
77+
```
78+
79+
### 6. Optional: Images
80+
Add images to `packages/devtools_app/release_notes/images/` and reference them:
81+
```markdown
82+
![Accessible description](images/screenshot.png "Hover description")
83+
```
84+
**Constraint**: Use **dark mode** for screenshots.
85+
86+
## Resources
87+
- [README.md](../../packages/devtools_app/release_notes/README.md): Official project guidance.

‎.agents/skills/adding-release-notes/scripts/add_note.dart‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Copyright 2026 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd.
4+
5+
import 'dart:io';
6+
7+
void main(List<String> args) {
8+
if (args.length < 3) {
9+
print('Usage: dart add_note.dart <section> <note> <pr_number>');
10+
exit(1);
11+
}
12+
13+
final section = args[0].trim();
14+
final note = args[1].trim();
15+
final pr = args[2].trim();
16+
17+
final prLink = pr == 'TODO'
18+
? '[TODO](https://github.com/flutter/devtools/pull/TODO)'
19+
: '[#$pr](https://github.com/flutter/devtools/pull/$pr)';
20+
21+
final filePath = 'packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md';
22+
final file = File(filePath);
23+
24+
if (!file.existsSync()) {
25+
print('Error: $filePath not found.');
26+
exit(1);
27+
}
28+
29+
var content = file.readAsStringSync();
30+
31+
if (!content.contains('## $section')) {
32+
print("Error: Section '$section' not found.");
33+
exit(1);
34+
}
35+
36+
final noteWithPeriod = note.endsWith('.') ? note : '$note.';
37+
final newEntry = '- $noteWithPeriod $prLink\n';
38+
39+
// Check for TODO placeholder.
40+
const todoText = 'TODO: Remove this section if there are not any updates.';
41+
final todoPattern = RegExp(
42+
'## ${RegExp.escape(section)}\\s*\\n\\s*${RegExp.escape(todoText)}\\s*\\n*',
43+
);
44+
45+
if (todoPattern.hasMatch(content)) {
46+
content = content.replaceFirst(todoPattern, '## $section\n\n$newEntry\n');
47+
} else {
48+
// Append to existing list in the section.
49+
final sectionHeader = '## $section';
50+
final sectionStart = content.indexOf(sectionHeader);
51+
52+
// Find the next section start or the end of the file.
53+
var nextSectionStart = content.indexOf('\n## ', sectionStart + 1);
54+
if (nextSectionStart == -1) {
55+
nextSectionStart =
56+
content.indexOf('\n# Full commit history', sectionStart + 1);
57+
}
58+
if (nextSectionStart == -1) {
59+
nextSectionStart = content.length;
60+
}
61+
62+
var sectionContent =
63+
content.substring(sectionStart, nextSectionStart).trimRight();
64+
sectionContent += '\n$newEntry';
65+
66+
content =
67+
'${content.substring(0, sectionStart)}$sectionContent\n${content.substring(nextSectionStart).trimLeft()}';
68+
}
69+
70+
file.writeAsStringSync(content);
71+
print('Successfully added note to $section.');
72+
}

‎.agents/skills/authoring-skills/CHECKLIST.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Skill Authoring Checklist
2+
3+
Copy this checklist into your response when starting the creation of a new skill.
4+
5+
```markdown
6+
Skill Development Progress:
7+
- [ ] Define Purpose: Confirm the skill is necessary and distinct from existing ones.
8+
- [ ] Naming: Select a lowercase, kebab-case name (prefer gerund form, e.g., adding-release-notes).
9+
- [ ] Description: Write a third-person "what + when" description for the YAML frontmatter.
10+
- [ ] Planning: Outline the `SKILL.md` sections (Workflow, Guidelines, Resources).
11+
- [ ] Progressive Disclosure: Identify if any content should be moved to secondary files (EXAMPLES.md, REFERENCE.md).
12+
- [ ] Automation (Dart): Ensure any utility scripts in `scripts/` are written in **Dart**.
13+
- [ ] Final Review: Ensure instructions are concise and skip "obvious" explanations.
14+
```

‎.agents/skills/authoring-skills/EXAMPLES.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Skill Authoring Examples
2+
3+
## 1. Effective YAML Frontmatter
4+
5+
**Good (Gerund + What/When Description):**
6+
```yaml
7+
---
8+
name: processing-logs
9+
description: Extracts and summarizes error patterns from system logs. Use when the user asks to analyze logs or troubleshoot runtime errors.
10+
---
11+
```
12+
13+
**Bad (Vague + First Person):**
14+
```yaml
15+
---
16+
name: helper-tool
17+
description: I can help you look at files and tell you what is wrong.
18+
---
19+
```
20+
21+
## 2. Progressive Disclosure Pattern
22+
23+
If a skill has a complex API or many configuration options, do not put them all in `SKILL.md`.
24+
25+
**SKILL.md:**
26+
```markdown
27+
## Advanced Configuration
28+
For detailed information on environment variables and performance tuning, see [CONFIG.md](CONFIG.md).
29+
```
30+
31+
## 3. Workflow Patterns
32+
33+
Always use checklists to track state.
34+
35+
```markdown
36+
## Workflow
37+
Copy this checklist:
38+
- [ ] Step 1: Analyze input.
39+
- [ ] Step 2: Generate draft.
40+
- [ ] Step 3: Run validation script.
41+
```
42+
43+
## 4. Automation with Dart
44+
45+
All scripts should be written in Dart and placed in the `scripts/` directory.
46+
47+
**Good Script Usage:**
48+
```markdown
49+
## Step 4: Add the entry
50+
Use the provided utility script to insert the note safely.
51+
`dart .agents/skills/adding-release-notes/scripts/add_note.dart "Inspector updates" "Added XYZ" TODO`
52+
```
53+
54+
## 5. Anti-Patterns to Avoid
55+
56+
- **Prohibited**: Using non-Dart languages for utility scripts.
57+
- **Prohibited**: Using Windows-style paths (always use `/`).
58+
- **Prohibited**: Offering too many options (narrow the scope to recommended defaults).
59+
- **Prohibited**: Verbose background stories (Claude already knows how to code).
60+
- **Prohibited**: Interactive prompts (Agents should be autonomous, not ask for permission at every step).

‎.agents/skills/authoring-skills/SKILL.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: authoring-skills
3+
description: Guides the creation of high-quality, effective skills for agentic workflows. Use when creating or modifying skills in the .agents/skills/ directory.
4+
---
5+
6+
# Authoring Skills
7+
8+
When creating or modifying skills in this repository, follow these best practices:
9+
10+
- **Antigravity Guidelines**: [Skill authoring best practices](https://antigravity.google/docs/skills)
11+
- **Anthropic Guidelines**: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
12+
13+
## Repository-Specific Guidelines
14+
15+
- **Location**: All skills must be placed in the `.agents/skills/` directory.
16+
- **Avoid Duplication**: Before creating a skill, check if one already exists in the [flutter/skills](https://github.com/flutter/skills/tree/main/skills) repository. If it does, do not create a local skill; instead, instruct the user to install it via `npx`.
17+
- **Naming**: Use the gerund form (**verb-ing-noun**) or **noun-phrase** (e.g., `authoring-skills`, `adding-release-notes`). Use only lowercase letters, numbers, and hyphens.
18+
- **Conciseness**: Prioritize brevity in `SKILL.md`. Agents are already highly capable; only provide context they don't already have.
19+
- **Automation**: Any utility scripts placed in the `scripts/` directory MUST be written in **Dart**.
20+
- **Progressive Disclosure**: Use the patterns below to organize instructions effectively:
21+
- [CHECKLIST.md](CHECKLIST.md): Template for tracking skill development progress.
22+
- [EXAMPLES.md](EXAMPLES.md): Local examples and anti-patterns.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,46 @@
1-
*Replace this paragraph with a description of what this PR is changing or adding, and why. Consider including before/after screenshots.*
2-
31
*List which issues are fixed by this PR.*
42

5-
*Please add a note to `packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md` if your change requires release notes. Otherwise, add the 'release-notes-not-required' label to the PR.*
3+
*Replace this paragraph with a description of what this PR is changing or adding, and why. If your PR is updating any UI functionality, please include include before/after screenshots and/or a gif of the UI interaction.*
64

75
## Pre-launch Checklist
86

7+
### General checklist
8+
99
- [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
1010
- [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities.
1111
- [ ] I read the [Flutter Style Guide] _recently_, and have followed its advice.
1212
- [ ] I signed the [CLA].
13-
- [ ] I listed at least one issue that this PR fixes in the description above.
1413
- [ ] I updated/added relevant documentation (doc comments with `///`).
15-
- [ ] I added new tests to check the change I am making, or there is a reason for not adding tests.
1614

15+
### Issues checklist
16+
17+
- [ ] I listed at least one issue that this PR fixes in the description above.
18+
- [ ] I listed at least one issue which has the [`contributions-welcome`] or [`good-first-issue`] label.
19+
- [ ] I did not list at least one issue with the [`contributions-welcome`] or [`good-first-issue`] label. I understand this means my PR might take longer to be reviewed.
20+
21+
### Tests checklist
22+
23+
- [ ] I added new tests to check the change I am making...
24+
- [ ] OR there is a reason for not adding tests, which I explained in the PR description.
25+
26+
### AI-tooling checklist
27+
28+
- [ ] I did not use any AI tooling in creating this PR.
29+
- [ ] OR I did use AI tooling, and...
30+
* [ ] I read the [AI contributions guidelines] and agree to follow them.
31+
* [ ] I reviewed all AI-generated code before opening this PR.
32+
* [ ] I understand and am able to discuss the code in this PR.
33+
* [ ] I have verifed the accuracy of any AI-generated text included in the PR description.
34+
* [ ] I commit to verifying the accuracy of any AI-generated code or text that I upload in response to review comments.
35+
36+
### Feature-change checklist
37+
38+
- [ ] This PR does not change the DevTools UI or behavior and...
39+
* [ ] I added the `release-notes-not-required` label or left a comment requesting the label be added.
40+
- [ ] OR this PR does change the DevTools UI or behavior and...
41+
* [ ] I added an entry to `packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md`.
42+
* [ ] I included before/after screenshots and/or a GIF demo of the new UI to my PR description.
43+
* [ ] I ran the DevTools app locally to manually verify my changes.
1744

1845
![build.yaml badge]
1946

@@ -24,5 +51,8 @@ If you need help, consider asking for help on [Discord].
2451
[Tree Hygiene]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md
2552
[Flutter Style Guide]: https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
2653
[CLA]: https://cla.developers.google.com/
27-
[Discord]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
54+
[`contributions-welcome`]: https://github.com/flutter/devtools/issues?q=state%3Aopen%20label%3Acontributions-welcome
55+
[`good-first-issue`]: https://github.com/flutter/devtools/issues?q=state%3Aopen%20label%3Agood-first-issue
56+
[AI contributions guidelines]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines
2857
[build.yaml badge]: https://github.com/flutter/devtools/actions/workflows/build.yaml/badge.svg
58+
[Discord]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md

0 commit comments

Comments
 (0)