From c66b0e83025b5cebf126eb618160a8d1c1739e30 Mon Sep 17 00:00:00 2001 From: intelliDean Date: Fri, 30 Jan 2026 12:00:13 +0100 Subject: [PATCH] updated the CONTRIBUTING.md --- .gitignore | 1 + CONTRIBUTING.md | 686 +++++++++++++++++++++++++++++++++++++++++++++--- dock.txt | 194 -------------- 3 files changed, 647 insertions(+), 234 deletions(-) delete mode 100755 dock.txt diff --git a/.gitignore b/.gitignore index 906b659..2a26295 100755 --- a/.gitignore +++ b/.gitignore @@ -42,4 +42,5 @@ success_report.md check_output*.txt check_detailed.txt api_check_detailed.txt +dock.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c65b942..615ddc0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,42 +1,648 @@ # Contributing to Payego -Thank you for your interest in contributing to Payego! We welcome contributions from everyone. - -## Development Workflow - -1. **Fork and Clone**: Fork the repository and clone it locally. -2. **Branching**: Create a new branch for your feature or bugfix. - ```bash - git checkout -b feature/amazing-feature - ``` -3. **Backend Development**: - - Code is in `src/`, `crates/`, and `bin/`. - - Run tests: `cargo test` - - Check linting: `cargo clippy` - - Check formatting: `cargo fmt` -4. **Frontend Development**: - - Code is in `payego_ui/`. - - Run dev server: `npm run dev` - - Run tests: `npm run test` - - Run linting: `npm run lint` - -## Pull Request Process - -1. Ensure all local tests pass. -2. Commit your changes with clear, descriptive commit messages. -3. Push to your fork and submit a Pull Request to the `main` branch. -4. Our CI pipeline will automatically run to verify your changes. - -## Code Style - -- **Rust**: Follow standard Rust conventions (`rustfmt`). -- **JavaScript/React**: Follow ESLint configuration in `payego_ui`. - -## Architecture Guide - -- **payego-api** (`crates/api`): HTTP handlers and routing. -- **payego-core** (`crates/core`): Business logic and services. -- **payego-primitives** (`crates/primitives`): Shared types, DTOs, and errors. -- **payego-ui** (`payego_ui`): React frontend. - -Happy Coding! πŸš€ +Thank you for your interest in contributing to Payego! We welcome contributions from everyone and appreciate your help in making this project better. + +## πŸ“‹ Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Testing Requirements](#testing-requirements) +- [Code Quality Standards](#code-quality-standards) +- [Pull Request Process](#pull-request-process) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Architecture Overview](#architecture-overview) +- [Security Guidelines](#security-guidelines) +- [Documentation Standards](#documentation-standards) +- [Getting Help](#getting-help) + +--- + +## 🀝 Code of Conduct + +### Our Pledge + +We are committed to providing a welcoming and inclusive environment for all contributors, regardless of experience level, background, or identity. + +### Expected Behavior + +- Be respectful and considerate +- Use welcoming and inclusive language +- Accept constructive criticism gracefully +- Focus on what's best for the project +- Show empathy towards other contributors + +### Unacceptable Behavior + +- Harassment, trolling, or discriminatory comments +- Personal attacks or insults +- Publishing others' private information +- Any conduct that would be inappropriate in a professional setting + +--- + +## πŸš€ Getting Started + +### Prerequisites + +Ensure you have the following installed: +- **Rust**: v1.75+ (`rustup update`) +- **Node.js**: v18+ +- **PostgreSQL**: v15+ +- **Diesel CLI**: `cargo install diesel_cli --no-default-features --features postgres` +- **Git**: Latest version + +### Initial Setup + +1. **Fork the Repository** + ```bash + # Click "Fork" on GitHub, then clone your fork + git clone https://github.com/YOUR_USERNAME/payego.git + cd payego + ``` + +2. **Add Upstream Remote** + ```bash + git remote add upstream https://github.com/intelliDean/payego.git + ``` + +3. **Environment Configuration** + ```bash + cp .env.example .env + ``` + + Edit `.env` and configure: + - Database credentials + - JWT secret (32+ characters) + - Payment provider keys (Stripe, PayPal, Paystack) + - CORS origins + +4. **Database Setup** + ```bash + # Create database + diesel setup + + # Run migrations + diesel migration run + ``` + +5. **Install Dependencies** + + **Backend:** + ```bash + cargo build + ``` + + **Frontend:** + ```bash + cd payego_ui + npm install + ``` + +6. **Verify Setup** + + **Backend:** + ```bash + cargo test --workspace + cargo run + ``` + + **Frontend:** + ```bash + cd payego_ui + npm test + npm run dev + ``` + +--- + +## πŸ”„ Development Workflow + +### 1. Create a Feature Branch + +Always create a new branch for your work: +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/bug-description +``` + +**Branch naming conventions:** +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Adding or updating tests +- `chore/` - Maintenance tasks + +### 2. Make Your Changes + +**Backend Development:** +- Code location: `crates/api`, `crates/core`, `crates/primitives` +- Run tests: `cargo test --workspace` +- Check linting: `cargo clippy --workspace --tests -- -D warnings` +- Format code: `cargo fmt --all` + +**Frontend Development:** +- Code location: `payego_ui/src` +- Run dev server: `npm run dev` +- Run tests: `npm test` +- Run linting: `npm run lint` +- Build: `npm run build` + +### 3. Keep Your Branch Updated + +Regularly sync with upstream: +```bash +git fetch upstream +git rebase upstream/main +``` + +### 4. Commit Your Changes + +Follow our [commit message guidelines](#commit-message-guidelines): +```bash +git add . +git commit -m "feat: add user profile endpoint" +``` + +### 5. Push and Create PR + +```bash +git push origin feature/your-feature-name +``` + +Then create a Pull Request on GitHub. + +--- + +## πŸ§ͺ Testing Requirements + +### Backend Tests + +**Required:** +- Write integration tests for new API endpoints +- Write unit tests for service layer logic +- Ensure all existing tests pass + +**Running tests:** +```bash +# All tests +cargo test --workspace + +# Specific test file +cargo test --test auth_tests + +# With output +cargo test -- --nocapture +``` + +**Test categories:** +- `bin/payego/tests/` - Integration tests +- Service unit tests - In service modules + +**Example test:** +```rust +#[tokio::test] +async fn test_user_registration() { + let app = setup_test_app().await; + let response = app.register_user("test@example.com", "password123").await; + assert_eq!(response.status(), StatusCode::CREATED); +} +``` + +### Frontend Tests + +**Required:** +- Write tests for new components +- Test error handling scenarios +- Ensure all existing tests pass + +**Running tests:** +```bash +cd payego_ui +npm test + +# With coverage +npm test -- --coverage + +# Watch mode +npm test -- --watch +``` + +**Test utilities:** +Use `test-utils.tsx` for component tests: +```typescript +import { render, screen } from '../utils/test-utils'; + +test('renders login form', () => { + render(); + expect(screen.getByLabelText(/email/i)).toBeInTheDocument(); +}); +``` + +### Test Coverage Expectations + +- **Backend**: Maintain 70%+ coverage for service layer +- **Frontend**: Aim for 60%+ coverage for components +- **Critical paths**: 100% coverage (auth, payments, transfers) + +--- + +## βœ… Code Quality Standards + +### Rust Code Quality + +**1. Run Clippy (Required)** +```bash +cargo clippy --workspace --tests -- -D warnings +``` + +All Clippy warnings must be resolved before PR approval. + +**2. Format Code (Required)** +```bash +cargo fmt --all +``` + +**3. Follow Rust Conventions** +- Use `snake_case` for functions and variables +- Use `PascalCase` for types and traits +- Add doc comments for public APIs +- Avoid `unwrap()` - use proper error handling + +**4. Error Handling** +- Use `Result` for all fallible operations +- Never use `panic!` in production code +- Log errors appropriately (WARN for expected, ERROR for unexpected) + +**5. Security** +- Wrap secrets in `secrecy::Secret` +- Never log sensitive data +- Validate all user input + +### Frontend Code Quality + +**1. Run Linter (Required)** +```bash +npm run lint +``` + +**2. TypeScript** +- Enable strict mode +- Avoid `any` types +- Use proper type definitions + +**3. Component Standards** +- Use functional components with hooks +- Extract reusable logic into custom hooks +- Keep components focused and small + +**4. Error Handling** +- Use centralized error handler (`errorHandler.ts`) +- Display user-friendly error messages +- Log errors for debugging + +--- + +## πŸ“ Pull Request Process + +### Before Submitting + +**Checklist:** +- [ ] All tests pass (`cargo test`, `npm test`) +- [ ] Code is formatted (`cargo fmt`, `npm run lint`) +- [ ] No Clippy warnings (`cargo clippy`) +- [ ] Added tests for new functionality +- [ ] Updated documentation if needed +- [ ] Commit messages follow conventions +- [ ] Branch is up-to-date with `main` + +### PR Description Template + +```markdown +## Description +Brief description of changes + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update + +## Testing +How was this tested? + +## Checklist +- [ ] Tests added/updated +- [ ] Documentation updated +- [ ] No breaking changes (or documented) +``` + +### Review Process + +1. **Automated Checks**: CI runs tests and linting +2. **Code Review**: Maintainer reviews code +3. **Feedback**: Address review comments +4. **Approval**: PR approved by maintainer +5. **Merge**: Squash and merge to main + +**Expected timeline:** 2-5 business days for initial review + +--- + +## πŸ’¬ Commit Message Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/). + +### Format + +``` +(): + + + +