Skip to content

Contributing

This document provides guidelines for contributing to the Stratpoint Timesheet Application. Whether you're fixing bugs, adding features, or improving documentation, these guidelines will help ensure a smooth contribution process.

Getting Started

Prerequisites

Before contributing, ensure you have:

  • PHP 8.1 or higher
  • Node.js 18 or higher
  • MySQL 8.0 or higher
  • Redis 7.0 or higher
  • Composer
  • Git

Development Environment Setup

  1. Clone the repository 

    git clone https://github.com/stratpoint/timesheet-application.git
cd timesheet-application

  2. Install dependencies 

    composer install
npm install

  3. Environment configuration 

    cp .env.example .env
php artisan key:generate

  4. Database setup 

    php artisan migrate
php artisan db:seed

  5. Build assets 

    npm run dev

  6. Start development server 

    php artisan serve

Contribution Workflow

Branch Strategy

We use Git Flow branching model:

graph LR
    A[main] --> B[develop]
    B --> C[feature/feature-name]
    B --> D[bugfix/bug-description]
    B --> E[hotfix/critical-fix]

    C --> B
    D --> B
    E --> A
    E --> B

Branch Naming Conventions

  • Feature branches: feature/JIRA-123-add-timesheet-approval
  • Bug fix branches: bugfix/JIRA-456-fix-calculation-error
  • Hotfix branches: hotfix/JIRA-789-security-patch
  • Release branches: release/v2.1.0

Commit Message Format

Follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools

Examples

feat(timesheet): add bulk approval functionality

- Add bulk selection for timesheet entries
- Implement batch approval API endpoint
- Add confirmation dialog for bulk actions

Closes JIRA-123

fix(auth): resolve JWT token expiration issue

The JWT tokens were expiring too quickly due to incorrect
timezone calculation in the token generation logic.

Fixes JIRA-456

Code Contribution Guidelines

Code Quality Standards

  1. Follow PSR-12 coding standards for PHP
  2. Use ESLint configuration for JavaScript
  3. Maintain test coverage above 80%
  4. Write self-documenting code with clear variable and function names
  5. Add PHPDoc comments for all public methods
  6. Follow SOLID principles

Pull Request Process

  1. Create feature branch from develop 

    git checkout develop
git pull origin develop
git checkout -b feature/JIRA-123-new-feature

  2. Make your changes following coding standards

  3. Write tests for new functionality 

    # Run tests
php artisan test
npm run test

  4. Update documentation if necessary

  5. Commit changes with descriptive messages 

    git add .
git commit -m "feat(timesheet): add bulk approval functionality"

  6. Push to your branch 

    git push origin feature/JIRA-123-new-feature

  7. Create Pull Request with detailed description

Pull Request Template

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issues
- Closes JIRA-123
- Related to JIRA-456

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Browser compatibility tested

## Screenshots (if applicable)
Add screenshots to help explain your changes.

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Code Review Process

For Contributors

  1. Self-review your code before submitting
  2. Ensure all tests pass locally
  3. Update documentation as needed
  4. Respond promptly to review feedback
  5. Make requested changes in additional commits

For Reviewers

  1. Review within 24 hours of submission
  2. Check code quality and adherence to standards
  3. Verify test coverage and functionality
  4. Provide constructive feedback
  5. Approve or request changes with clear explanations

Review Checklist

  • [ ] Code follows project coding standards
  • [ ] All tests pass
  • [ ] Test coverage is adequate
  • [ ] Documentation is updated
  • [ ] No security vulnerabilities introduced
  • [ ] Performance impact considered
  • [ ] Breaking changes documented
  • [ ] Database migrations are reversible
  • [ ] Error handling is appropriate

Testing Requirements

Required Tests

  1. Unit Tests for all new functions/methods
  2. Feature Tests for API endpoints
  3. Integration Tests for complex workflows
  4. Browser Tests for UI changes

Test Examples

Unit Test Example

/** @test */
public function it_calculates_overtime_hours_correctly()
{
    // Arrange
    $user = User::factory()->create();
    $regularHours = 40;
    $totalHours = 45;

    // Act
    $overtimeHours = $this->timesheetService->calculateOvertimeHours($user, $totalHours, $regularHours);

    // Assert
    $this->assertEquals(5, $overtimeHours);
}

