Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
245 lines (186 loc) · 7.29 KB

CONTRIBUTING.md

File metadata and controls

245 lines (186 loc) · 7.29 KB

Contributing to SBDK.dev

Note: This project is archived as a reference implementation (November 2025). While we welcome bug reports and documentation improvements, for new features or significant changes, we recommend forking the project.

Thank you for your interest in contributing to SBDK.dev! Here's how you can help:

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

How Can I Contribute?

For This Repository (Archived Reference)

Since this is an archived reference implementation, we accept:

✅ Bug Reports - Critical issues that affect functionality ✅ Documentation Improvements - Clarifications, fixes, better examples ✅ Security Issues - Report via Security Advisories

❌ New Features - Consider forking for major additions ❌ Breaking Changes - Fork and create your own version

For New Features: Fork & Build Your Own

This project is designed to be forked and adapted:

  1. Fork this repository
  2. Make your changes freely
  3. Share your fork - Open an issue to showcase what you built!

We encourage you to use this as a starting point for your own projects.

Areas Where Contributions Are Welcome

  • 🐛 Bug fixes - Fix broken functionality
  • 📝 Documentation - Improve clarity, fix typos, add examples
  • ♿ Accessibility - WCAG compliance improvements
  • 🔒 Security - Vulnerability fixes

Development Setup

Prerequisites

  • Node.js 18 or higher
  • npm or yarn
  • Git

Installation

  1. Fork the repository on GitHub

  2. Clone your fork

    git clone https://github.com/YOUR_USERNAME/sbdk.dev.git
cd sbdk.dev

  3. Add upstream remote

    git remote add upstream https://github.com/sbdk-dev/sbdk.dev.git

  4. Install dependencies

    npm install

  5. Run development server

    npm run dev

  6. Open your browser Navigate to http://localhost:3000

Available Scripts

npm run dev        # Start development server with hot reload
npm run build      # Build for production
npm start          # Start production server
npm run lint       # Run ESLint to check code quality
npm run type-check # Run TypeScript type checking

Pull Request Process

Before Submitting

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Write clean, readable code
    • Follow existing code style
    • Add comments for complex logic
    • Update documentation if needed

  3. Test your changes

    npm run build      # Ensure production build succeeds
npm run lint       # Check for linting errors
npm run type-check # Check for TypeScript errors

  4. Commit your changes

    git add .
git commit -m "feat: add new feature description"

    Use conventional commit messages:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation changes
    • style: - Code style changes (formatting, etc.)
    • refactor: - Code refactoring
    • perf: - Performance improvements
    • test: - Adding or updating tests
    • chore: - Maintenance tasks

  5. Push to your fork

    git push origin feature/your-feature-name

Submitting the PR

  1. Go to the SBDK.dev repository
  2. Click "New Pull Request"
  3. Select your fork and branch
  4. Fill out the PR template with:
    • Description - What does this PR do?
    • Motivation - Why is this change needed?
    • Testing - How did you test this?
    • Screenshots - If UI changes are involved
    • Checklist - Complete the checklist items

Review Process

  • Maintainers will review your PR within a few days
  • Address any requested changes
  • Once approved, your PR will be merged
  • Your contribution will be acknowledged in release notes

Style Guidelines

TypeScript/React

  • Use TypeScript for all new files
  • Use functional components with hooks
  • Keep components small and focused
  • Extract reusable logic into custom hooks
  • Use meaningful variable names

Tailwind CSS

  • Use Tailwind utility classes over custom CSS
  • Follow mobile-first responsive design
  • Use the project's design system colors/spacing
  • Group classes logically (layout → spacing → colors → typography)

Example:

<div className="flex items-center gap-4 px-6 py-4 bg-white dark:bg-gray-900 rounded-lg">
  // content
</div>

Code Formatting

  • Run npm run lint before committing
  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Add trailing commas in objects/arrays

Accessibility

  • Use semantic HTML elements
  • Add ARIA labels where needed
  • Ensure keyboard navigation works
  • Maintain color contrast ratios (WCAG AA)
  • Test with screen readers when possible

Performance

  • Optimize images (use next/image)
  • Lazy load components when appropriate
  • Minimize bundle size
  • Avoid unnecessary re-renders

Project Structure

sbdk.dev/
├── app/                    # Next.js App Router pages
│   ├── layout.tsx         # Root layout with SEO metadata
│   ├── page.tsx           # Landing page (10 sections)
│   ├── pricing/           # Pricing page
│   └── globals.css        # Global styles
├── components/             # Reusable React components
│   ├── PipelineVisualizer.tsx  # Pipeline flow visualization
│   ├── InteractiveTerminal.tsx # CLI sandbox
│   ├── DataTableViewer.tsx     # DuckDB results
│   ├── Logo.tsx               # Brand logo component
│   └── ThemeProvider.tsx      # Dark mode provider
├── docs/                   # 📚 Documentation
│   ├── ARCHITECTURE.md    # Technical architecture
│   ├── DEPLOYMENT.md      # Deployment guides
│   └── README.md          # Docs index
├── public/                 # Static assets
│   ├── brand/             # Logo variants & guidelines
│   ├── favicon.svg        # Site icon
│   ├── og-image.svg       # Social sharing image
│   └── llms.txt           # AI crawler file
├── .github/                # GitHub templates
│   ├── ISSUE_TEMPLATE/    # Bug & feature templates
│   └── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md         # This file
├── CODE_OF_CONDUCT.md     # Community standards
├── SECURITY.md            # Security policy
└── README.md              # Project overview

Questions?

Thank you for contributing to SBDK.dev! 🎉