Skip to content

Commit 9c0b11e

Browse files
christianhellechristianhelle
authored
Merge pull request #1190 from christianhelle/copilot/fix-1189
Add comprehensive CONTRIBUTING.md with code patterns and PR guidelines
2 parents ee165ae + 172363d commit 9c0b11e

File tree

1 file changed

+212
-0
lines changed

1 file changed

+212
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Contributing to REST API Client Code Generator
2+
3+
Thank you for your interest in contributing to the REST API Client Code Generator! This document provides guidelines and conventions to help maintain code quality and consistency across the project.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- .NET SDK (latest version)
10+
- Visual Studio 2019/2022 or VS Code
11+
- Node.js (for VS Code extension development)
12+
- Git
13+
14+
### Repository Structure
15+
16+
This repository contains multiple components:
17+
18+
- **`src/Core/`** - Core .NET libraries and business logic
19+
- **`src/CLI/`** - Command-line interface tool (Rapicgen)
20+
- **`src/VSIX/`** - Visual Studio extension
21+
- **`src/VSCode/`** - Visual Studio Code extension
22+
- **`src/VSMac/`** - Visual Studio for Mac extension
23+
- **`test/`** - Test files and test data
24+
- **`docs/`** - Documentation
25+
26+
### Getting Started
27+
28+
1. **Clone the repository**
29+
```bash
30+
git clone https://github.com/christianhelle/apiclientcodegen.git
31+
cd apiclientcodegen
32+
```
33+
34+
2. **Build the project**
35+
```bash
36+
cd src
37+
dotnet restore
38+
dotnet build
39+
```
40+
41+
3. **Run tests**
42+
```bash
43+
dotnet test
44+
```
45+
46+
For specific component development, see the respective directories for additional setup instructions.
47+
48+
## Code Patterns and Style Guidelines
49+
50+
### C# Code Standards
51+
52+
Follow these established patterns found throughout the codebase:
53+
54+
#### Test Naming Conventions
55+
- Use descriptive test method names that clearly state what is being tested
56+
- Follow the pattern: `MethodName_Scenario_ExpectedResult`
57+
- Examples:
58+
```csharp
59+
[Fact]
60+
public void Constructor_Requires_XDocument()
61+
62+
[Fact]
63+
public void Updates_PropertyGroups()
64+
65+
[Fact]
66+
public void InstallOpenApiGenerator_Invokes_DownloadFile()
67+
```
68+
69+
#### Test Structure
70+
- Use the **Arrange-Act-Assert** pattern
71+
- Utilize **FluentAssertions** for assertions
72+
- Use **xUnit** as the test framework
73+
- Apply **AutoMoqData** attribute for parameterized tests with mocking
74+
- Example:
75+
```csharp
76+
[Theory, AutoMoqData]
77+
public void MethodName_Should_DoSomething(
78+
[Frozen] IDependency dependency,
79+
ClassUnderTest sut)
80+
{
81+
// Arrange
82+
// setup test data
83+
84+
// Act
85+
var result = sut.MethodUnderTest();
86+
87+
// Assert
88+
result.Should().NotBeNull();
89+
Mock.Get(dependency).Verify(/* verification */);
90+
}
91+
```
92+
93+
#### General C# Guidelines
94+
- Use meaningful variable and method names
95+
- Follow Microsoft's C# coding conventions
96+
- Use dependency injection patterns where appropriate
97+
- Implement interfaces for testability
98+
- Use nullable reference types where supported
99+
100+
### TypeScript/JavaScript (VS Code Extension)
101+
- Follow the existing patterns in `src/VSCode/`
102+
- Use ESLint configuration provided
103+
- Maintain TypeScript type safety
104+
- Use webpack for bundling
105+
106+
## Testing Guidelines
107+
108+
### Unit Tests
109+
- Write unit tests for all new functionality
110+
- Aim for high code coverage
111+
- Use descriptive test names that explain the scenario
112+
- Mock external dependencies using Moq
113+
- Test both positive and negative scenarios
114+
115+
### Integration Tests
116+
- Add integration tests for end-to-end scenarios
117+
- Use appropriate test data from the `test/` directory
118+
- Ensure tests are isolated and can run independently
119+
120+
### Test Organization
121+
- Place tests in corresponding `*.Tests` projects
122+
- Mirror the source code structure in test projects
123+
- Group related tests in the same test class
124+
125+
## Pull Request Guidelines
126+
127+
### PR Description Requirements
128+
**PR descriptions must be as verbose as possible.** Include:
129+
130+
1. **Clear summary** of what the PR accomplishes
131+
2. **Detailed explanation** of changes made
132+
3. **Reasoning** behind the approach taken
133+
4. **Testing performed** - describe what tests were added/modified
134+
5. **Breaking changes** if any
135+
6. **Related issues** using keywords like "Fixes #123" or "Closes #456"
136+
137+
#### Example PR Description:
138+
```markdown
139+
## Summary
140+
Add support for generating TypeScript clients using OpenAPI Generator
141+
142+
## Changes Made
143+
- Extended the core generator interface to support TypeScript output
144+
- Added new TypeScript-specific configuration options
145+
- Updated CLI tool to accept typescript as a generator option
146+
- Added comprehensive unit tests for the new functionality
147+
148+
## Reasoning
149+
This change addresses user requests for TypeScript client generation
150+
capability, expanding the tool's usefulness in JavaScript/TypeScript
151+
ecosystems.
152+
153+
## Testing
154+
- Added 15 new unit tests covering TypeScript generation scenarios
155+
- Verified integration with existing OpenAPI Generator workflows
156+
- Tested with sample OpenAPI specifications
157+
158+
## Breaking Changes
159+
None - this is a purely additive feature.
160+
161+
Fixes #123, Closes #456
162+
```
163+
164+
### README Maintenance
165+
**Keep README.md up to date with changes:**
166+
167+
- Update feature lists when adding new capabilities
168+
- Add new installation instructions for new components
169+
- Update usage examples when APIs change
170+
- Maintain accuracy in supported platforms/versions
171+
- Update badges and links as needed
172+
173+
### Technical Requirements
174+
1. **All tests must pass** - ensure existing functionality isn't broken
175+
2. **Add tests for new features** - maintain or improve test coverage
176+
3. **Update CHANGELOG.md** with your changes in the "Unreleased" section
177+
4. **Follow semantic versioning** guidelines for version impacts
178+
5. **Update documentation** if adding new features or changing behavior
179+
180+
### Code Review Process
181+
- PRs require approval before merging
182+
- Address all review feedback
183+
- Keep commits focused and atomic
184+
- Use meaningful commit messages
185+
186+
## Build and Development Workflow
187+
188+
### VS Code Extension Development
189+
See [`src/VSCode/CONTRIBUTING.md`](src/VSCode/CONTRIBUTING.md) for specific VS Code extension development guidelines.
190+
191+
## Continuous Integration
192+
193+
The project uses GitHub Actions for CI/CD:
194+
- Unit tests run on all PRs
195+
- Integration tests validate changes
196+
- Code quality checks via SonarCloud
197+
- Automated releases when merging to main
198+
199+
## Getting Help
200+
201+
- Review existing code for patterns and examples
202+
- Check the [documentation](docs/) for detailed guides
203+
- Look at recent PRs for examples of good contributions
204+
- Open an issue for questions or clarifications
205+
206+
## Code of Conduct
207+
208+
Please be respectful and inclusive in all interactions related to this project. We welcome contributions from developers of all backgrounds and experience levels.
209+
210+
---
211+
212+
Thank you for contributing to making this tool better for the development community!

0 commit comments

Comments
 (0)