Contributing

Guidelines for contributing to the 2KRIKA project and maintaining code quality.

Overview

Git workflow for collaboration
Code review process
Branch naming conventions
Commit message standards
Pull request checklist
Issue tracking guidelines

Getting Started

Prerequisites

Clone repository:

git clone https://github.com/OryStack/2-krika-backend.git
cd 2-krika-backend

Install dependencies:
```
pnpm install
```

Setup environment:

cp .env.example .env
# Edit .env with your configuration

Run migrations:
```
pnpm dev:migrate
pnpm dev:seed
```
Start development server:
```
pnpm dev
```

Git Workflow

Branching Strategy

Main branches: - main – Production-ready code - develop – Integration branch for features - staging – Pre-production testing

Feature branches:

feature/feature-name
bugfix/bug-description
hotfix/critical-fix
docs/documentation-update
refactor/code-improvement
test/test-coverage

Creating Feature Branch

# Update develop
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/add-payment-retry

# Work on feature
git add .
git commit -m "feat: add payment retry logic"

# Push to remote
git push -u origin feature/add-payment-retry

Branch Naming Convention

Pattern: type/short-description

# Features
feature/user-notifications
feature/order-cancellation
feature/service-reviews

# Bug fixes
bugfix/payment-verification
bugfix/order-state-machine
bugfix/email-template

# Hotfixes (production)
hotfix/critical-security-fix
hotfix/payment-gateway-timeout

# Documentation
docs/api-documentation
docs/setup-guide

# Refactoring
refactor/repository-pattern
refactor/error-handling

# Tests
test/order-use-cases
test/payment-integration

Commit Messages

Convention

Follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code formatting (no logic change)
refactor: Code restructuring
test: Adding or updating tests
chore: Maintenance tasks
perf: Performance improvements
ci: CI/CD changes

Examples

Feature:

git commit -m "feat(orders): add order cancellation by customer"

Bug fix:

git commit -m "fix(payments): handle payment verification timeout

- Add retry logic for failed verifications
- Increase timeout from 30s to 60s
- Log verification attempts

Fixes #123"

Breaking change:

git commit -m "feat(auth)!: change JWT token expiration

BREAKING CHANGE: Access tokens now expire after 15 minutes instead of 1 hour.
Clients need to implement token refresh flow."

Documentation:

git commit -m "docs: update installation guide with Redis setup"

Refactoring:

git commit -m "refactor(repositories): extract base repository class

- Create AbstractRepository interface
- Implement BaseRepository with common methods
- Update all repositories to extend BaseRepository"

Commit Message Rules

✅ Do: - Use imperative mood ("add" not "added") - Keep subject line under 50 characters - Capitalize subject line - No period at end of subject - Separate subject from body with blank line - Wrap body at 72 characters - Explain what and why, not how

❌ Don't: - Don't use vague messages ("fix bug", "update code") - Don't combine unrelated changes - Don't commit broken code - Don't commit commented code - Don't commit console.log statements

Pull Request Process

Creating Pull Request

Push feature branch:

git push -u origin feature/add-payment-retry

Open PR on GitHub:
Go to repository
Click "New Pull Request"
Select base branch (usually develop)
Select compare branch (your feature)
Fill PR template:

## Description
Brief description of changes

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

## Changes Made
- Added payment retry logic
- Updated payment gateway timeout
- Added retry configuration to .env

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

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests pass locally
- [ ] Dependent changes merged

## Related Issues
Closes #123

PR Checklist

Before submitting PR:

[ ] Tests pass – pnpm test succeeds
[ ] Linter clean – pnpm lint passes
[ ] Formatted – pnpm format passes
[ ] Type-safe – No TypeScript errors
[ ] Build succeeds – pnpm build works
[ ] Documentation updated – If needed
[ ] Migrations tested – If database changes
[ ] No console.log – Use logger instead
[ ] Branch updated – Rebased on latest develop
[ ] Meaningful commits – Follow convention

Code Review

As Author: - Respond to all comments - Make requested changes - Mark resolved discussions - Keep PR focused and small - Add reviewers promptly

As Reviewer: - Review within 24 hours - Be constructive and respectful - Test locally if needed - Check for security issues - Verify tests are adequate - Approve when satisfied

Review Comments

Requesting changes:

Please add error handling for null values here.

Suggestion:
if (!order) {
  throw new OrderNotFoundError(orderId);
}

Approving with suggestions:

LGTM! Minor suggestion: Consider extracting this logic into a separate function for reusability.

Blocking issues:

⚠️ Security concern: User input not sanitized before database query.
This needs to be fixed before merging.

Code Style

Follow Coding Standards

See Coding Standards for details:

TypeScript strict mode
ESLint rules
Prettier formatting
Clean Architecture layers
SOLID principles
Consistent naming

Pre-commit Checks

Install Git hooks:

# .husky/pre-commit
#!/bin/sh
pnpm lint
pnpm test

