How to Contribute

We welcome contributions to the PY32F0xx HAL project! Whether you're fixing bugs, adding features, improving documentation, or testing on new hardware, your help is appreciated.

Ways to Contribute

Code Contributions

Bug fixes - Fix issues you encounter
New features - Add support for new peripherals or devices
Examples - Create examples for common use cases
Optimizations - Improve performance or reduce code size

Documentation

Fix typos - Correct spelling and grammar errors
Add examples - Document working code patterns
Improve clarity - Make instructions easier to follow
Translate content - Help with internationalization

Testing and Validation

Test on new hardware - Verify HAL works on different devices
Report bugs - Document issues you encounter
Validate examples - Confirm examples work as expected
Performance testing - Benchmark and optimize code

Getting Started

1. Set Up Development Environment

Follow our Development Environment Guide to set up your tools.

2. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/py32f0xx-hal.git
cd py32f0xx-hal

# Add upstream remote
git remote add upstream https://github.com/UNIT-Electronics-MX/py32f0xx-hal.git

3. Create a Feature Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

Development Guidelines

Code Style

Follow Rust conventions - Use cargo fmt and cargo clippy
Document public APIs - Add doc comments to public functions
Include examples - Show how to use new features
Test thoroughly - Verify code works on real hardware

Commit Messages

Use clear, descriptive commit messages:

type: brief description

Optional longer description explaining the change.

Fixes #123

Types:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
style: - Code formatting
refactor: - Code restructuring
test: - Test additions or changes
chore: - Maintenance tasks

Testing

Test on real hardware - Ensure changes work on actual devices
Include test cases - Add tests for new functionality
Verify examples - Make sure all examples still compile and work
Check documentation - Verify docs are accurate and complete

Submitting Changes

1. Prepare Your Changes

# Format code
cargo fmt

# Run clippy for linting
cargo clippy --all-targets --all-features

# Build all examples
make build-all

# Test documentation
cd docs && mdbook test

2. Commit and Push

# Stage changes
git add .

# Commit with descriptive message
git commit -m \"feat: add USART interrupt support\"

# Push to your fork
git push origin feature/your-feature-name

3. Create Pull Request

Go to GitHub and create a pull request
Describe your changes clearly in the PR description
Reference issues if your PR fixes them
Include testing details - what hardware you tested on

Pull Request Template

## Description
Brief description of what this PR does.

## Changes
- List of changes made
- New features added
- Bugs fixed

## Testing
- [ ] Tested on PY32F003I DFN8
- [ ] Tested on PY32F030 TSSOP20
- [ ] All examples compile
- [ ] Documentation updated

## Related Issues
Fixes #123