diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0eca1d44 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contributing to Refitter + +Thank you for your interest in contributing to Refitter! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How to Contribute](#how-to-contribute) + - [Reporting Issues](#reporting-issues) + - [Feature Requests](#feature-requests) + - [Pull Requests](#pull-requests) +- [Development Guidelines](#development-guidelines) + - [Code Quality](#code-quality) + - [Testing](#testing) + - [Documentation](#documentation) +- [Style Guide](#style-guide) + +## Code of Conduct + +Please review and adhere to our code of conduct to ensure a positive and inclusive environment for all contributors. + +## How to Contribute + +### Reporting Issues + +If you encounter a bug or issue, please create a GitHub issue with the following information: +- A clear, descriptive title +- A detailed description of the issue +- Steps to reproduce the problem +- Expected behavior +- Actual behavior +- Environment information (OS, .NET version, etc.) +- **Support Key**: `[your-support-key]` (The support key is a unique identifier generated on your machine, displayed in the output when running Refitter since v0.5.4, and used for telemetry data) +- Any relevant error messages or logs + +### Feature Requests + +Feature requests are welcome! Please follow the feature request template in `.github/ISSUE_TEMPLATE/feature_request.md` when submitting a feature request. The template guides you to provide: + +- A description of whether your feature request is related to a problem +- A clear, detailed description of the solution you'd like +- Alternative solutions or features you've considered +- Any additional context or screenshots + +### Pull Requests + +1. Fork the repository +2. Create a new branch for your changes +3. Make your changes following the development guidelines below +4. Submit a pull request with a clear description of the changes and any related issues +5. Follow the pull request template in `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` which asks for: + - A description of the changes being made + - Association with existing issues if applicable + - Example OpenAPI specifications + - Example generated Refit interface + +## Development Guidelines + +### Code Quality + +- **All new code must not break existing features**. Ensure your changes don't introduce regressions. +- Maintain consistent code style with the existing codebase. +- Follow the [Style Guide](#style-guide) for the project. +- Prioritize readability and maintainability over cleverness. + +### Testing + +- **All new code must include unit tests** that verify the functionality works as expected. +- **New features must have unit tests similar to those under the Refitter.Tests.Examples namespace**. These tests must: + - Contain an example OpenAPI specification stored in a const string in the test class + - Assert on expected patterns in the generated code + - Verify that the generated code builds successfully +- Test coverage should be comprehensive, covering both normal operation and edge cases. +- All tests must pass before submitting a pull request. + +Example test pattern: + +```csharp +public class MyFeatureTests +{ + private const string OpenApiSpec = @" + // Your OpenAPI specification here + "; + + [Fact] + public async Task Can_Generate_Code() + { + string generateCode = await GenerateCode(); + generateCode.Should().NotBeNullOrWhiteSpace(); + } + + [Fact] + public async Task Generated_Code_Contains_Expected_Pattern() + { + string generateCode = await GenerateCode(); + generateCode.Should().Contain("ExpectedPattern"); + } + + [Fact] + public async Task Can_Build_Generated_Code() + { + string generateCode = await GenerateCode(); + BuildHelper + .BuildCSharp(generateCode) + .Should() + .BeTrue(); + } + + private static async Task GenerateCode() + { + var swaggerFile = await CreateSwaggerFile(OpenApiSpec); + var settings = new RefitGeneratorSettings + { + OpenApiPath = swaggerFile, + // Configure your feature settings here + }; + + var sut = await RefitGenerator.CreateAsync(settings); + var generateCode = sut.Generate(); + return generateCode; + } + + private static async Task CreateSwaggerFile(string contents) + { + var filename = $"{Guid.NewGuid()}.yml"; + var folder = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(folder); + var swaggerFile = Path.Combine(folder, filename); + await File.WriteAllTextAsync(swaggerFile, contents); + return swaggerFile; + } +} +``` + +### Documentation + +- **New features must be documented in the README files**. +- Documentation is especially important for: + - New CLI tool arguments + - Changes to the .refitter file format + - API changes or additions +- Update both code comments and user-facing documentation. +- Documentation should be clear, concise, and include examples where appropriate. + +## Style Guide + +- Use consistent naming conventions throughout the codebase. +- Use meaningful variable and method names that clearly express their purpose. +- Write clear XML documentation comments for public APIs. +- Keep methods focused and concise, following the single responsibility principle. +- Use proper formatting and indentation. + +--- + +Thank you for contributing to Refitter! Your help improves the project for everyone. \ No newline at end of file diff --git a/README.md b/README.md index 3c6ebb2f..c5f8fc59 100644 --- a/README.md +++ b/README.md @@ -1199,6 +1199,10 @@ Please head to the [Apizr documentation](https://www.apizr.net) to get more. .NET 8.0 +## Contributing + +Please read our [contribution guidelines](CONTRIBUTING.md) if you'd like to contribute to the project. + ## Contributors