Skip to content

docs: improve AGENTS.md and add comprehensive development documentation #12420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
LingyuCoder merged 8 commits into from
Dec 11, 2025
Merged

docs: improve AGENTS.md and add comprehensive development documentation #12420

LingyuCoder merged 8 commits into from
Dec 11, 2025

Conversation

@LingyuCoder
Copy link
Contributor

@LingyuCoder LingyuCoder commented Dec 11, 2025 •
edited
Loading

Summary

This PR enhances the development documentation for Rspack to make it more AI/LLM-friendly and provides comprehensive guidelines for contributors.

Changes

AGENTS.md Improvements

  • Add detailed directory structure information
  • Add debugging guide references
  • Add code quality and style guidelines
  • Add common tasks and workflows
  • Add dependency management details
  • Add performance testing information
  • Fix grammar errors (test Cases -> test cases, codes -> code, Formating -> Formatting)

New Documentation Files

  • CODE_STYLE.md: Comprehensive code style guide

    • Rust code style (formatting, naming, organization, error handling, async patterns)
    • TypeScript/JavaScript code style (formatting, naming, organization, error handling)
    • Testing patterns
    • File organization guidelines
    • Performance considerations
    • Common anti-patterns to avoid

  • COMMON_PATTERNS.md: Common code patterns and templates

    • Plugin implementation patterns (basic, multiple hooks, conditional logic)
    • Hook usage patterns (accessing compilation data, updating assets, using logger)
    • Error handling patterns (propagation, adding context, batch handling)
    • Async operation patterns
    • Testing patterns (Rust and JavaScript)
    • Loader implementation patterns
    • Configuration options definition
    • Asset processing patterns
    • String processing patterns
    • Performance optimization patterns

  • project.md: Project architecture documentation (English and Chinese)

    • Document all Rust crates with descriptions
    • Document all NPM packages with descriptions
    • Document test cases directory structure

  • Update _meta.json files to include project.md in navigation

  • Add deconflict to project-words.txt for spell checking

Benefits

  • Better AI/LLM Support: Comprehensive documentation helps AI assistants understand the codebase structure and conventions
  • Improved Developer Experience: Clear guidelines and patterns reduce onboarding time
  • Code Consistency: Standardized patterns ensure consistent code quality across the project
  • Easier Contribution: Templates and examples make it easier for new contributors to follow project conventions

Checklist

  • Tests updated (or not required)
  • Documentation updated

@LingyuCoder
chore: improve AGENTS.md and add project architecture documentation
3371e77 
- Enhance AGENTS.md with comprehensive development guidelines
  - Add detailed directory structure information
  - Add debugging guide references
  - Add code quality and style guidelines
  - Add common tasks and workflows
  - Add dependency management details
  - Add performance testing information
  - Fix grammar errors (test Cases -> test cases, codes -> code, Formating -> Formatting)
- Add project.md documentation for both English and Chinese
  - Document all Rust crates with descriptions
  - Document all NPM packages with descriptions
  - Document test cases directory structure
- Update _meta.json files to include project.md in navigation
- Add deconflict to project-words.txt for spell checking
Copilot AI review requested due to automatic review settings December 11, 2025 05:50
@github-actions github-actions bot added the team The issue/pr is created by the member of Rspack. label Dec 11, 2025
@netlify
Copy link

netlify bot commented Dec 11, 2025 •
edited
Loading

✅ Deploy Preview for rspack canceled.

Name Link
🔨 Latest commit cba280f
🔍 Latest deploy log https://app.netlify.com/projects/rspack/deploys/693a83bee1607b000894714e

Copilot AI reviewed Dec 11, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR enhances developer onboarding and documentation by adding comprehensive project architecture documentation and improving the AGENTS.md file with detailed development guidelines. The changes provide both English and Chinese documentation to help developers understand the project structure, codebase organization, and common development workflows.

  • Adds detailed project architecture documentation (project.md) describing all Rust crates, NPM packages, and test cases
  • Expands AGENTS.md with comprehensive sections on setup, building, testing, debugging, code quality, common tasks, and contribution guidelines
  • Updates package.json to add test:rs command and change lint:rs from clippy to cargo check

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
AGENTS.md Significantly expanded with structured development guidelines including setup, building, testing, debugging, code quality, common tasks, dependency management, performance, documentation, PR guidelines, and error handling sections
website/docs/en/contribute/development/project.md New comprehensive English documentation of project architecture covering all Rust crates, NPM packages, and test suite structure with detailed descriptions
website/docs/zh/contribute/development/project.md New comprehensive Chinese documentation of project architecture, mirroring the English version with consistent translations
website/docs/en/contribute/development/_meta.json Adds "project" to navigation order as first item in development documentation
website/docs/zh/contribute/development/_meta.json Adds "project" to navigation order as first item in development documentation
website/project-words.txt Adds "deconflict" to the spell checker dictionary for legitimate technical term usage
package.json Adds test:rs command for running Rust tests and changes lint:rs from cargo clippy to cargo check --workspace --all-targets --locked

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@github-actions
Copy link
Contributor

github-actions bot commented Dec 11, 2025 •
edited
Loading

Rsdoctor Bundle Diff Analysis

Found 5 project(s) in monorepo.

