Skip to content

Commit b82d49b

Browse files
truewebbertruewebber
committed
docs: Add comprehensive project documentation
- Update README.md with production-ready documentation * Complete feature overview and quick start guide * API reference with examples for all use cases * Performance metrics and quality badges * Support for proto3 extend statements and qualified types - Add CONTRIBUTING.md with development guidelines * Development workflow and PR process * Testing requirements (90%+ coverage) * Code style and architecture guidelines * Performance considerations and benchmarking - Add MIT LICENSE for open source distribution * Copyright (c) 2024 truewebber * Permissive license for maximum compatibility Ready for v1.0 production release with complete documentation suite.
1 parent a15ced2 commit b82d49b

File tree

3 files changed

+493
-236
lines changed

3 files changed

+493
-236
lines changed

‎CONTRIBUTING.md

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# Contributing to SwiftProtoParser
2+
3+
Thank you for your interest in contributing to SwiftProtoParser! We welcome contributions from the community and are pleased to have you join us.
4+
5+
## 🚀 Getting Started
6+
7+
### Prerequisites
8+
9+
- **Swift 5.9+**
10+
- **Xcode 15.0+** (for macOS development)
11+
- **Git** for version control
12+
13+
### Setting Up the Development Environment
14+
15+
1. **Fork** the repository on GitHub
16+
2. **Clone** your fork locally:
17+
```bash
18+
git clone https://github.com/your-username/SwiftProtoParser.git
19+
cd SwiftProtoParser
20+
```
21+
22+
3. **Install dependencies** and run initial setup:
23+
```bash
24+
make start-session
25+
```
26+
27+
4. **Run tests** to ensure everything is working:
28+
```bash
29+
make test
30+
make coverage
31+
```
32+
33+
## 📋 How to Contribute
34+
35+
### Reporting Bugs
36+
37+
Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, please include:
38+
39+
- **Clear description** of the issue
40+
- **Steps to reproduce** the behavior
41+
- **Expected vs actual behavior**
42+
- **Environment details** (Swift version, platform, etc.)
43+
- **Sample .proto file** if applicable
44+
- **Error messages** or logs
45+
46+
**Use this template:**
47+
48+
```markdown
49+
**Bug Description**
50+
A clear description of the bug.
51+
52+
**To Reproduce**
53+
Steps to reproduce the behavior:
54+
1. Create a .proto file with '...'
55+
2. Call SwiftProtoParser.parseProtoFile('...')
56+
3. See error
57+
58+
**Expected Behavior**
59+
What you expected to happen.
60+
61+
**Environment**
62+
- SwiftProtoParser version: [e.g. 1.0.0]
63+
- Swift version: [e.g. 5.9]
64+
- Platform: [e.g. macOS 14.0, iOS 17.0]
65+
66+
**Additional Context**
67+
Any other context about the problem.
68+
```
69+
70+
### Suggesting Features
71+
72+
We welcome feature suggestions! Please:
73+
74+
- **Check existing issues** to avoid duplicates
75+
- **Provide clear use case** for the feature
76+
- **Describe the expected behavior**
77+
- **Consider backward compatibility**
78+
79+
### Contributing Code
80+
81+
#### Development Workflow
82+
83+
1. **Create a branch** for your work:
84+
```bash
85+
git checkout -b feature/your-feature-name
86+
```
87+
88+
2. **Make your changes** following our coding standards
89+
3. **Add or update tests** for your changes
90+
4. **Run tests** to ensure everything passes:
91+
```bash
92+
make test
93+
make coverage
94+
```
95+
96+
5. **Commit your changes** with a clear message:
97+
```bash
98+
git commit -m "Add support for custom proto options"
99+
```
100+
101+
6. **Push to your fork** and create a Pull Request
102+
103+
#### Pull Request Guidelines
104+
105+
- **Keep changes focused** - one feature/fix per PR
106+
- **Write clear commit messages**
107+
- **Include tests** for new functionality
108+
- **Update documentation** if needed
109+
- **Ensure all tests pass**
110+
- **Maintain code coverage** above 90%
111+
112+
**PR Template:**
113+
114+
```markdown
115+
## Description
116+
Brief description of changes made.
117+
118+
## Type of Change
119+
- [ ] Bug fix
120+
- [ ] New feature
121+
- [ ] Documentation update
122+
- [ ] Performance improvement
123+
- [ ] Code refactoring
124+
125+
## Testing
126+
- [ ] Added new tests
127+
- [ ] Updated existing tests
128+
- [ ] All tests pass
129+
- [ ] Coverage maintained/improved
130+
131+
## Checklist
132+
- [ ] Code follows project style guidelines
133+
- [ ] Self-review completed
134+
- [ ] Documentation updated
135+
- [ ] No breaking changes (or clearly documented)
136+
```
137+
138+
## 🧪 Testing Guidelines
139+
140+
### Running Tests
141+
142+
```bash
143+
# Run all tests
144+
swift test
145+
146+
# Run specific test suite
147+
swift test --filter SwiftProtoParserTests
148+
149+
# Run with coverage
150+
make coverage
151+
```
152+
153+
### Writing Tests
154+
155+
- **Follow existing patterns** in the test suite
156+
- **Test both success and failure cases**
157+
- **Use descriptive test names**: `testParseValidProtoWithExtendStatements()`
158+
- **Include edge cases** and error conditions
159+
- **Add test resources** in `Tests/TestResources/` if needed
160+
161+
### Test Coverage Requirements
162+
163+
- **Maintain 90%+ coverage** for new code
164+
- **Add tests for bug fixes** to prevent regressions
165+
- **Include performance tests** for optimization changes
166+
167+
## 📝 Code Style Guidelines
168+
169+
### Swift Style
170+
171+
Follow [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/):
172+
173+
- **Use clear, descriptive names**
174+
- **Follow camelCase** for functions and variables
175+
- **Follow PascalCase** for types
176+
- **Prefer clarity over brevity**
177+
178+
### Code Organization
179+
180+
- **Group related functionality** together
181+
- **Use extensions** for protocol conformance
182+
- **Add documentation comments** for public APIs
183+
- **Keep functions focused** and small
184+
185+
### Example:
186+
187+
```swift
188+
/// Parses a Protocol Buffers .proto file into an Abstract Syntax Tree
189+
/// - Parameter filePath: Path to the .proto file
190+
/// - Returns: Result containing the parsed AST or an error
191+
/// - Throws: ProtoParseError if parsing fails
192+
public static func parseProtoFile(_ filePath: String) -> Result<ProtoAST, ProtoParseError> {
193+
// Implementation
194+
}
195+
```
196+
197+
## 🏗️ Architecture Guidelines
198+
199+
### Adding New Features
200+
201+
- **Follow existing module structure**
202+
- **Maintain separation of concerns**
203+
- **Add comprehensive error handling**
204+
- **Consider performance implications**
205+
- **Update relevant documentation**
206+
207+
### Module Guidelines
208+
209+
- **Core**: Fundamental types and errors
210+
- **Lexer**: Tokenization logic
211+
- **Parser**: AST generation
212+
- **DescriptorBuilder**: SwiftProtobuf integration
213+
- **DependencyResolver**: Import resolution
214+
- **Performance**: Caching and optimization
215+
- **Public**: Public API interface
216+
217+
## 🔍 Code Review Process
218+
219+
### What We Look For
220+
221+
- **Correctness**: Does the code work as intended?
222+
- **Tests**: Are there adequate tests?
223+
- **Performance**: Are there any performance regressions?
224+
- **Style**: Does it follow our coding standards?
225+
- **Documentation**: Is the code well-documented?
226+
227+
### Review Timeline
228+
229+
- **Initial review**: Within 2-3 days
230+
- **Follow-up reviews**: Within 1-2 days
231+
- **Merge**: After approval and CI passes
232+
233+
## 📚 Documentation
234+
235+
### Updating Documentation
236+
237+
- **Update README.md** for user-facing changes
238+
- **Update code comments** for API changes
239+
- **Add examples** for new features
240+
- **Update architecture docs** for structural changes
241+
242+
### Documentation Style
243+
244+
- **Be clear and concise**
245+
- **Include code examples**
246+
- **Explain the "why" not just the "what"**
247+
- **Keep it up to date**
248+
249+
## 🚨 Performance Considerations
250+
251+
### Performance Requirements
252+
253+
- **Maintain sub-millisecond** parsing for small files
254+
- **Keep memory usage reasonable** (< 50MB for typical projects)
255+
- **Preserve cache hit rates** above 80%
256+
- **Add benchmarks** for performance-critical changes
257+
258+
### Performance Testing
259+
260+
```bash
261+
# Run performance tests
262+
swift test --filter Performance
263+
264+
# Generate performance report
265+
make benchmark
266+
```
267+
268+
## 🆘 Getting Help
269+
270+
### Community Support
271+
272+
- **GitHub Discussions**: For questions and general discussion
273+
- **GitHub Issues**: For bugs and feature requests
274+
- **Documentation**: Check the `docs/` directory
275+
276+
### Development Questions
277+
278+
If you're stuck:
279+
280+
1. **Check existing documentation**
281+
2. **Search existing issues**
282+
3. **Ask in GitHub Discussions**
283+
4. **Ping maintainers** in your PR
284+
285+
## 📄 License
286+
287+
By contributing to SwiftProtoParser, you agree that your contributions will be licensed under the MIT License.
288+
289+
## 🙏 Recognition
290+
291+
Contributors will be recognized in:
292+
293+
- **GitHub contributors list**
294+
- **Release notes** for significant contributions
295+
- **Special mentions** for major features
296+
297+
---
298+
299+
Thank you for contributing to SwiftProtoParser! 🚀

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 truewebber
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)