/ CONTRIBUTING.md
CONTRIBUTING.md
1 # Contributing to Radicle Infrastructure 2 3 Thank you for your interest in contributing to the Radicle infrastructure! This document provides guidelines for contributing to this internal project. 4 5 --- 6 7 ## Table of Contents 8 9 1. [Getting Started](#getting-started) 10 2. [Development Setup](#development-setup) 11 3. [Contribution Workflow](#contribution-workflow) 12 4. [Code Standards](#code-standards) 13 5. [Commit Guidelines](#commit-guidelines) 14 6. [Testing](#testing) 15 7. [Documentation](#documentation) 16 17 --- 18 19 ## Getting Started 20 21 ### Prerequisites 22 23 - Radicle CLI installed (`brew install radicle`) 24 - Git configured with your identity 25 - Access to the private Radicle network 26 - macOS (for full infrastructure support) 27 28 ### Initial Setup 29 30 ```bash 31 # Clone the repository 32 rad clone rad:z2s159BoUPWefbmtu6s5DV5vvxymy 33 34 # Navigate to the project 35 cd radicle 36 37 # Install dependencies 38 npm install # if working with Node.js components 39 40 # Verify setup 41 ./scripts/workflow/sync-status.sh 42 ``` 43 44 --- 45 46 ## Development Setup 47 48 ### Environment Configuration 49 50 1. **Configure Package Registries** (optional but recommended): 51 ```bash 52 # npm 53 npm config set registry http://localhost:4873 54 55 # Python (project-level) 56 mkdir -p .pip 57 cat > .pip/pip.conf <<EOF 58 [global] 59 index-url = http://localhost:3141/root/pypi/+simple/ 60 trusted-host = localhost 61 EOF 62 ``` 63 64 2. **Install Pre-commit Hooks**: 65 ```bash 66 # Copy pre-commit hook 67 cp .git/hooks/pre-commit.sample .git/hooks/pre-commit 68 chmod +x .git/hooks/pre-commit 69 ``` 70 71 3. **Start Local Services** (if needed): 72 ```bash 73 # Start monitoring (if working on monitoring features) 74 ~/radicle-monitoring/start-monitoring.sh 75 76 # Start registries (if working on package features) 77 ~/radicle-registry/registry-manager.sh start 78 ``` 79 80 --- 81 82 ## Contribution Workflow 83 84 We use Radicle's **patch-based workflow** for all contributions: 85 86 ### 1. Create a Feature Branch 87 88 ```bash 89 # Create and switch to a new branch 90 git checkout -b feature/your-feature-name 91 ``` 92 93 ### 2. Make Your Changes 94 95 - Write code following our [Code Standards](#code-standards) 96 - Add tests if applicable 97 - Update documentation 98 - Commit frequently with clear messages 99 100 ### 3. Test Locally 101 102 ```bash 103 # Run validation (if applicable) 104 ./scripts/ci-cd/run-ci-job.sh $(git rev-parse HEAD) 105 106 # Check code quality 107 shellcheck your-script.sh # for bash scripts 108 ``` 109 110 ### 4. Create a Patch 111 112 ```bash 113 # Create a patch from your branch 114 ./scripts/workflow/create-patch.sh 115 116 # Or manually: 117 rad patch create \ 118 --title "feat: Brief description of your change" \ 119 --description "Detailed description..." \ 120 --message "Initial patch" 121 ``` 122 123 ### 5. Respond to Review 124 125 ```bash 126 # Make requested changes 127 git add . 128 git commit -m "address: Review feedback" 129 130 # Update the patch 131 ./scripts/workflow/update-patch.sh 132 133 # Or manually: 134 rad patch update <patch-id> --message "Updated based on review" 135 ``` 136 137 ### 6. Merge 138 139 Once approved: 140 ```bash 141 # Merge the patch 142 ./scripts/workflow/merge-patch.sh <patch-id> 143 ``` 144 145 --- 146 147 ## Code Standards 148 149 ### General Guidelines 150 151 1. **Write Clear Code**: 152 - Use descriptive variable and function names 153 - Add comments for complex logic 154 - Keep functions small and focused 155 156 2. **Follow Language Conventions**: 157 - **Bash**: Follow Google Shell Style Guide 158 - **Python**: Follow PEP 8 159 - **JavaScript/Node.js**: Follow Airbnb Style Guide 160 161 3. **Error Handling**: 162 - Always handle errors explicitly 163 - Provide helpful error messages 164 - Use appropriate exit codes 165 166 ### Bash Scripts 167 168 ```bash 169 #!/bin/bash 170 # 171 # Script Name - Brief description 172 # Usage: script-name [options] 173 # 174 175 set -euo pipefail # Strict error handling 176 177 # Constants in UPPER_CASE 178 CONST_VALUE="value" 179 180 # Functions in snake_case 181 function_name() { 182 local local_var="value" 183 # Function body 184 } 185 186 # Main execution 187 main() { 188 # Script logic 189 } 190 191 # Run main if executed (not sourced) 192 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then 193 main "$@" 194 fi 195 ``` 196 197 ### Script Headers 198 199 All scripts must include: 200 - Shebang (`#!/bin/bash`) 201 - Description 202 - Usage information 203 - Author/date (optional) 204 205 ### Documentation Blocks 206 207 ```bash 208 # Function: function_name 209 # Description: What this function does 210 # Arguments: 211 # $1 - First argument description 212 # $2 - Second argument description 213 # Returns: 214 # 0 - Success 215 # 1 - Error 216 function_name() { 217 # Implementation 218 } 219 ``` 220 221 --- 222 223 ## Commit Guidelines 224 225 ### Commit Message Format 226 227 Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: 228 229 ``` 230 <type>(<scope>): <subject> 231 232 <body> 233 234 <footer> 235 ``` 236 237 ### Types 238 239 - `feat`: New feature 240 - `fix`: Bug fix 241 - `docs`: Documentation changes 242 - `style`: Code style changes (formatting, etc.) 243 - `refactor`: Code refactoring 244 - `test`: Adding or updating tests 245 - `chore`: Maintenance tasks 246 - `perf`: Performance improvements 247 - `ci`: CI/CD changes 248 249 ### Examples 250 251 ```bash 252 # Feature 253 git commit -m "feat(monitoring): Add DORA metrics dashboard" 254 255 # Bug fix 256 git commit -m "fix(ci): Resolve shellcheck warnings in validation script" 257 258 # Documentation 259 git commit -m "docs: Update contributing guidelines" 260 261 # Multiple paragraphs 262 git commit -m "feat(registry): Add backup automation 263 264 - Implement daily backup schedule 265 - Add restore functionality 266 - Include verification checks 267 268 Closes #123" 269 ``` 270 271 ### Commit Best Practices 272 273 1. **Atomic Commits**: One logical change per commit 274 2. **Clear Messages**: Explain *what* and *why*, not *how* 275 3. **Reference Issues**: Link to related issues or patches 276 4. **Sign Commits**: Use GPG signing when possible 277 278 --- 279 280 ## Testing 281 282 ### Running Tests 283 284 ```bash 285 # Run all tests 286 ./scripts/ci-cd/run-all-tests.sh 287 288 # Run specific test suite 289 ./tests/run-integration-tests.sh 290 291 # Run CI validation locally 292 ./scripts/ci-cd/run-ci-job.sh $(git rev-parse HEAD) 293 ``` 294 295 ### Writing Tests 296 297 - Add tests for new features 298 - Update tests for bug fixes 299 - Ensure tests are reproducible 300 - Use descriptive test names 301 302 ### Test Structure 303 304 ```bash 305 # tests/test-feature.sh 306 #!/bin/bash 307 308 # Test: Feature description 309 test_feature_name() { 310 # Setup 311 local expected="expected_value" 312 313 # Execute 314 local actual=$(your_function) 315 316 # Assert 317 if [[ "$actual" == "$expected" ]]; then 318 echo "✓ Test passed" 319 return 0 320 else 321 echo "✗ Test failed: expected '$expected', got '$actual'" 322 return 1 323 fi 324 } 325 326 # Run tests 327 test_feature_name 328 ``` 329 330 --- 331 332 ## Documentation 333 334 ### When to Update Documentation 335 336 - Adding new features 337 - Changing existing functionality 338 - Fixing bugs that affect usage 339 - Adding new scripts or tools 340 - Updating configuration 341 342 ### Documentation Standards 343 344 1. **README Files**: Every directory should have a README explaining its contents 345 2. **Inline Comments**: Comment complex logic and non-obvious code 346 3. **Usage Examples**: Provide examples for all scripts and tools 347 4. **Keep Updated**: Update docs with code changes in the same commit 348 349 ### Documentation Structure 350 351 ``` 352 docs/ 353 ├── README.md # Documentation index 354 ├── getting-started/ # Onboarding guides 355 ├── guides/ # User guides 356 ├── operations/ # Operational procedures 357 ├── architecture/ # Architecture docs 358 └── api/ # API/script reference 359 ``` 360 361 ### Writing Good Documentation 362 363 1. **Be Clear and Concise**: Use simple language 364 2. **Provide Examples**: Show real usage 365 3. **Include Screenshots**: When helpful 366 4. **Cross-Reference**: Link related docs 367 5. **Keep Current**: Review and update regularly 368 369 --- 370 371 ## Code Review Process 372 373 ### For Patch Authors 374 375 1. **Self-Review First**: Review your own code before submitting 376 2. **Provide Context**: Explain what, why, and how in patch description 377 3. **Be Responsive**: Address review feedback promptly 378 4. **Test Thoroughly**: Ensure CI passes before requesting review 379 380 ### For Reviewers 381 382 1. **Be Respectful**: Provide constructive feedback 383 2. **Be Specific**: Point to exact lines and suggest improvements 384 3. **Ask Questions**: If something is unclear 385 4. **Test Changes**: Pull and test the patch locally if needed 386 5. **Approve Promptly**: Don't block good patches unnecessarily 387 388 --- 389 390 ## Getting Help 391 392 ### Resources 393 394 - **Documentation**: `docs/` directory 395 - **Scripts Reference**: `scripts/README.md` 396 - **Troubleshooting**: `docs/guides/troubleshooting.md` 397 - **Architecture**: `docs/architecture/overview.md` 398 399 ### Contact 400 401 - **Team Lead**: [Name/Contact] 402 - **Infrastructure Questions**: [Contact] 403 - **Security Issues**: See [SECURITY.md](SECURITY.md) 404 405 --- 406 407 ## License 408 409 See [LICENSE](LICENSE) file for details. This is an internal Project Auxo Inc. project. 410 411 --- 412 413 **Thank you for contributing to our infrastructure!** 🎉 414 415 **Last Updated**: November 12, 2025