Contributing

Contributing to Urx

Urx is an open-source project, and we welcome contributions from the community!

How to Contribute

Reporting Issues

Found a bug or have a feature request?

1. Search existing issues to avoid duplicates
2. Create a new issue with a clear title and description
3. Provide details:
   • Urx version (urx --version)
   • Operating system
   • Command used
   • Expected vs actual behavior
   • Steps to reproduce

Report an issue on GitHub

Contributing Code

Prerequisites

• Rust (latest stable version)
• Git
• Familiarity with the Rust ecosystem

Development Setup

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/urx.git
   cd urx
   

3. Build the project:

   cargo build
   

4. Run tests:

   cargo test
   

5. Create a feature branch:

   git checkout -b feature/your-feature-name
   

Making Changes

1. Write clean code following Rust best practices
2. Add tests for new functionality
3. Update documentation if needed
4. Run formatting:

   cargo fmt
   

5. Run linting:

   cargo clippy -- --deny warnings
   

Submitting Changes

1. Commit your changes:

   git add .
   git commit -m "Add feature: description"
   

2. Push to your fork:

   git push origin feature/your-feature-name
   

3. Create a Pull Request on GitHub:

   • Clear title and description
   • Reference related issues
   • Describe changes made
   • Include any breaking changes

Contributing Documentation

Documentation improvements are always welcome!

• Fix typos or unclear explanations
• Add examples and use cases
• Improve existing guides

Documentation is in the docs/content/ directory using Markdown format with TOML front matter.

Development Guidelines

Code Style

• Follow Rust standard formatting (use cargo fmt)
• Write clear, self-documenting code
• Add comments for complex logic
• Keep functions focused and small

Testing

• Add unit tests for new functions
• Add integration tests for features
• Ensure all tests pass before submitting
• Aim for high test coverage

Commit Messages

• Use clear, descriptive commit messages
• Start with a verb (Add, Fix, Update, Remove)
• Reference issue numbers when applicable
• Keep the first line under 72 characters

Pull Request Guidelines

• One feature/fix per pull request
• Keep changes focused and atomic
• Update CHANGELOG.md for significant changes
• Ensure CI passes before requesting review

Project Structure

urx/
├── src/              # Source code
│   ├── cli/         # CLI argument parsing
│   ├── providers/   # URL data providers
│   ├── filters/     # URL filtering logic
│   ├── testers/     # HTTP testing
│   └── network/     # Network configuration
├── docs/            # Documentation (Hwaro site)
├── example/         # Example configurations
└── tests/           # Integration tests

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Need Help?

• Read the full CONTRIBUTING.md guide
• Join GitHub Discussions
• Ask questions in issues

Recognition

All contributors are recognized in the project!

License

By contributing to Urx, you agree that your contributions will be licensed under the project's MIT License.