Skip to content

Commit 108e6b5

Browse files
Copilotjorgerangel-msft
authored and
nick863
committed
Add CONTRIBUTING.md for Azure Generator (#53660)
* Initial plan * Add CONTRIBUTING.md for Azure Generator Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com> * Address review feedback: remove cd command and Discussions link Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com> * Clarify Spector filter usage and coverage output location Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com> * Update Spector filter example to use http/type/array Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com> * Use positional parameter for Test-Spector.ps1 filter Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>
1 parent dbe5a99 commit 108e6b5

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎eng/packages/http-client-csharp/CONTRIBUTING.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Contributing to @azure-typespec/http-client-csharp
2+
3+
Welcome! This guide will help you set up your development environment and contribute to the Azure TypeSpec HTTP Client C# package.
4+
5+
## Table of Contents
6+
7+
- [Prerequisites](#prerequisites)
8+
- [Getting Started](#getting-started)
9+
- [Development Workflow](#development-workflow)
10+
- [Testing](#testing)
11+
- [Code Generation](#code-generation)
12+
- [Creating Pull Requests](#creating-pull-requests)
13+
- [Getting Help](#getting-help)
14+
- [Code of Conduct](#code-of-conduct)
15+
16+
## Prerequisites
17+
18+
Before you begin, ensure you have the following installed:
19+
20+
- [Node.js](https://nodejs.org/) (version 20 or higher)
21+
- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) (required - see global.json for exact version)
22+
- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
23+
- [Git](https://git-scm.com/)
24+
- [PowerShell](https://docs.microsoft.com/powershell/scripting/install/installing-powershell) (version 7.0 or higher, for advanced testing and code generation scenarios)
25+
- [Long Path Support](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell#registry-setting-to-enable-long-paths) (Windows only required to avoid path length limitations during development)
26+
27+
## Getting Started
28+
29+
### 1. Clone the Repository
30+
31+
```bash
32+
git clone https://github.com/Azure/azure-sdk-for-net.git
33+
cd azure-sdk-for-net/eng/packages/http-client-csharp
34+
```
35+
36+
### 2. Install Dependencies
37+
38+
From the repository root:
39+
40+
```bash
41+
npm ci
42+
```
43+
44+
### 3. Build the C# Package
45+
46+
```bash
47+
npm run build
48+
```
49+
50+
This command runs:
51+
52+
- `npm run build:emitter` - Builds the TypeScript emitter
53+
- `npm run build:generator` - Builds the .NET generator
54+
55+
### 4. Verify Installation
56+
57+
After building, you can verify everything is working correctly by running:
58+
59+
```bash
60+
npm run test
61+
```
62+
63+
## Development Workflow
64+
65+
### Package Structure
66+
67+
The C# HTTP client package consists of two main components:
68+
69+
- **Emitter** (`/emitter`): TypeScript code that processes TypeSpec definitions and produces input for the generator
70+
- **Generator** (`/generator`): .NET code that generates C# client libraries from the emitter output
71+
72+
### Making Changes
73+
74+
1. **Create a fork** of the repository and clone it:
75+
76+
```bash
77+
git clone https://github.com/YOUR_USERNAME/azure-sdk-for-net.git
78+
cd azure-sdk-for-net
79+
git checkout -b feature/your-feature-name
80+
```
81+
82+
2. **Make your changes** to the codebase
83+
84+
3. **Build your changes**:
85+
86+
```bash
87+
# Build emitter only
88+
npm run build:emitter
89+
90+
# Build generator only
91+
npm run build:generator
92+
93+
# Build everything
94+
npm run build
95+
```
96+
97+
4. **Test your changes**:
98+
99+
```bash
100+
# Test emitter only
101+
npm run test:emitter
102+
103+
# Test generator only
104+
npm run test:generator
105+
106+
# Test everything
107+
npm run test
108+
```
109+
110+
### Code Style and Linting
111+
112+
- **Format code**: `npm run prettier:fix`
113+
- **Run linting**: `npm run lint`
114+
- **Fix lint issues**: `npm run lint:fix`
115+
116+
## Testing
117+
118+
### Unit Tests
119+
120+
The package includes both TypeScript (emitter) and C# (generator) tests:
121+
122+
```bash
123+
# Run all tests
124+
npm run test
125+
126+
# Run emitter tests only (TypeScript/Vitest)
127+
npm run test:emitter
128+
129+
# Run generator tests only (.NET)
130+
npm run test:generator
131+
```
132+
133+
> **Note**: Some tests may require a full workspace build to resolve all dependencies before running successfully.
134+
135+
### Integration Testing with Spector
136+
137+
The package uses the Spector test framework for end-to-end testing of generated code:
138+
139+
```bash
140+
# Run Spector tests (requires PowerShell)
141+
./eng/scripts/Test-Spector.ps1
142+
143+
# Run Spector tests with filter (filters by directory path)
144+
./eng/scripts/Test-Spector.ps1 "http/type/array"
145+
146+
# Get Spector test coverage (outputs to ./generator/artifacts/coverage, not checked in)
147+
./eng/scripts/Get-Spector-Coverage.ps1
148+
```
149+
150+
### Test Project Generation
151+
152+
Generate test projects to validate the emitter and generator:
153+
154+
```bash
155+
# Generate all test projects (requires PowerShell)
156+
./eng/scripts/Generate.ps1
157+
158+
# Generate specific test project
159+
./eng/scripts/Generate.ps1 -filter "project-name"
160+
161+
# Generate with stubbed mode disabled
162+
./eng/scripts/Generate.ps1 -Stubbed $false
163+
```
164+
165+
## Code Generation
166+
167+
### Regenerating Test Projects
168+
169+
To regenerate test projects after making changes:
170+
171+
**Generate projects**:
172+
173+
```bash
174+
./eng/scripts/Generate.ps1
175+
```
176+
177+
### Regenerating Azure Libraries
178+
179+
To regenerate Azure libraries using your local changes, run:
180+
181+
```bash
182+
./eng/scripts/RegenPreview.ps1
183+
```
184+
185+
This will regenerate all the Azure libraries and allow you to view any potential diffs your changes may cause. For more information on the script's usage, see [RegenPreview](./eng/scripts/docs/RegenPreview.md).
186+
187+
## Creating Pull Requests
188+
189+
### 1. Prepare Your PR
190+
191+
Before creating a pull request:
192+
193+
- [ ] Ensure all tests pass: `npm run test`
194+
- [ ] Ensure code is properly formatted: `npm run prettier:fix`
195+
- [ ] Ensure code is properly linted: `npm run lint:fix`
196+
- [ ] Generate and test projects: `./eng/scripts/Generate.ps1` (if applicable)
197+
- [ ] Update documentation if needed
198+
199+
### 2. Create the PR
200+
201+
1. Push your branch to your fork or the main repository
202+
2. Create a pull request to the [Azure/azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net) repository
203+
3. Provide a clear description of your changes
204+
4. Link any related issues
205+
206+
## Getting Help
207+
208+
- **Issues**: Report bugs or request features in the [Azure SDK for .NET repository issues](https://github.com/Azure/azure-sdk-for-net/issues)
209+
- **Documentation**: Check the [TypeSpec documentation](https://typespec.io/) for more information
210+
- **C# Customization**: See the [Customization Guide](https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/.tspd/docs/customization.md)
211+
212+
## Code of Conduct
213+
214+
This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). Please be respectful and inclusive in all interactions.
215+
216+
Thank you for contributing! 🎉

0 commit comments

Comments
 (0)