🎉 Thank you for your interest in contributing to LocalStack .NET Client!

We welcome contributions of all kinds - from bug reports and feature requests to code improvements and documentation updates. This guide will help you get started and ensure your contributions have the best chance of being accepted.

• 🐛 Found a bug? → Create an Issue
• 💡 Have an idea? → Start a Discussion
• ❓ Need help? → Q&A Discussions
• 🚨 Security issue? → See our Security Policy
• 🔧 Ready to code? → Submit a Pull Request

This project follows the .NET Foundation Code of Conduct. By participating, you're expected to uphold this code. Please report unacceptable behavior to localstack.dotnet@gmail.com.

Important: As this project is pursuing .NET Foundation membership, contributors may be required to sign a Contributor License Agreement (CLA) as part of the contribution process. This helps ensure that contributions can be used by the project and the community. By submitting a pull request, you agree to license your contribution under the MIT license.

We maintain a dual-track versioning strategy:

• v2.x (AWS SDK v4) - Active development on master branch
• v1.x (AWS SDK v3) - Long-term support on sdkv3-lts branch (maintained until July 2026)

When contributing, please specify which version track your contribution targets.

• .NET SDK 8.0+ (for development)
• Docker (for LocalStack testing)
• Git
• IDE: Visual Studio, Rider, or VS Code

1. Fork and Clone

   # Fork the repository on GitHub, then clone your fork
   git clone https://github.com/YOUR-USERNAME/localstack-dotnet-client.git
   cd localstack-dotnet-client
   
   # Add upstream remote
   git remote add upstream https://github.com/localstack-dotnet/localstack-dotnet-client.git

2. Build the Project

   # Windows
   .\build.ps1
   
   # Linux/macOS  
   ./build.sh

3. Run Tests

   # All tests (requires Docker for functional tests)
   .\build.ps1 --target tests
   
   # Unit/Integration tests only
   .\build.ps1 --target tests --skipFunctionalTest true

1. Search existing issues to avoid duplicates
2. Check Discussions - your question might already be answered
3. Verify the issue occurs with LocalStack (not real AWS services)
4. Test with latest version when possible

Use our Issue Template which will guide you through providing:

• Environment details (LocalStack version, .NET version, OS)
• Minimal reproduction case
• Expected vs actual behavior
• Configuration and error messages

We love new ideas! Here's how to suggest features:

1. Check existing discussions for similar requests
2. Start a Discussion to gauge community interest
3. Create an issue if there's positive feedback and clear requirements

1. Discuss significant changes in Discussions first
2. Check for existing work - someone might already be working on it
3. Create an issue if one doesn't exist (for tracking)

1. Create a feature branch

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-number-description

2. Make your changes

   • Follow existing code style and conventions
   • Add tests for new functionality
   • Update documentation as needed
   • Ensure all analyzers pass without warnings

3. Test thoroughly

   # Run all tests
   ./build.sh --target tests
   
   # Test specific scenarios with LocalStack
   # (see sandbox projects for examples)

4. Commit with conventional commits

   git commit -m "feat: add support for XYZ service"
   git commit -m "fix: resolve timeout issue in DynamoDB client"
   git commit -m "docs: update installation guide"

5. Submit the Pull Request

   • Use our PR Template
   • Provide clear description of changes
   • Link related issues
   • Specify target version track (v1.x or v2.x)

• ✅ Follow existing patterns and architectural decisions
• ✅ Write comprehensive tests (unit, integration, functional where applicable)
• ✅ Add XML documentation for public APIs
• ✅ No analyzer warnings - we treat warnings as errors
• ✅ Maintain backward compatibility (unless it's a breaking change PR)
• ✅ Performance considerations - avoid introducing regressions

We have multiple test types:

• Unit Tests - Fast, isolated, no external dependencies
• Integration Tests - Test AWS SDK integration and client creation
• Functional Tests - Full end-to-end with LocalStack containers

When adding tests:

• Place them in the appropriate test project
• Follow existing naming conventions
• Test both success and error scenarios
• Include tests for edge cases

• Code comments - Explain the "why", not the "what"
• XML documentation - Required for all public APIs
• README updates - For feature additions or breaking changes
• CHANGELOG - Add entries for user-facing changes

1. Automated checks must pass (build, tests, code analysis)
2. Maintainer review - we aim to review within 48 hours
3. Community feedback - other contributors may provide input
4. Iterative improvements - address feedback promptly
5. Final approval and merge

• Questions about usage → Q&A Discussions
• Ideas for features → Ideas Discussions
• General discussion → General Discussions
• Show your work → Show and Tell

Contributors are recognized in:

• Our Contributors page
• Release notes for significant contributions
• Project documentation for major features

By contributing to this project, you agree to abide by our Code of Conduct and understand that your contributions will be licensed under the MIT License.

Thank you for making LocalStack .NET Client better! 🚀