📁 react-10k

Path: ../build-tools-performance/cases/react-10k/dist/rsdoctor-data.json

⚠️ No baseline data found - Unable to perform comparison analysis

Metric Current Baseline Change
📊 Total Size 5.7 MB - -
📄 JavaScript 5.7 MB - -
🎨 CSS 21.0 B - -
🌐 HTML 0 B - -
📁 Other Assets 0 B - -

📁 react-1k

Path: ../build-tools-performance/cases/react-1k/dist/rsdoctor-data.json

⚠️ No baseline data found - Unable to perform comparison analysis

Metric Current Baseline Change
📊 Total Size 823.6 KB - -
📄 JavaScript 823.6 KB - -
🎨 CSS 0 B - -
🌐 HTML 0 B - -
📁 Other Assets 0 B - -

📁 react-5k

Path: ../build-tools-performance/cases/react-5k/dist/rsdoctor-data.json

⚠️ No baseline data found - Unable to perform comparison analysis

Metric Current Baseline Change
📊 Total Size 2.7 MB - -
📄 JavaScript 2.7 MB - -
🎨 CSS 21.0 B - -
🌐 HTML 0 B - -
📁 Other Assets 0 B - -

📁 rome

Path: ../build-tools-performance/cases/rome/dist/rsdoctor-data.json

⚠️ No baseline data found - Unable to perform comparison analysis

Metric Current Baseline Change
📊 Total Size 984.3 KB - -
📄 JavaScript 984.3 KB - -
🎨 CSS 0 B - -
🌐 HTML 0 B - -
📁 Other Assets 0 B - -

📁 ui-components

Path: ../build-tools-performance/cases/ui-components/dist/rsdoctor-data.json

⚠️ No baseline data found - Unable to perform comparison analysis

Metric Current Baseline Change
📊 Total Size 2.1 MB - -
📄 JavaScript 2.0 MB - -
🎨 CSS 83.0 KB - -
🌐 HTML 0 B - -
📁 Other Assets 0 B - -

Generated by Rsdoctor GitHub Action

@LingyuCoder LingyuCoder enabled auto-merge (squash) December 11, 2025 06:04
@github-actions
Copy link
Contributor

github-actions bot commented Dec 11, 2025 •
edited
Loading

📦 Binary Size-limit

Comparing cba280f to fix: make splitChunks more stable (#12410) by Fy

🙈 Size remains the same at 48.21MB

@codspeed-hq
Copy link

codspeed-hq bot commented Dec 11, 2025 •
edited
Loading

CodSpeed Performance Report

Merging #12420 will not alter performance

Comparing docs/improve-agents-and-project-docs (cba280f) with main (9b810aa)

Summary

✅ 17 untouched

@LingyuCoder
docs: add CODE_STYLE.md and COMMON_PATTERNS.md
2228b12 
- Add comprehensive code style guide covering Rust and TypeScript/JavaScript conventions
- Add common patterns documentation with examples for plugins, hooks, error handling, and more
- Provide templates and examples to help developers follow project conventions
@LingyuCoder LingyuCoder changed the title chore: improve AGENTS.md and add project architecture documentation docs: improve AGENTS.md and add comprehensive development documentation Dec 11, 2025
@github-actions github-actions bot added the release: document release: document related release(mr only) label Dec 11, 2025
@JSerFeng JSerFeng mentioned this pull request Dec 11, 2025
Closed
2 tasks
chenjiahan
chenjiahan reviewed Dec 11, 2025
View reviewed changes
chenjiahan
chenjiahan reviewed Dec 11, 2025
View reviewed changes
@LingyuCoder
chore: move AI-friendly docs to agents/ directory and add index in AG…
2dbe4b3 
…ENTS.md

- Move API_DESIGN.md, ARCHITECTURE.md, CODE_STYLE.md, COMMON_PATTERNS.md,
  GLOSSARY.md, and SKILLS.md to agents/ directory
- Keep AGENTS.md in root directory as the main entry point
- Add comprehensive index section in AGENTS.md pointing to all docs in agents/
- Update internal references between documents to reflect new locations
- Ensure AI models can easily discover and access all documentation
@LingyuCoder LingyuCoder force-pushed the docs/improve-agents-and-project-docs branch from aa5a908 to 2dbe4b3 Compare December 11, 2025 08:19
@LingyuCoder
docs: simplify ARCHITECTURE.md to under 4k tokens
cba280f 
Reduce ARCHITECTURE.md from ~13k to ~9.5k characters (~2.5k tokens) by:
- Condensing detailed descriptions
- Simplifying code examples and flowcharts
- Removing redundant explanations
- Keeping core concepts and essential information
@LingyuCoder LingyuCoder merged commit b73f59a into main Dec 11, 2025
52 checks passed
@LingyuCoder LingyuCoder deleted the docs/improve-agents-and-project-docs branch December 11, 2025 09:40
This was referenced Dec 11, 2025
Merged
Merged
Merged
@CPunisher CPunisher mentioned this pull request Dec 17, 2025
Merged
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@chenjiahan chenjiahan chenjiahan approved these changes

Assignees

No one assigned

Labels

release: document release: document related release(mr only) team The issue/pr is created by the member of Rspack.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@LingyuCoder @chenjiahan