skillhub/CONTRIBUTING.md

Contributing to SkillHub

Thank you for your interest in contributing to SkillHub! This document provides guidelines and instructions for contributing.

---

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Standards
• Commit Messages

---

Code of Conduct

This project follows the Contributor Covenant. Please be respectful and constructive in all interactions.

---

How Can I Contribute?

Report Bugs

Found a bug? Please open an issue with:

1. Clear title describing the problem
2. Steps to reproduce the issue
3. Expected behavior vs actual behavior
4. Environment details (OS, Node version, browser)
5. Screenshots if applicable

Suggest Features

Have an idea? Open an issue with:

1. Use case - What problem does it solve?
2. Proposed solution - How should it work?
3. Alternatives considered - What else did you think about?

Submit Skills

Want to add your skill to SkillHub?

1. Ensure your repository has a valid SKILL.md file
2. Go to skills.palebluedot.live/claim
3. Sign in with GitHub
4. Submit your repository URL

Code Contributions

We welcome code contributions for:

• Bug fixes
• New features
• Performance improvements
• Documentation updates
• Test coverage
• Translations (i18n)

---

Development Setup

Prerequisites

• Node.js 18+
• pnpm 9+
• Docker (for database and services)
• Git

Setup Steps

# Clone the repository
git clone https://github.com/airano-ir/skillhub.git
cd skillhub

# Install dependencies
pnpm install

# Copy environment file
cp .env.example .env

# Start infrastructure (database, redis, meilisearch)
docker compose up -d db redis meilisearch

# Run database migrations
pnpm db:push

# Seed sample data (optional)
docker exec -i skillhub-db psql -U postgres -d skillhub < scripts/seed-data.sql

# Start development servers
pnpm dev

Project Scripts

pnpm dev          # Start all apps in dev mode
pnpm build        # Build all packages
pnpm test         # Run all tests
pnpm lint         # Lint all packages
pnpm typecheck    # TypeScript type checking

Package-Specific Commands

# Web app
pnpm --filter @skillhub/web dev
pnpm --filter @skillhub/web build

# CLI
pnpm --filter skillhub dev
pnpm --filter skillhub build

# Core library
pnpm --filter skillhub-core test

# Database
pnpm --filter @skillhub/db studio  # Open Drizzle Studio

---

Pull Request Process

Before Submitting

1. Create an issue first - Discuss your change before implementing
2. Fork the repository - Work on your own fork
3. Create a feature branch - git checkout -b feature/your-feature
4. Write tests - Add tests for new functionality
5. Run tests locally - pnpm test
6. Lint your code - pnpm lint

PR Guidelines

1. Title format: type(scope): description

   • Types: feat, fix, docs, style, refactor, test, chore
   • Example: feat(cli): add update --all command

2. Description should include:

   • What changes were made
   • Why the changes were needed
   • How to test the changes
   • Screenshots (for UI changes)

3. Keep PRs focused - One feature/fix per PR

4. Update documentation - If your change affects user-facing features

Review Process

1. Maintainers will review within 3-5 business days
2. Address feedback promptly
3. Once approved, a maintainer will merge

---

Coding Standards

TypeScript

• Use TypeScript for all new code
• Enable strict mode
• Avoid any type - use unknown or proper types
• Use interfaces over types when possible

// Good
interface SkillMetadata {
  name: string;
  description: string;
  version?: string;
}

// Avoid
const skill: any = fetchSkill();

React/Next.js

• Use functional components with hooks
• Prefer server components where possible
• Use next-intl for translations
• Follow Next.js 15 patterns (async params, etc.)

// Good - Next.js 15 pattern
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  // ...
}

Styling

• Use Tailwind CSS
• Follow design token system (bg-surface, text-text-primary)
• Avoid hardcoded colors
• Support dark mode

// Good
<div className="bg-surface text-text-primary">

// Avoid
<div className="bg-white text-gray-900">

Testing

• Write unit tests for utilities and functions
• Write integration tests for API routes
• Use Vitest for unit tests
• Use Playwright for E2E tests

// Example test
import { describe, it, expect } from 'vitest';

describe('parseSkillMd', () => {
  it('should parse valid SKILL.md', () => {
    const result = parseSkillMd(validInput);
    expect(result.name).toBe('expected-name');
  });
});

---

Commit Messages

Follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting (no code change)
refactor	Code restructuring
test	Adding tests
chore	Maintenance

Examples

feat(cli): add search command with category filter
fix(web): resolve RTL layout issues on skill page
docs: update README with new installation steps
test(core): add tests for SKILL.md parser

---

Questions?

• GitHub Discussions: For general questions
• GitHub Issues: For bugs and feature requests
• Discord: Coming soon

---

Thank you for contributing to SkillHub!