Feature Test Example

/** @test */
public function authenticated_user_can_approve_timesheet()
{
    // Arrange
    $manager = User::factory()->create(['role' => 'manager']);
    $timesheet = Timesheet::factory()->create(['approval_status' => 'pending']);

    Sanctum::actingAs($manager);

    // Act
    $response = $this->putJson("/api/timesheets/{$timesheet->id}/approve");

    // Assert
    $response->assertStatus(200);
    $this->assertDatabaseHas('timelogs', [
        'id' => $timesheet->id,
        'approval_status' => 'approved'
    ]);
}

Documentation Guidelines

Documentation Types

  1. Code Documentation: PHPDoc comments, inline comments
  2. API Documentation: OpenAPI/Swagger specifications
  3. User Documentation: Feature guides, tutorials
  4. Technical Documentation: Architecture, deployment guides

Documentation Standards

  • Use clear, concise language
  • Include code examples where appropriate
  • Keep documentation up-to-date with code changes
  • Use proper markdown formatting
  • Include diagrams for complex concepts

Example Documentation

/**
 * Calculate utilization rate for a user in a given period
 *
 * This method calculates the utilization rate by comparing actual hours
 * worked against expected hours based on working days in the period.
 *
 * @param User $user The user to calculate utilization for
 * @param Carbon $startDate Start of the calculation period
 * @param Carbon $endDate End of the calculation period
 * @return float Utilization rate as percentage (0-100)
 * @throws TimesheetException When no working days in period
 * 
 * @example
 * $rate = $service->calculateUtilizationRate($user, $start, $end);
 * // Returns: 85.5 (representing 85.5% utilization)
 */
public function calculateUtilizationRate(User $user, Carbon $startDate, Carbon $endDate): float
{
    // Implementation...
}

Issue Reporting

Bug Reports

When reporting bugs, include:

  1. Clear description of the issue
  2. Steps to reproduce the problem
  3. Expected behavior
  4. Actual behavior
  5. Environment details (OS, browser, PHP version)
  6. Screenshots or logs if applicable

Bug Report Template

## Bug Description
A clear and concise description of what the bug is.

## Steps to Reproduce
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

## Expected Behavior
A clear and concise description of what you expected to happen.

## Actual Behavior
A clear and concise description of what actually happened.

## Screenshots
If applicable, add screenshots to help explain your problem.

## Environment
- OS: [e.g. macOS 12.0]
- Browser: [e.g. Chrome 95.0]
- PHP Version: [e.g. 8.1.0]
- Laravel Version: [e.g. 8.75.0]

## Additional Context
Add any other context about the problem here.

Feature Requests

When requesting features, include:

  1. Problem statement - what problem does this solve?
  2. Proposed solution - how should it work?
  3. Alternative solutions - what other approaches were considered?
  4. Use cases - who would benefit from this feature?
  5. Priority level - how important is this feature?

Security Guidelines

Security Considerations

  1. Never commit sensitive data (passwords, API keys, etc.)
  2. Use environment variables for configuration
  3. Validate all input from users
  4. Sanitize output to prevent XSS
  5. Use parameterized queries to prevent SQL injection
  6. Follow OWASP guidelines

Reporting Security Issues

For security vulnerabilities:

  1. Do not create public issues
  2. Email security team directly: security@stratpoint.com
  3. Include detailed description and reproduction steps
  4. Allow time for fix before public disclosure

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

  1. Be respectful and professional
  2. Be collaborative and helpful
  3. Be patient with newcomers
  4. Focus on constructive feedback
  5. Respect different viewpoints

Communication Channels

  • Slack: #timesheet-dev channel
  • Email: dev-team@stratpoint.com
  • Jira: For issue tracking
  • Confluence: For documentation

Recognition

Contributors will be recognized through:

  • Contributor list in README
  • Release notes acknowledgments
  • Team meetings recognition
  • Annual awards for significant contributions

Thank you for contributing to the Stratpoint Timesheet Application!