Skip to content

copilot-instructions.md

Latest commit

 

History

History
281 lines (187 loc) · 10 KB

copilot-instructions.md

File metadata and controls

281 lines (187 loc) · 10 KB

Open Source Bazaar - GitHub Copilot Instructions

Open Source Bazaar is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. It includes license filters, Wiki knowledge base, volunteer showcase, Lark integration, and other features.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Critical Requirements

⚠️ MANDATORY NODE.JS VERSION: This project requires Node.js >=20. The build works on Node.js 20+ but may have warnings.

  • Check Node.js version: node --version
  • Development and linting commands work on Node.js 20+
  • Use PNPM as package manager, not NPM or Yarn

Working Effectively

Initial Setup (REQUIRED for all development)

  1. Install global pnpm: npm install -g pnpm
  2. Install dependencies: pnpm install -- takes 1-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
  3. Verify setup: pnpm --version (should be 10.x+)

Important: If you see "node_modules missing" error, you MUST run pnpm install first before any other commands.

Development Workflow (FULLY VALIDATED)

  • Start development server: pnpm dev -- starts in 5-15 seconds on http://localhost:3000
  • Run linting: pnpm lint -- takes 15 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
  • Run tests: pnpm test -- runs lint-staged + lint, takes 15 seconds. Set timeout to 2+ minutes.

Build Process

  • Production build: pnpm build -- works on Node.js 20+ (estimated 30s-2 minutes)
    • NEVER CANCEL. Set timeout to 5+ minutes.
  • Static export: Available but not commonly used in development

Validation Scenarios

After making ANY changes, ALWAYS validate by running through these scenarios:

Manual Testing Requirements

  1. Start development server: pnpm dev and verify it starts without errors
  2. Navigate to homepage: Visit http://localhost:3000 and verify page loads with navigation menu
  3. Test core pages:
  4. Test API endpoints: Verify GitHub API integrations work
  5. Check responsive design: Test mobile/desktop layouts with React Bootstrap components
  6. Verify i18n functionality: Check Chinese/English language switching works

Pre-commit Validation

ALWAYS run before committing changes:

npm test     # Runs linting + staged file checks

Key Project Structure

Important Directories

  • pages/ - Next.js pages and API routes
  • components/ - Reusable React components with Bootstrap styling
  • models/ - MobX stores and data models
  • translation/ - i18n language files (zh-CN, en-US, zh-TW)
  • styles/ - CSS and styling files
  • public/ - Static assets

Configuration Files

  • package.json - Dependencies and scripts
  • next.config.ts - Next.js configuration with MDX support
  • tsconfig.json - TypeScript configuration
  • eslint.config.ts - ESLint configuration
  • babel.config.js - Babel configuration

Key Dependencies

  • Next.js 15 - React framework
  • React Bootstrap 2.10 - UI component library
  • MobX 6.13 - State management
  • MobX-GitHub 0.4 - GitHub API integration
  • MobX-i18n 0.7 - Internationalization
  • License-Filter 0.2 - License filtering functionality
  • Marked 16.2 - Markdown processing

Development Standards and Best Practices

Based on comprehensive PR review analysis, follow these critical development standards:

Architecture and Code Organization

Component and Import Standards

  • ALWAYS use React Bootstrap components instead of custom HTML elements
  • Use utilities from established libraries: 'web-utility'
  • Import './Base' in model files for proper configuration

Error Handling and Static Generation

  • Natural error throwing for static generation - let errors bubble up to catch build issues
  • Ensure build passes before pushing - resolve issues at compile time

UI/UX Standards

Component Usage Patterns

// ✅ Correct - use React Bootstrap components
import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap';

<Button variant="outline-primary" size="sm" href={url} target="_blank">
  {t('edit_on_github')}
</Button>

<Badge bg="secondary">{label}</Badge>

// ❌ Wrong - custom HTML elements
<a href={url} className="btn btn-outline-primary">Edit</a>
<span className="badge bg-secondary">{label}</span>

Semantic HTML Structure

  • Use ordered lists (<ol>) for countable items, unordered lists (<ul>) for navigation
  • Apply proper semantic structure: <article>, <header>, <section>
  • Use list-unstyled class for first-level lists to remove default styling

Code Quality Standards

