Skip to content

Commit bc77230

Browse files
fiskerfisker
committed
Merge branch 'main' into dev
# Conflicts: # .angular-github/ISSUE_TEMPLATE/5-vscode.yaml
2 parents 9f363e3 + 836094c commit bc77230

File tree

2,446 files changed

+170535
-102578
lines changed

Some content is hidden

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

2,446 files changed

+170535
-102578
lines changed

‎.agent/rules/agents.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../AGENTS.md

‎.agent/skills/adev-writing-guide/SKILL.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
name: adev-writing-guide
3+
description: Comprehensive writing guide for Angular documentation (adev). Covers Google Technical Writing standards, Angular-specific markdown extensions, code blocks, and components. Use when authoring or reviewing content in adev/src/content.
4+
---
5+
6+
# Angular Documentation (adev) Writing Guide
7+
8+
This skill provides comprehensive guidelines for authoring content in `adev/src/content`. It combines Google's technical writing standards with Angular-specific markdown conventions, components, and best practices.
9+
10+
## I. Google Technical Writing Guidelines
11+
12+
### Tone and Content
13+
14+
- **Be conversational and friendly:** Maintain a helpful yet professional tone. Avoid being overly casual.
15+
- **Write accessibly:** Ensure documentation is understandable to a diverse global audience, including non-native English speakers.
16+
- **Audience-first:** Focus on what the user needs to do, not just what the system does.
17+
- **Avoid pre-announcing:** Do not mention unreleased features or make unsupported claims.
18+
- **Use descriptive link text:** Link text should clearly indicate the destination (e.g., avoid "click here").
19+
20+
### Language and Grammar
21+
22+
- **Use second person ("you"):** Address the reader directly.
23+
- **Prefer active voice:** Clearly state who or what is performing the action (e.g., "The system generates a token" vs "A token is generated").
24+
- **Standard American English:** Use standard American spelling and punctuation.
25+
- **Conditional clauses first:** Place "if" or "when" clauses before the instruction (e.g., "If you encounter an error, check the logs").
26+
- **Define terms:** Introduce new or unfamiliar terms/acronyms upon first use.
27+
- **Consistent terminology:** Use the same term for the same concept throughout the document.
28+
- **Conciseness:** Aim for one idea per sentence. Keep sentences short.
29+
30+
### Formatting and Organization
31+
32+
- **Sentence case for headings:** Capitalize only the first word and proper nouns in titles and headings.
33+
- **Lists:**
34+
- **Numbered lists:** Use for sequential steps or prioritized items.
35+
- **Bulleted lists:** Use for unordered collections of items.
36+
- **Description lists:** Use for term-definition pairs.
37+
- **Serial commas:** Use the Oxford comma (comma before the last item in a list of three or more).
38+
- **Code formatting:** Use code font for code-related text (filenames, variables, commands).
39+
- **UI Elements:** formatting user interface elements in **bold**.
40+
- **Date formatting:** Use unambiguous formats (e.g., "September 4, 2024" rather than "9/4/2024").
41+
- **Structure:** Use logical hierarchy with clear introductions and navigation. Headings should be task-based where possible.
42+
43+
### Images and Code Samples
44+
45+
- **Images:** Use simple, clear illustrations to enhance understanding.
46+
- **Captions:** Write captions that support the image.
47+
- **Code Samples:**
48+
- Ensure code is correct and builds without errors.
49+
- Follow language-specific conventions.
50+
- **Comments:** Focus on _why_, not _what_. Avoid commenting on obvious code.
51+
52+
### Reference Hierarchy
53+
54+
1. Project-specific style guidelines (if any exist in `CONTRIBUTING.md` or similar).
55+
2. Google Developer Documentation Style Guide.
56+
3. Merriam-Webster (spelling).
57+
4. Chicago Manual of Style (non-technical).
58+
5. Microsoft Writing Style Guide (technical).
59+
60+
---
61+
62+
## II. Angular Documentation Specifics
63+
64+
### Code Blocks
65+
66+
Use the appropriate language identifier for syntax highlighting:
67+
68+
- **TypeScript (Angular):** Use `angular-ts` when TypeScript code examples contain inline templates.
69+
- **HTML (Angular):** Use `angular-html` for Angular templates.
70+
- **TypeScript (Generic):** Use `ts` for plain TypeScript.
71+
- **HTML (Generic):** Use `html` for plain HTML.
72+
- **Shell/Terminal:** Use `shell` or `bash`.
73+
- **Mermaid Diagrams:** Use `mermaid`.
74+
75+
#### Attributes
76+
77+
You can enhance code blocks with attributes in curly braces `{}` after the language identifier:
78+
79+
- `header="Title"`: Adds a title to the code block.
80+
- `linenums`: Enables line numbering.
81+
- `highlight="[1, 3-5]"`: Highlights specific lines.
82+
- `hideCopy`: Hides the copy button.
83+
- `prefer`: Marks code as a preferred example (green border/check).
84+
- `avoid`: Marks code as an example to avoid (red border/cross).
85+
86+
**Example:**
87+
88+
````markdown
89+
```angular-ts {header:"My Component", linenums, highlight="[2]"}
90+
@Component({
91+
selector: 'my-app',
92+
template: '<h1>Hello</h1>',
93+
})
94+
export class App {}
95+
```
96+
````
97+
98+
#### `<docs-code>` Component
99+
100+
For more advanced code block features, use the `<docs-code>` component:
101+
102+
- `path`: Path to a source file (e.g., `adev/src/content/examples/...`).
103+
- `header`: Custom header text.
104+
- `language`: Language identifier (e.g., `angular-ts`).
105+
- `linenums`: Boolean attribute.
106+
- `highlight`: Array of line numbers/ranges (e.g., `[[3,7], 9]`).
107+
- `diff`: Path to diff file.
108+
- `visibleLines`: Range of lines to show initially (collapsible).
109+
- `region`: Region to extract from source file.
110+
- `preview`: Boolean. Renders a live preview (StackBlitz). _Only works with standalone examples._
111+
- `hideCode`: Boolean. Collapses code by default.
112+
113+
**Multifile Example:**
114+
115+
```html
116+
<docs-code-multifile path="..." preview>
117+
<docs-code path="..." />
118+
<docs-code path="..." />
119+
</docs-code-multifile>
120+
```
121+
122+
### Alerts / Admonitions
123+
124+
Use specific keywords followed by a colon for alerts. These render as styled blocks.
125+
126+
- `NOTE:` For ancillary information.
127+
- `TIP:` For helpful hints or shortcuts.
128+
- `IMPORTANT:` For crucial information.
129+
- `CRITICAL:` For warnings about potential data loss or severe issues.
130+
- `TODO`: For incomplete documentation.
131+
- `QUESTION:` To pose a question to the reader.
132+
- `SUMMARY:` For section summaries.
133+
- `TLDR:` For concise summaries.
134+
- `HELPFUL:` For best practices.
135+
136+
**Example:**
137+
138+
```markdown
139+
TIP: Use `ng serve` to run your application locally.
140+
```
141+
142+
### Custom Components
143+
144+
- **Cards (`<docs-card>`):**
145+
- Must be inside `<docs-card-container>`.
146+
- Attributes: `title`, `link`, `href`.
147+
- **Callouts (`<docs-callout>`):**
148+
- Attributes: `title`, `important`, `critical`.
149+
- **Pills (`<docs-pill>`):**
150+
- Must be inside `<docs-pill-row>`.
151+
- Attributes: `title`, `href`.
152+
- **Steps / Workflow (`<docs-step>`):**
153+
- Must be inside `<docs-workflow>`.
154+
- Attributes: `title`.
155+
- **Tabs (`<docs-tab>`):**
156+
- Must be inside `<docs-tab-group>`.
157+
- Attributes: `label`.
158+
- **Videos (`<docs-video>`):**
159+
- Attributes: `src` (YouTube embed URL), `alt`.
160+
161+
### Images
162+
163+
Use standard markdown syntax with optional attributes for sizing and loading behavior.
164+
165+
- `#small`, `#medium`: Append to image URL for sizing.
166+
- `{loading: 'lazy'}`: Add attribute for lazy loading.
167+
168+
**Example:**
169+
170+
```markdown
171+
![Alt Text](path/to/image.png#medium {loading: 'lazy'})
172+
```
173+
174+
### Headers
175+
176+
- Use markdown headers (`#`, `##`, `###`).
177+
- Ensure a logical hierarchy (don't skip levels).
178+
- `h2` and `h3` are most common for content structure.

‎.agent/skills/pr_review/SKILL.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
name: PR Review
3+
description: Guidelines and tools for reviewing pull requests in the Angular repository.
4+
---
5+
6+
# PR Review Guidelines
7+
8+
When reviewing a pull request for the `angular` repository, follow these essential guidelines to ensure high-quality contributions:
9+
10+
1. **Context & Ecosystem**:
11+
- Keep in mind that this is the core Angular framework. Changes here can impact millions of developers.
12+
- Be mindful of backwards compatibility. Breaking changes require strict approval processes and deprecation periods.
13+
14+
2. **Key Focus Areas**:
15+
- **Comprehensive Reviews**: You **MUST always** perform a deep, comprehensive review of the _entire_ pull request. If the user asks you to look into a specific issue, file, or area of concern, you must investigate that specific area _in addition to_ reviewing the rest of the PR's substantive changes. Do not terminate your review after addressing only the user's focal point.
16+
- **Package-Specific Guidelines**: Check if there are specific guidelines for the package being modified in the `reference/` directory (e.g., `reference/router.md`). Always prioritize these rules for their respective packages.
17+
- **Commit Messages**: Evaluate the quality of commit messages. They should explain the _why_ behind the change, not just the _what_. Someone should be able to look at the commit history years from now and clearly understand the context and reasoning for the change.
18+
- **Code Cleanliness**: Ensure the code is readable, maintainable, and follows Angular's project standards.
19+
- **Performance**: Look out for code that might negatively impact runtime performance or bundle size, particularly in hot paths like change detection or rendering.
20+
- **Testing**: Ensure all new logic has comprehensive tests, including edge cases. **Do NOT run tests locally** as part of your review process. CI handles this automatically, and running tests locally is redundant and inefficient.
21+
- **API Design**: Ensure new public APIs are well-designed, consistent with existing APIs, and properly documented.
22+
- **Payload Size**: Pay attention to the impact of changes on the final client payload size.
23+
24+
3. **Execution Workflow**:
25+
Determine the appropriate review method. If the user explicitly asks for a `remote` or `local` review in their request, that takes precedence (e.g. "leave comments on the PR" implies `remote`). Otherwise, use the GitHub MCP or available scripts to determine if the review should be `local` or `remote`.
26+
27+
**Common Review Practices (Applies to both Local and Remote)**
28+
- **Preparation & Checklist**:
29+
- First, create a task list (e.g., in `task.md`) that you can easily reference containing **all** the review requirements from the "Key Focus Areas" section (Commit Messages, Performance, Testing, etc.), along with any specific review notes or requests from the user.
30+
- Before doing an in-depth review, expand this list into more detailed items of what you plan to explore and verify in the PR.
31+
- As you conduct the review, check off items in this list, adding your assessment or findings underneath each item.
32+
- At the end of your review, refer back to the checklist to ensure every single requirement was completely verified.
33+
- **Fetch PR Metadata Safely**: When you need to read the PR description or context, do NOT use `gh pr view <PR_NUMBER>` by itself, as its default GraphQL query may fail due to lack of `read:org` and `read:discussion` token scopes. Instead, use `read_url_content` on the PR URL or use `gh pr view <PR_NUMBER> --json title,body,state,author`.
34+
- **Check Existing Comments First**: Before formulating feedback, use the GitHub MCP or available scripts to fetch existing comments on the PR. Review this feedback to avoid duplicate comments, and incorporate its insights into your own review process.
35+
- **Constructive Feedback**: Provide clear, actionable, and polite feedback. Explain the _why_ behind your suggestions or edits. Do **NOT** leave inline comments purely to praise, agree with, or acknowledge a correct implementation detail, as this clutters the review. If you want to praise the PR, do so in the single general PR comment.
36+
37+
**A. Local Code Review (If the PR is owned by the author requesting the review)**
38+
- **Checkout**: Check out the PR branch locally (if it doesn't already exist, fetch it). If checking out the branch fails due to a worktree claim (e.g. "fatal: '<branch>' is already used by worktree at '<path>'"), do the review in that directory.
39+
- **Review & Edit**: Execute the review directly on the code. Instead of adding inline PR comments for suggestions, format the codebase or apply the edits directly to the files.
40+
- **Feedback**: Summarize the review findings and the concrete changes you made in a message to the user, referencing the completed items from your checklist.
41+
- **Do NOT Commit or Push**: Leave the changes uncommitted in the working directory so the user can easily review the pending edits locally. Let the user know the changes are ready for their review, but do not ask for approval to push.
42+
- **Resolve Comments**: Once the user confirms the changes are good and should be committed/pushed, respond to the existing comments as 'resolved' using the GitHub MCP or available scripts.
43+
44+
**B. Remote Code Review (For all other PRs)**
45+
- **Batching Comments (MCP Server - Preferred)**: If you have the GitHub MCP Server configured, you **MUST** follow this workflow to avoid spamming the author with multiple notifications:
46+
1. Create a pending review using `mcp_github-mcp-server_pull_request_review_write` (method `create`).
47+
2. Add your inline comments to the pending review using `mcp_github-mcp-server_add_comment_to_pending_review`.
48+
3. Submit the review using `mcp_github-mcp-server_pull_request_review_write` (method `submit_pending`).
49+
- **Batching Comments (Scripts - Fallback)**: If you do **NOT** have access to the GitHub MCP Server (e.g., specific MCP tools are missing from your context), fallback to using the provided scripts. Use `post_inline_comment.sh` to stage your comments locally. Once all comments are staged, you **MUST** call `submit_pr_review.sh` to publish them as a single batched review (and send a single notification). Try to keep comments minimal or use a general comment if you have many suggestions.
50+
- **Use Suggested Changes**: Whenever appropriate (e.g., for simple code fixes, refactoring suggestions, or typo corrections), prefer using GitHub's **Suggested Changes** syntax (`suggestion ... `) in your inline comments. This allows the author to apply your suggested code improvements with a single click in the GitHub UI.
51+
- **Review Type**: Never mark an external PR review as an "approval" unless explicitly instructed by a repo maintainer. Always use "Request Changes" or "Comment". Note that some tools might only support commenting.
52+
- **Require User Approval Before Posting**: Prepare your review comments and present them to the user, alongside a summary of your completed checklist. Do NOT post comments to the PR without explicitly asking the user for permission first. Only post the review after the user approves.
53+
- **Prefix Agent Comments**: To make it clear when comments are generated and posted by an AI agent rather than a human user, **always** prefix your review comments with `AGENT: `.
54+
55+
## Available Tools
56+
57+
The following tools are available for remote interactions. We prefer using standard **GitHub MCP Server** tools when available. If you do not have the MCP server set up, you **MUST** fallback to using the custom bash scripts.
58+
59+
### GitHub MCP Tools (Preferred)
60+
61+
- `mcp_github-mcp-server_pull_request_review_write`
62+
- `mcp_github-mcp-server_add_comment_to_pending_review`
63+
64+
### Custom Bash Scripts (Fallback)
65+
66+
The following scripts are provided as fallbacks if the MCP server is not available. Note that they rely on the `gh` CLI being correctly installed and authenticated in the local environment.
67+
68+
### `determine_review_type.sh`
69+
70+
Determines whether to use the Local or Remote review workflow by checking if the currently authenticated GitHub user via the `gh` CLI matches the author of the pull request.
71+
72+
**Usage:**
73+
74+
```bash
75+
.agent/skills/pr_review/scripts/determine_review_type.sh <PR_NUMBER>
76+
```
77+
78+
### `get_pr_comments.sh`
79+
80+
Fetches all existing inline comments on a PR using the GitHub API. This is crucial for reviewing other contributors' feedback and avoiding duplicate comments. It outputs JSON containing the `id`, `path`, `line`, `body`, and `user` for each comment.
81+
82+
**Usage:**
83+
84+
```bash
85+
.agent/skills/pr_review/scripts/get_pr_comments.sh <PR_NUMBER>
86+
```
87+
88+
### `reply_pr_comment.sh`
89+
90+
Replies to an existing PR comment thread. This is useful for marking comments as resolved after addressing them in a local code review. Note that the `COMMENT_ID` must be the ID of the top-level comment in the thread.
91+
92+
**Usage:**
93+
94+
```bash
95+
.agent/skills/pr_review/scripts/reply_pr_comment.sh <PR_NUMBER> <COMMENT_ID> <REPLY_BODY>
96+
```
97+
98+
### `post_inline_comment.sh`
99+
100+
The GitHub CLI `gh pr review` command does not natively support adding inline comments to specific lines of code via its standard flags. This script wraps the GitHub API to stage comments locally. They will not be published until you call `submit_pr_review.sh`.
101+
102+
**Usage:**
103+
104+
```bash
105+
.agent/skills/pr_review/scripts/post_inline_comment.sh <PR_NUMBER> <FILE_PATH> <LINE_NUMBER> <COMMENT_BODY>
106+
```
107+
108+
**Example:**
109+
110+
```bash
111+
.agent/skills/pr_review/scripts/post_inline_comment.sh 12345 "packages/core/src/render3/instructions/element.ts" 42 "AGENT: Consider the performance implications here."
112+
```
113+
114+
### `submit_pr_review.sh`
115+
116+
Submits all locally staged inline comments as a single batched review via the GitHub Pull Request Reviews API.
117+
118+
**Usage:**
119+
120+
```bash
121+
.agent/skills/pr_review/scripts/submit_pr_review.sh <PR_NUMBER> <EVENT_TYPE> [BODY]
122+
```
123+
124+
**Options:**
125+
126+
- `EVENT_TYPE`: Must be `COMMENT`, `APPROVE`, or `REQUEST_CHANGES`. Never use `APPROVE` for external PRs.
127+
- `BODY`: (Optional) A general summary comment for the review.
128+
129+
**Example:**
130+
131+
```bash
132+
.agent/skills/pr_review/scripts/submit_pr_review.sh 12345 COMMENT "AGENT: I have left a few inline suggestions for your consideration."
133+
```

‎.agent/skills/pr_review/reference/router.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Router PR Review Guidelines
2+
3+
When reviewing pull requests that modify the Angular Router (`packages/router`), pay special attention to the following:
4+
5+
- **Timing Sensitivity**: The router is extremely sensitive to timing changes. Any changes that alter the asynchronous timing of navigations, resolvers, or guards are almost always breaking changes and must be scrutinized carefully.
6+
- **Testing Practices**: Tests should usually use the `RouterTestingHarness`. Many existing tests are older and do not use this harness. Do not blindly follow the shape of existing tests when writing or reviewing new ones; encourage the use of modern testing utilities.
7+
- **Feature Justification**: Changes to router core code should be well-justified. Consider whether the change is proven to be a core developer ask, such as resolving a highly upvoted GitHub issue or addressing a critical bug.

‎.agent/skills/pr_review/scripts/determine_review_type.sh‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
# determine_review_type.sh <PR_NUMBER>
5+
# Determines if the PR should be reviewed locally or remotely based on author.
6+
7+
if [ -z "$1" ]; then
8+
echo "Usage: determine_review_type.sh <PR_NUMBER>"
9+
exit 1
10+
fi
11+
12+
PR_NUMBER=$1
13+
14+
# Get current authenticated user
15+
CURRENT_USER=$(gh api user -q .login 2>/dev/null)
16+
if [ $? -ne 0 ]; then
17+
echo "Error: Could not determine current GitHub user. Are you logged in to gh?"
18+
exit 1
19+
fi
20+
21+
# Get PR author
22+
PR_AUTHOR=$(gh pr view "$PR_NUMBER" --json author -q .author.login 2>/dev/null)
23+
if [ $? -ne 0 ]; then
24+
echo "Error: Could not retrieve PR information for $PR_NUMBER."
25+
exit 1
26+
fi
27+
28+
if [ "$CURRENT_USER" = "$PR_AUTHOR" ]; then
29+
echo "local"
30+
else
31+
echo "remote"
32+
fi

‎.agent/skills/pr_review/scripts/get_pr_comments.sh‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
# get_pr_comments.sh
5+
# Fetches existing inline comments on a PR to avoid duplicate reviews.
6+
# Usage: ./get_pr_comments.sh <PR_NUMBER>
7+
8+
if [ "$#" -lt 1 ]; then
9+
echo "Usage: $0 <PR_NUMBER>"
10+
exit 1
11+
fi
12+
13+
PR_NUMBER="$1"
14+
15+
# Ensure gh cli is installed
16+
if ! command -v gh &> /dev/null; then
17+
echo "Error: gh CLI could not be found. Please install and authenticate."
18+
exit 1
19+
fi
20+
21+
# Get the current repository (e.g., angular/angular)
22+
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
23+
24+
# Fetch comments
25+
gh api \
26+
--paginate \
27+
-H "Accept: application/vnd.github+json" \
28+
"/repos/${REPO}/pulls/${PR_NUMBER}/comments" \
29+
--jq '.[] | {id: .id, path: .path, line: .line, body: .body, user: .user.login}'

0 commit comments

Comments
 (0)