Skip to content

Development Conventions

Jump to bottom
Loacky edited this page Dec 31, 2025 · 4 revisions

Development Conventions

These are the standard conventions that all CrowdUp developers must follow to maintain a coherent and organized codebase.

Git Workflow

Branch Naming Convention

Branch names must follow the format: type/scope/description

Branch Types

  • feature/ - New features
feature/auth-google-oauth
feature/post-creation-form
feature/company-verification
  • enhancement/ - New Enhancement
enhancement/admin-panel
enhancement/filter-button
enhancement/company-verification
  • bugfix/ - Bug fixes
bugfix/trending-hardcoded-data
bugfix/localStorage-vulnerability
bugfix/image-upload-validation
  • hotfix/ - Urgent production fixes
hotfix/critical-security-patch
hotfix/database-connection-issue
  • docs/ - Documentation and wiki
docs/setup-instructions
docs/api-endpoints
docs/deployment-guide
  • refactor/ - Code improvements without new features
refactor/auth-context
refactor/api-routes-organization
refactor/component-structure
  • chore/ - Maintenance, dependencies, configuration
chore/update-dependencies
chore/eslint-configuration
chore/github-actions-setup

Rules

  • Use lowercase
  • Separate words with hyphens (-)
  • Be descriptive but concise (max 50 characters)
  • Don't use numbers directly, use issue numbers

Commit Message Format

Follow the Conventional Commits format:

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

<body>

<footer>

Commit Types

  • feat - New feature
feat(auth): add Google OAuth integration
  • fix - Bug fix
fix(trending): replace hardcoded data with database queries
  • docs - Documentation updates
docs(setup): add environment variables section
  • style - Formatting, semicolons, etc. (no logic changes)
style(components): format PostCard spacing
  • refactor - Code refactoring
refactor(auth-context): simplify token validation
  • perf - Performance improvements
perf(database): add indexes to posts table
  • test - Adding or modifying tests
test(auth): add login flow tests
  • chore - Maintenance
chore(deps): upgrade Next.js to 15.4.10

Complete Examples

feat(auth): implement localStorage security fix (#36)

Remove user object from localStorage and implement async 
fetching from database. Replace with httpOnly cookies for
token storage to prevent XSS vulnerabilities.

Fixes #36

fix(trending): replace hardcoded data with database queries (#14)

Implement getTrendingPosts and getTrendingCompanies functions.
Add real-time ranking based on votes, comments, and recency.

Closes #14

Pull Request Conventions

PR Title Format

[type] Brief description (#issue-number)

Examples:

  • [Feature] Add Google OAuth integration (#5)
  • [Bugfix] Fix localStorage XSS vulnerability (#36)
  • [Docs] Add API documentation (#21)

PR Description

Just use Copilot summary. Remember to link related issues (see template)

If needed use this template:

## Description

Brief description of changes

## Type of Change

- [ ] New feature
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation update

## Related Issues

Closes #123

## How to Test

Explain how to test the changes

## Checklist

- [ ] Code follows style guidelines
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No new warnings

Code Style Conventions

Naming Conventions

  • File names: kebab-case for components, camelCase for utilities
  • Folders: kebab-case
  • Functions: camelCase
  • Constants: UPPER_SNAKE_CASE
  • Classes/Interfaces: PascalCase
  • Database columns: snake_case 
src/
  components/
    post-card.tsx
    user-profile.tsx
  hooks/
    useAuth.ts
    usePosts.ts
  lib/
    api-client.ts
    format-date.ts
  constants/
    API_ENDPOINTS.ts
    VALIDATION_RULES.ts

Testing Conventions

  • Create test files at the same level as the component/function
  • Naming: fileName.test.ts or __tests__/fileName.ts
  • Coverage target: 70%+
  • Test behavior, not implementation
// ✅ Correct
describe('PostCard', () => {
  it('should call onVote when clicked', () => {
    const onVote = jest.fn();
    render(<PostCard id="123" title="Test" onVote={onVote} />);
    fireEvent.click(screen.getByText('Test'));
    expect(onVote).toHaveBeenCalledWith('123');
  });
});

Documentation Conventions

  • Document public functions with JSDoc
  • Add comments for complex logic
  • Keep README and wiki up to date
  • Add usage examples
/**
 * Fetches trending posts from the database
 * @param limit - Maximum number of posts to return (default: 10)
 * @param timeWindow - Time window in hours (default: 24)
 * @returns Promise of trending posts array
 */
const getTrendingPosts = async (
  limit: number = 10,
  timeWindow: number = 24
): Promise<Post[]> => {
  // implementation
};

Review Checklist

Before opening a PR, ensure that:

  • Branch created from main and up to date
  • Commit messages follow conventions
  • No console.log or debug code
  • Type errors resolved
  • Linting passes (npm run lint)
  • Tests pass (npm run test)
  • Build passes (npm run build)
  • Documentation updated if necessary
  • No conflicts with main

CrowdUp Wiki

Start Here

Guides and development

Support and troubleshooting

Clone this wiki locally