Or use manual check:

pnpm lint && pnpm test && pnpm format

Testing Requirements

Test Coverage

Maintain minimum 80% coverage:

# Run with coverage
pnpm test --coverage

# Check coverage report
open coverage/lcov-report/index.html

Test Types

Unit Tests – Required for: - Domain entities - Value objects - Use cases - Validators

Integration Tests – Required for: - Repositories - Gateways - API endpoints - Database operations

Example:

describe('Order Use Cases', () => {
  it('should create order with valid data', async () => {
    const order = await createOrder(validData, userId, repo);
    expect(order.status).toBe('pending');
  });

  it('should reject unauthorized user', async () => {
    await expect(
      createOrder(data, unauthorizedUserId, repo)
    ).rejects.toThrow(ForbiddenError);
  });
});

Documentation

Update Documentation

When adding features:

Code comments – JSDoc for public APIs
README – Update setup if needed
CHANGELOG – Add entry for version
API docs – Update Swagger annotations
User guide – Add feature documentation

Documentation Standards

/**
 * Creates a new order for a service.
 * 
 * @param data - The order creation data
 * @param customerId - ID of the customer creating order
 * @param orderRepo - Order repository instance
 * @returns Promise resolving to created order
 * 
 * @throws {ValidationError} If order data is invalid
 * @throws {ForbiddenError} If user not authorized
 * @throws {NotFound} If service not found
 * 
 * @example
 * ```typescript
 * const order = await createOrder(
 *   { serviceId: 'svc-123', quantity: 1 },
 *   'user-456',
 *   orderRepository
 * );
 * ```
 */
export async function createOrder(
  data: CreateOrderDTO,
  customerId: string,
  orderRepo: OrderRepository,
): Promise<Order> {
  // Implementation
}

Issue Tracking

Creating Issues

Bug Report:

## Bug Description
Clear description of the bug

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

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: Ubuntu 22.04
- Node: v20.11.0
- pnpm: 10.7.1

## Additional Context
Screenshots, logs, etc.

Feature Request:

## Feature Description
Clear description of proposed feature

## Problem It Solves
Why this feature is needed

## Proposed Solution
How it could be implemented

## Alternatives Considered
Other approaches evaluated

## Additional Context
Mockups, examples, etc.

Issue Labels

bug – Something isn't working
feature – New feature request
enhancement – Improvement to existing feature
documentation – Documentation improvements
help wanted – Extra attention needed
good first issue – Good for newcomers
priority: high – Urgent issue
priority: low – Nice to have

Release Process

Version Numbering

Follow Semantic Versioning:

MAJOR (1.0.0) – Breaking changes
MINOR (0.1.0) – New features (backward compatible)
PATCH (0.0.1) – Bug fixes

Creating Release

Update CHANGELOG.md:

## [1.2.0] - 2024-01-15

### Added
- Payment retry logic for failed transactions
- Order cancellation by customer

### Fixed
- Payment verification timeout issues
- Email template rendering

### Changed
- Increased JWT expiration to 1 hour

Update version:

# Update package.json version
pnpm version minor  # or major/patch

Create release tag:

git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

Deploy to production:

# Via CI/CD pipeline or manual deployment

Communication

Channels

GitHub Issues – Bug reports, feature requests
GitHub Discussions – Questions, ideas
Pull Requests – Code review, discussions
Slack/Discord – Team communication (if applicable)

Code of Conduct

Be respectful and inclusive
Accept constructive criticism
Focus on what's best for the project
Show empathy towards others
Assume good intentions

Best Practices Summary

✅ Do

Write tests – For all new code
Follow conventions – Coding standards, commit messages
Document changes – Update relevant docs
Small PRs – Easier to review
Review thoroughly – Both as author and reviewer
Keep main stable – Never commit broken code
Communicate – Ask questions, share ideas
Update dependencies – Keep packages current

❌ Don't

Don't commit to main – Always use feature branches
Don't skip tests – Maintain coverage
Don't ignore reviews – Address all feedback
Don't make huge PRs – Break into smaller changes
Don't break builds – Test before pushing
Don't duplicate code – DRY principle
Don't hardcode secrets – Use environment variables
Don't ignore conventions – Follow project standards

Getting Help

Resources

Documentation – Read project docs first
Code examples – Check existing code
Tests – See how features are tested
Issues – Search for similar problems
Team – Ask teammates for help

Asking Questions

Good question format:

## What I'm trying to do
Create order with custom delivery time

## What I've tried
- Checked Order entity
- Reviewed createOrder use case
- Searched documentation

## Specific question
How do I validate custom delivery time against service limits?

## Code context
[Include relevant code snippet]

Summary

Contributing effectively requires:

Following conventions – Git, commits, code style
Writing tests – Maintain quality
Good communication – Clear PRs and reviews
Documentation – Keep docs updated
Respect – Collaborate professionally

Thank you for contributing to 2KRIKA! Your efforts help make the project better for everyone.