Skip to content

Commit 6ca0235

Browse files
committed
update
1 parent 4612446 commit 6ca0235

File tree

10 files changed

+31
-1829
lines changed

10 files changed

+31
-1829
lines changed

src/docs/contribute/formatter.md

Lines changed: 2 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -5,128 +5,23 @@ outline: deep
55

66
# Formatter (Prettier)
77

8-
We are currently porting Prettier to Oxc to create a high-performance, Prettier-compatible formatter.
8+
We are currently porting Prettier and Biome Formatter to Oxc to create a high-performance, Prettier-compatible formatter.
99

1010
## Architecture Overview
1111

1212
The Oxc formatter is built around the same core concepts as Prettier but with significant performance optimizations:
1313

14-
- **Document Model**: Uses Prettier's document IR (Intermediate Representation)
14+
- **Document Model**: Uses Prettier and Biome's document IR (Intermediate Representation)
1515
- **Pretty Printing**: Implements Wadler's pretty printing algorithm
1616
- **AST Integration**: Leverages Oxc's fast parser for optimal performance
1717

18-
## Development Setup
19-
20-
### Prerequisites
21-
22-
- Rust toolchain (latest stable)
23-
- Node.js and npm (for testing against Prettier)
24-
25-
### Building the Formatter
26-
27-
```bash
28-
# Clone the repository
29-
git clone https://github.com/oxc-project/oxc
30-
cd oxc
31-
32-
# Build the formatter
33-
cargo build -p oxc_formatter
34-
35-
# Run formatter tests
36-
cargo test -p oxc_formatter
37-
```
38-
39-
### Testing Framework
40-
41-
We maintain comprehensive test coverage to ensure Prettier compatibility:
42-
43-
```bash
44-
# Run all formatter tests
45-
just test-formatter
46-
47-
# Run specific test categories
48-
cargo test -p oxc_formatter -- javascript
49-
cargo test -p oxc_formatter -- typescript
50-
cargo test -p oxc_formatter -- jsx
51-
```
52-
53-
## Implementation Details
54-
55-
### Document Builders
56-
57-
The formatter uses document builders similar to Prettier:
58-
59-
```rust
60-
pub enum Doc {
61-
Str(&'static str),
62-
String(String),
63-
Array(Vec<Doc>),
64-
Indent(Box<Doc>),
65-
Group(Box<Doc>),
66-
Line,
67-
SoftLine,
68-
HardLine,
69-
// ... other document types
70-
}
71-
```
72-
73-
### Formatting Process
74-
75-
1. **Parse**: Use Oxc parser to generate AST
76-
2. **Build**: Convert AST to document IR
77-
3. **Print**: Apply pretty printing algorithm
78-
4. **Output**: Generate formatted string
79-
80-
### Key Components
81-
82-
- **`oxc_formatter`**: Core formatting logic
83-
- **`oxc_formatter_js`**: JavaScript-specific formatting rules
84-
- **`oxc_formatter_ts`**: TypeScript-specific formatting rules
85-
- **`oxc_formatter_jsx`**: JSX/TSX formatting rules
86-
87-
## Contributing Guidelines
88-
89-
### Adding New Features
90-
91-
1. **Write Tests First**: Add test cases that demonstrate the desired formatting
92-
2. **Implement Logic**: Add formatting logic to appropriate modules
93-
3. **Verify Compatibility**: Ensure output matches Prettier exactly
94-
4. **Performance Test**: Benchmark changes for performance impact
95-
96-
### Code Style
97-
98-
- Follow Rust naming conventions
99-
- Add comprehensive documentation
100-
- Use `#[inline]` for performance-critical functions
101-
- Minimize allocations in hot paths
102-
103-
### Test Categories
104-
105-
- **Conformance Tests**: Verify identical output to Prettier
106-
- **Performance Tests**: Ensure formatting speed improvements
107-
- **Edge Case Tests**: Handle malformed or unusual code
108-
- **Integration Tests**: Test with real-world codebases
109-
11018
## Performance Considerations
11119

11220
### Optimization Strategies
11321

11422
- **Memory Arena**: AST allocated in bump allocator
11523
- **String Interning**: Reuse common strings
11624
- **Lazy Evaluation**: Defer expensive computations
117-
- **SIMD**: Use SIMD instructions where applicable
118-
119-
### Benchmarking
120-
121-
We maintain benchmarks against Prettier and other formatters:
122-
123-
```bash
124-
# Run performance benchmarks
125-
cargo bench --bench formatter
126-
127-
# Compare with Prettier
128-
just bench-formatter-prettier
129-
```
13025

