|
| 1 | +# 🚀 Contributing to EasySwitch |
| 2 | + |
| 3 | +Thank you for your interest in contributing to **EasySwitch**! This guide will help you contribute effectively while maintaining our quality standards. |
| 4 | + |
| 5 | +## 📋 Table of Contents |
| 6 | +- [Prerequisites](#-prerequisites) |
| 7 | +- [Local Setup](#-local-setup) |
| 8 | +- [Contribution Workflow](#-contribution-workflow) |
| 9 | +- [Code Conventions](#-code-conventions) |
| 10 | +- [Testing & Quality](#-testing--quality) |
| 11 | +- [Issue Management](#-issue-management) |
| 12 | +- [Code of Conduct](#-code-of-conduct) |
| 13 | + |
| 14 | +--- |
| 15 | + |
| 16 | +## 🔍 Prerequisites |
| 17 | +- Python 3.10+ |
| 18 | +- [UV](https://docs.astral.sh/uv/) (recommended) or pip |
| 19 | +- Basic knowledge of payment APIs |
| 20 | +- Familiarity with async testing |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## 💻 Local Setup |
| 25 | + |
| 26 | +### 1. Fork the Repository |
| 27 | +Click "Fork" at the top-right of the [project's GitHub page](https://github.com/AllDotPy/easyswitch). |
| 28 | + |
| 29 | +### 2. Clone the Project |
| 30 | +```bash |
| 31 | +git clone https://github.com/your-username/easyswitch.git |
| 32 | +cd easyswitch |
| 33 | +``` |
| 34 | + |
| 35 | +### 3. Set Up the Environment |
| 36 | +**With UV (recommended):** |
| 37 | +```bash |
| 38 | +# Install UV |
| 39 | +pip install uv |
| 40 | + |
| 41 | +# Create virtual environment |
| 42 | +uv venv |
| 43 | + |
| 44 | +# Activate environment |
| 45 | +source venv/bin/activate # Linux/Mac |
| 46 | +# OR |
| 47 | +.\venv\Scripts\activate # Windows |
| 48 | + |
| 49 | +# Install dependencies |
| 50 | +uv pip install -e .[dev] |
| 51 | +``` |
| 52 | + |
| 53 | +**With standard pip:** |
| 54 | +```bash |
| 55 | +python -m venv venv |
| 56 | +source venv/bin/activate |
| 57 | +pip install -e .[dev] |
| 58 | +``` |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## 🔄 Contribution Workflow |
| 63 | + |
| 64 | +1. **Create a Branch** |
| 65 | + ```bash |
| 66 | + git checkout -b feat/new-feature |
| 67 | + ``` |
| 68 | + |
| 69 | +2. **Implement Your Changes** |
| 70 | + - Follow [code conventions](#-code-conventions) |
| 71 | + - Add relevant tests |
| 72 | + |
| 73 | +3. **Verify Code Quality** |
| 74 | + ```bash |
| 75 | + uv run lint # Style check |
| 76 | + uv run test # Run tests |
| 77 | + ``` |
| 78 | + |
| 79 | +4. **Push Changes** |
| 80 | + ```bash |
| 81 | + git push origin feat/new-feature |
| 82 | + ``` |
| 83 | + |
| 84 | +5. **Open a Pull Request** |
| 85 | + - Complete the PR template |
| 86 | + - Clearly describe your changes |
| 87 | + - Reference related issues |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## ✨ Code Conventions |
| 92 | + |
| 93 | +### General Structure |
| 94 | +- **Typing**: Use type annotations everywhere |
| 95 | +- **Async**: Prefer `async/await` for I/O operations |
| 96 | +- **Exceptions**: Use the project's custom exceptions |
| 97 | + |
| 98 | +### Style Guide |
| 99 | +- **Naming**: |
| 100 | + - Variables/functions: `snake_case` |
| 101 | + - Classes: `PascalCase` |
| 102 | + - Constants: `UPPER_CASE` |
| 103 | +- **Docstrings**: Follow Google Style |
| 104 | + ```python |
| 105 | + def send_payment(amount: float) -> bool: |
| 106 | + """Sends payment to the aggregator. |
| 107 | +
|
| 108 | + Args: |
| 109 | + amount: Amount to send (in XOF) |
| 110 | +
|
| 111 | + Returns: |
| 112 | + bool: True if payment succeeded |
| 113 | + """ |
| 114 | + ``` |
| 115 | + |
| 116 | +### Validation |
| 117 | +- Use validators from `easyswitch.utils.validators` |
| 118 | +- Always validate API inputs |
| 119 | + |
| 120 | +--- |
| 121 | + |
| 122 | +## 🧪 Testing & Quality |
| 123 | + |
| 124 | +### Running Tests |
| 125 | +```bash |
| 126 | +uv run test # All tests |
| 127 | +uv run test -k "test_payment" # Specific tests |
| 128 | +``` |
| 129 | + |
| 130 | +### Code Coverage |
| 131 | +```bash |
| 132 | +uv run coverage |
| 133 | +``` |
| 134 | + |
| 135 | +### Best Practices |
| 136 | +- 1 test per feature |
| 137 | +- Isolated, idempotent tests |
| 138 | +- Mock external APIs |
| 139 | + |
| 140 | +--- |
| 141 | + |
| 142 | +## 🐛 Issue Management |
| 143 | + |
| 144 | +### Reporting Bugs |
| 145 | +1. Check for existing issues |
| 146 | +2. Use the "Bug Report" template |
| 147 | +3. Include: |
| 148 | + - Environment (Python, OS) |
| 149 | + - Reproduction steps |
| 150 | + - Relevant logs/errors |
| 151 | + |
| 152 | +### Feature Proposals |
| 153 | +1. Use the "Feature Request" template |
| 154 | +2. Describe: |
| 155 | + - Use case |
| 156 | + - Expected impact |
| 157 | + - API sketch if applicable |
| 158 | + |
| 159 | +--- |
| 160 | + |
| 161 | +## 🤝 Code of Conduct |
| 162 | + |
| 163 | +We adhere to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating: |
| 164 | +- Be kind and open-minded |
| 165 | +- Accept constructive feedback |
| 166 | +- Prioritize collaboration |
| 167 | + |
| 168 | +--- |
| 169 | + |
| 170 | +## 🎉 First-Time Contributor? |
| 171 | + |
| 172 | +Check out these labeled issues: |
| 173 | +- `good first issue` for simple contributions |
| 174 | +- `help wanted` for more challenging tasks |
| 175 | + |
| 176 | +--- |
| 177 | + |
| 178 | +Thank you for helping make EasySwitch even better! 💪 |
0 commit comments