Skip to main content

Contributing Guide

Guidelines for contributing to the WorkPayCore Frontend utilities documentation and codebase.

Overview​

We welcome contributions to improve our utilities, documentation, and developer experience. This guide outlines the process for contributing effectively.

Getting Started​

Prerequisites​

  • Node.js 18+ and npm/yarn
  • TypeScript knowledge
  • Familiarity with React and modern frontend development
  • Git for version control

Development Setup​

  1. Clone the Repository:

    git clone https://gitlab.com/tozzaplus_systems/workpay_front_end .

  2. Install Dependencies:

    npm install

  3. Start Development Server:

    npm run dev

  4. Run Tests:

    npm run test

Contributing Process​

1. Issue Creation​

Before contributing, check if an issue exists or create one:

  • Bug Reports: Include steps to reproduce, expected vs actual behavior
  • Feature Requests: Describe the use case and proposed solution
  • Documentation: Identify gaps or improvements needed

2. Branch Strategy​

Follow the GitFlow branching model:

# Feature branches
git checkout -b feature/utility-name

# Bug fix branches
git checkout -b fix/issue-description

# Documentation branches
git checkout -b chore/section-name

3. Development Guidelines​

Code Standards​

  • TypeScript: All new utilities must be written in TypeScript
  • ESLint: Follow the existing ESLint configuration
  • Prettier: Use Prettier for code formatting
  • Testing: Include unit tests for all functions

Utility Structure​

// utils/helpers/my-helper.ts
/**
 * Brief description of the utility
 * @param param1 - Description of parameter
 * @returns Description of return value
 */
export const myUtilityFunction = (param1: string): string => {
  // Implementation
  return result;
};

// Export types
export interface MyUtilityOptions {
  option1: boolean;
  option2?: string;
}

Testing Requirements​

// __tests__/my-helper.test.ts
import { myUtilityFunction } from '../my-helper';

describe('myUtilityFunction', () => {
  it('should handle basic input', () => {
    const result = myUtilityFunction('test');
    expect(result).toBe('expected');
  });

  it('should handle edge cases', () => {
    expect(() => myUtilityFunction('')).toThrow();
  });
});

4. Documentation Requirements​

Function Documentation​

Every utility function requires comprehensive documentation:

### functionName(parameters)

Brief description of what the function does.

**Parameters:**

- `param1` (type): Description of parameter
- `param2` (type, optional): Description with default value

**Returns:**

- `type`: Description of return value

**Example:**

```typescript
import { functionName } from '@/utils/helpers/my-helper';

const result = functionName('input');
console.log(result); // Expected output
```

Use Cases:

  • Primary use case
  • Secondary use case
  • Edge case handling

#### Code Examples

- Include realistic, working examples
- Show both basic and advanced usage
- Demonstrate error handling
- Provide TypeScript types

### 5. Pull Request Process

#### PR Checklist

- [ ] Code follows style guidelines
- [ ] Tests pass locally
- [ ] Documentation is updated
- [ ] Examples are included
- [ ] Breaking changes are documented
- [ ] PR description explains the change

#### PR Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Breaking change

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing completed
- [ ] All tests pass

## Documentation
- [ ] README updated
- [ ] Function documentation added
- [ ] Examples provided

Documentation Contributions​

Documentation Structure​

docs/
├── core-utils/          # Core utility functions
├── helpers/             # Helper functions
├── constants/           # Constants and configuration
├── libraries/           # External library configurations
└── resources/           # Guides and references

Writing Guidelines​

  1. Clear Headings: Use descriptive section headings
  2. Code Examples: Include working, copy-paste examples
  3. Use Cases: Explain when and why to use each utility
  4. TypeScript: Always include type definitions
  5. Cross-References: Link to related utilities

Documentation Style​

  • Tone: Professional but approachable
  • Structure: Consistent formatting across all docs
  • Examples: Real-world, practical examples
  • Completeness: Cover all parameters and return values

Code Review Guidelines​

Reviewer Checklist​

  • Code is readable and well-documented
  • Tests cover edge cases
  • Performance implications considered
  • Security implications reviewed
  • Backward compatibility maintained
  • Documentation is accurate and complete

Review Process​

  1. Automated Checks: CI/CD runs tests and linting
  2. Peer Review: At least one team member reviews
  3. Documentation Review: Technical writer reviews docs
  4. Final Approval: Lead developer approves for merge

Release Process​

Versioning​

We follow Semantic Versioning (SemVer):

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Release Steps​

  1. Version Bump: Update version in package.json
  2. Changelog: Update CHANGELOG.md with changes
  3. Tag Release: Create Git tag for the version
  4. Deploy Docs: Update documentation site
  5. Announce: Notify team of new release

Best Practices​

Code Quality​

  • Single Responsibility: Each function should have one clear purpose
  • Type Safety: Use TypeScript features for better type safety
  • Error Handling: Handle edge cases gracefully
  • Performance: Consider performance implications
  • Testability: Write code that's easy to test

Documentation Quality​

  • Completeness: Document all public APIs
  • Accuracy: Keep documentation in sync with code
  • Examples: Provide practical, working examples
  • Accessibility: Use clear, inclusive language

Collaboration​

  • Communication: Ask questions and seek clarification
  • Feedback: Provide constructive feedback
  • Knowledge Sharing: Share learnings with the team
  • Mentoring: Help new contributors get started

Tools and Resources​

Development Tools​

  • VS Code: Recommended editor with TypeScript support
  • ESLint: For code linting and style enforcement
  • Prettier: For code formatting
  • Jest: For unit testing
  • TypeScript: For type checking

Useful Commands​

# Lint code
npm run lint

# Format code
npm run format

# Run tests
npm run test

# Build documentation
npm run docs:build

# Type check
npm run type-check

Getting Help​

  • Slack: #frontend-utils channel
  • Issues: GitHub issues for bugs and features
  • Wiki: Internal wiki for detailed guides
  • Code Review: Request reviews for guidance

Recognition​

Contributors are recognized through:

  • Changelog: Listed in release notes
  • Contributors: GitHub contributors page
  • Team Shoutouts: Monthly team recognition
  • Career Development: Contributions count toward performance reviews

Thank you for contributing to WorkPayCore Frontend utilities! Your contributions help improve the developer experience for the entire team.