13126
## Current Challenges
13227

@@ -144,30 +39,3 @@ just bench-formatter-prettier
14439
- [ ] Editor integrations
14540
- [ ] CLI tool
14641
- [ ] Language server protocol
147-
148-
## Getting Involved
149-
150-
### Ways to Contribute
151-
152-
1. **Test Coverage**: Add more test cases from real-world code
153-
2. **Performance Optimization**: Profile and optimize hot paths
154-
3. **Language Support**: Improve TypeScript and JSX handling
155-
4. **Documentation**: Improve code documentation and guides
156-
5. **Tooling**: Enhance development and testing tools
157-
158-
### Communication Channels
159-
160-
- **GitHub Issues**: [Formatter issues](https://github.com/oxc-project/oxc/labels/C-formatter)
161-
- **Discord**: Join our [Discord server](https://discord.gg/9uXCAwqQZW)
162-
- **Weekly Sync**: Formatter team meetings (check Discord for schedule)
163-
164-
### Development Workflow
165-
166-
1. Fork the repository
167-
2. Create a feature branch
168-
3. Write tests for your changes
169-
4. Implement the functionality
170-
5. Ensure all tests pass
171-
6. Submit a pull request
172-
173-
For detailed contribution guidelines, see our [main contributing guide](../introduction.md).

src/docs/contribute/introduction.md

Lines changed: 5 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -18,53 +18,39 @@ Need guidance? Join our [Discord community](https://discord.gg/9uXCAwqQZW) where
1818
We welcome and appreciate any form of contributions:
1919

2020
### 🐛 Bug Reports
21+
2122
- Report parsing errors or incorrect linting behavior
2223
- Share performance issues or regressions
2324
- Document edge cases we haven't considered
2425

2526
### 🚀 Feature Development
27+
2628
- Add new linting rules
2729
- Improve parser conformance
2830
- Enhance transformer capabilities
2931
- Build new tools in the Oxc ecosystem
3032

3133
### 📚 Documentation
34+
3235
- Improve getting started guides
3336
- Add examples and tutorials
3437
- Document architecture decisions
3538
- Translate content to other languages
3639

3740
### 🧪 Testing
41+
3842
- Add test cases from real-world codebases
3943
- Improve test coverage
4044
- Create performance benchmarks
4145
- Test against ecosystem projects
4246

4347
### 🔧 Infrastructure
48+
4449
- Improve build and CI systems
4550
- Enhance development tooling
4651
- Optimize performance critical paths
4752
- Maintain compatibility with other tools
4853

49-
## Getting Started
50-
51-
### Development Environment
52-
53-
1. **Install Rust**: Follow the [official Rust installation guide](https://rustup.rs/)
54-
2. **Clone the Repository**:
55-
```bash
56-
git clone https://github.com/oxc-project/oxc
57-
cd oxc
58-
```
59-
3. **Build the Project**:
60-
```bash
61-
cargo build
62-
```
63-
4. **Run Tests**:
64-
```bash
65-
cargo test
66-
```
67-
6854
### Understanding the Codebase
6955

7056
Oxc is organized into several crates:
@@ -74,7 +60,6 @@ Oxc is organized into several crates:
7460
- **`oxc_transformer`**: TypeScript and JSX transformation
7561
- **`oxc_minifier`**: JavaScript minification (in development)
7662
- **`oxc_formatter`**: Code formatting (in development)
77-
- **`oxc_resolver`**: Module resolution
7863

7964
### Your First Contribution
8065

@@ -96,14 +81,6 @@ Oxc is organized into several crates:
9681

9782
We are committed to providing a welcoming and inclusive experience for everyone. Please read our [Code of Conduct](https://github.com/oxc-project/oxc/blob/main/CODE_OF_CONDUCT.md) before participating.
9883

99-
### Recognition
100-
101-
We appreciate all contributions! Contributors are:
102-
- Listed in our release notes
103-
- Added to our [contributors page](https://github.com/oxc-project/oxc/graphs/contributors)
104-
- Eligible for Oxc contributor swag
105-
- Invited to join our private contributor Discord channels
106-
10784
## Next Steps
10885

10986
Ready to contribute? Here are some great places to start:

0 commit comments

Comments
 (0)