Modern ECMAScript Features

  • Use optional chaining and modern JavaScript features
  • Let TypeScript infer types when possible to avoid verbose annotations
  • Use modern ECMAScript patterns for cleaner, more maintainable code

Import and Type Management

  • Import from established sources: ContentModel from mobx-github, utilities from web-utility
  • Import configuration files where needed: './Base' for GitHub client setup
  • Use minimal exports and avoid unnecessary custom implementations
  • Use configured clients rather than creating new ones

Translation and Internationalization

Critical Translation Requirements

  • ALL user-facing text MUST be translated using i18n system
  • This includes button text, labels, error messages, placeholder text, and dynamic content
  • Use the t() function from I18nContext for all translations

Translation Patterns

  • Use the t() function from I18nContext for all user-facing text
  • Translate all button text, labels, error messages, and dynamic content
  • Avoid hardcoded text in any language

Translation Key Management

  • Use generic terms unless specifically scoped: t('knowledge_base') not t('policy_documents')
  • Add translation keys to ALL language files: zh-CN.ts, en-US.ts, zh-TW.ts
  • Remove unused translation keys when replacing with generic ones

Data Modeling and Content Management

Content Model Patterns

  • Use ContentModel with configured client from mobx-github
  • Import configuration via './Base' to ensure proper GitHub client setup
  • Handle Base64 content decoding when processing GitHub API responses

Tree Structure and Navigation

  • Use treeFrom utility from web-utility for hierarchical data structures
  • Follow established patterns for tree node organization and navigation

GitHub Integration Standards

API Usage Patterns

  • Import configured githubClient from models/Base.ts

Authentication and Rate Limiting

  • GitHub API authentication is configured in models/Base.ts
  • Use the configured client to avoid rate limiting and authentication issues
  • Don't create separate GitHub API instances

Build and Development Process

Pre-commit Standards

  1. Run linting: pnpm lint to auto-fix formatting
  2. Check build: Ensure pnpm build passes
  3. Validate translations: Verify all text is properly translated
  4. Remove unused code: Clean up unused imports and translation keys

Code Review Compliance

  • Follow exact code suggestions from reviews when provided
  • Use minimal approach - only include explicitly requested functionality
  • Don't add extra features not specified in requirements
  • Address reviewer feedback completely before requesting re-review

Common Commands Reference

Package Management

pnpm install          # Install dependencies (1-3 minutes)
pnpm --version        # Check pnpm version

Development

pnpm dev             # Start development server (5-15s)
pnpm build           # Production build (30s-2min)
pnpm start           # Start production server

Code Quality

pnpm lint            # Run ESLint with auto-fix (15s)
pnpm test            # Run tests (lint-staged + lint, 15s)

Troubleshooting

Common Issues and Solutions

Build and Development Issues

  • "Unsupported engine" warnings: Expected on Node.js <22, development still works
  • Build hangs: Never cancel builds - they may take several minutes, set appropriate timeouts
  • Missing dependencies: Always run pnpm install first

Component and Styling Issues

  • Custom HTML not working: Replace with React Bootstrap components
  • Translation not showing: Ensure all text uses t() function and keys exist in all language files
  • GitHub API errors: Verify you're using configured githubClient from models/Base.ts

Data and Content Issues

  • Base64 content errors: Use atob(item.content) to decode GitHub API responses
  • Missing content: Check ContentModel configuration and repository access
  • Tree structure problems: Use treeFrom() utility from web-utility

Development Environment Setup

  • Clear browser cache if components don't render properly
  • Restart development server after major configuration changes
  • Verify all translation files are updated when adding new keys

Project-Specific Patterns

Wiki System Architecture

  • Uses GitHub ContentModel to access policy documents from fpsig/open-source-policy repository
  • Renders markdown content with front-matter metadata
  • Supports hierarchical document structure with breadcrumb navigation

License Filter Integration

  • Interactive multi-step license selection process
  • Uses license-filter package for license recommendation logic
  • Supports multiple languages with comprehensive i18n coverage

Volunteer Management

  • Displays GitHub organization contributors
  • Integrates with OSS Insight widgets for contributor analytics
  • Uses GitHub API for real-time contributor data

Always prioritize these project-specific standards over generic Next.js or React guidance when working in this specific codebase.