Contributing

Contributing

Thank you for your interest in contributing to Bill Organizer! This guide covers the development workflow, code standards, and pull request process.

---

Development Setup

Follow the Getting Started guide to set up the project locally before contributing.

---

Code Style

PHP (Backend)

• Follow PSR-12 coding standards
• Use Laravel Pint for automatic formatting:

  composer run lint
  # or
  vendor/bin/pint
  # Format only changed files
  vendor/bin/pint --dirty

• Use type hints and return types on all methods
• Add PHPDoc blocks for non-obvious parameters
• Use snake_case for database columns and API response fields

TypeScript / Vue (Frontend)

• Use TypeScript for all new files — avoid any types
• Follow the Vue 3 Composition API style guide
• Use ESLint and Prettier for formatting:

  yarn lint
  yarn format:check
  yarn format

• Use Zod schemas for form validation via VeeValidate

General Conventions

• Use descriptive variable and function names
• Write self-documenting code; comments should explain why, not what
• Keep functions small and focused on a single responsibility
• Write tests for all new features

---

Branch Naming

feature/short-description       # New features
fix/short-description           # Bug fixes
refactor/short-description      # Refactoring
docs/short-description          # Documentation changes
chore/short-description         # Tooling, CI, dependencies

---

Pull Request Process

1. Fork the repository
2. Create a branch from main:

   git checkout -b feature/my-new-feature

3. Write tests for any new functionality
4. Ensure all tests pass:

   php artisan test
   yarn lint

5. Format your code:

   composer run lint
   yarn format

6. Commit with a clear message following Conventional Commits:

   feat: add bill duplication feature
   fix: correct recurring date calculation for leap years
   docs: update API authentication examples
   

7. Push to your fork and open a Pull Request against main
8. Fill out the PR description with:
   • What the change does
   • Why it's needed
   • How to test it
   • Screenshots (for UI changes)

---

Writing Tests

Bill Organizer uses Pest PHP for backend testing.

Feature Tests (API)

test('user can create a bill', function () {
    $user = User::factory()->withTeam()->create();

    $response = $this->actingAs($user)
        ->postJson('/api/v1/bills', [
            'title'    => 'Netflix',
            'amount'   => 15.99,
            'due_date' => '2026-05-01',
        ]);

    $response->assertCreated()
             ->assertJsonPath('data.title', 'Netflix');
});

Running Tests

# All tests
php artisan test

# API tests only
php artisan test tests/Feature/Api

# With coverage report
php artisan test --coverage

# A specific file
php artisan test tests/Feature/Api/V1/BillControllerTest.php

Test coverage expectations:

• Happy path (successful operation)
• Validation errors (missing/invalid fields)
• Authentication requirement (unauthenticated access)
• Authorization checks (wrong team, non-owner actions)
• Edge cases

---

Development Workflow

# Start development servers
composer run dev

# Watch logs in real time
php artisan pail

# Enable query log for debugging
DB::enableQueryLog();
// ...your code...
dd(DB::getQueryLog());

# Reset database
php artisan migrate:fresh --seed

# Clear all caches
php artisan optimize:clear

# Restart queues
php artisan queue:restart

---

Adding a New API Endpoint

1. Add the route to routes/api/v1.php
2. Create or update the controller in app/Http/Controllers/Api/V1/
3. Create or update the resource in app/Http/Resources/Api/V1/
4. Write a feature test in tests/Feature/Api/V1/
5. Update the relevant wiki page (or create a new one)

---

Reporting Issues

• Use GitHub Issues
• Search existing issues before creating a new one
• Include steps to reproduce, expected behavior, and actual behavior
• Attach logs or screenshots where relevant

---

License

By contributing, you agree that your contributions will be licensed under the same GNU General Public License as the project.