Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
318 lines (222 loc) · 7.3 KB

CONTRIBUTING.md

File metadata and controls

318 lines (222 loc) · 7.3 KB

Contributing to Bearnie

Thank you for your interest in contributing to Bearnie! We welcome contributions of all kinds, including bug reports, feature requests, documentation improvements, and code contributions.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.

AI-Generated Pull Requests

We do not accept pull requests that are fully generated by AI tools (Claude, ChatGPT, Copilot, etc.) without meaningful human review and understanding.

Why?

  • We value contributions from people who understand the codebase
  • AI-generated code often lacks context and can introduce subtle bugs
  • We want contributors to learn and grow, not just copy-paste AI output

What's acceptable:

  • Using AI as a coding assistant while you write and understand the code
  • AI-assisted code that you've reviewed, tested, and can explain

What's not acceptable:

  • Submitting AI-generated PRs without understanding the changes
  • Using AI bots to automatically create issues or PRs

PRs that appear to be fully AI-generated without human oversight will be closed.

Getting Started

Prerequisites

  • Node.js 18+ and npm 9+
  • Git
  • Basic familiarity with Astro and Tailwind CSS

Local Development Setup

  1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/bearnie.git
cd bearnie
npm install
  1. Create a feature branch
git checkout -b feature/your-feature-name
  1. Start the development server
npm run dev

The site will be available at http://localhost:4321

  1. Build the CLI locally
npm run cli:build
npm run cli:link

Now you can test the CLI with bearnie command.

How to Contribute

Reporting Bugs

  1. Check if the issue already exists in Issues
  2. Provide a clear, descriptive title
  3. Describe the exact steps to reproduce the problem
  4. Explain what you expected to happen vs. what actually happened
  5. Include screenshots or error messages if applicable

Example:

Title: Button component doesn't apply variant styles

Steps to reproduce:
1. Add button component: npx bearnie add button
2. Use <Button variant="destructive">Delete</Button>
3. The button appears with default styling, not destructive

Expected: Destructive red styling should be applied
Actual: Button has default blue styling

Submitting Features

  1. Open an issue with the tag enhancement
  2. Describe the feature and why it would be useful
  3. Provide examples if applicable
  4. Wait for feedback before starting work

Adding New Components

Step 1: Create the Component

Create a new directory in src/components/ui/:

mkdir src/components/ui/my-component
touch src/components/ui/my-component/MyComponent.astro

Component template:

---
import { cn } from "@/utils/cn";
import type { HTMLAttributes } from "astro/types";

export interface Props extends HTMLAttributes<"div"> {
  variant?: "default" | "secondary";
}

const {
  variant = "default",
  class: className,
  ...props
} = Astro.props;

const baseStyles = "inline-flex items-center gap-2";

const variantStyles = {
  default: "bg-primary text-white",
  secondary: "bg-secondary text-gray-900",
};

const classes = cn(baseStyles, variantStyles[variant], className);
---

<div class={classes} {...props}>
  <slot />
</div>

Step 2: Add Component Metadata

Edit scripts/generate-registry.ts and add to COMPONENT_META:

"my-component": {
  description: "Brief description of the component",
  category: "form", // or layout, navigation, feedback, disclosure, display
  registryDependencies: [], // Other components this depends on
},

Step 3: Generate Registry

npm run generate-registry

Step 4: Create Documentation

Create src/content/components/my-component.mdx:

---
title: MyComponent
description: A brief description of what this component does.
---

import MyComponent from "@/components/ui/my-component/MyComponent.astro";

## Overview

Describe what the component does and when to use it.

## Basic Usage

<MyComponent>Content here</MyComponent>

## Variants

<MyComponent variant="secondary">Content here</MyComponent>

## Props

- `variant` - The style variant (default, secondary)
- `class` - Additional CSS classes

Step 5: Test with CLI

# Test adding the component
BEARNIE_REGISTRY_PATH=./public/registry bearnie add my-component

Step 6: Commit and Create PR

git add .
git commit -m "feat: add MyComponent component"
git push origin feature/my-component

Improving Documentation

  1. Navigate to the relevant .mdx file in src/content/components/
  2. Make improvements to examples, descriptions, or add new sections
  3. Test locally with npm run dev
  4. Create a pull request with your changes

Fixing Bugs

  1. Create a branch for the fix: git checkout -b fix/bug-description
  2. Make your changes
  3. Test thoroughly
  4. Create a pull request with:
    • Clear description of the bug
    • Link to related issue
    • Steps to verify the fix

Pull Request Process

  1. Update your branch with the latest main:
git fetch origin
git rebase origin/main
  1. Run tests and checks:
npm run build
npm run cli:build
  1. Commit with meaningful messages:
git commit -m "feat: add support for X"
git commit -m "fix: resolve issue with Y"
git commit -m "docs: improve Z documentation"

Use conventional commits:

  • feat: - A new feature
  • fix: - A bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting, semicolons, etc.)
  • refactor: - Code refactoring
  • test: - Adding tests
  • chore: - Build process, dependencies
  1. Create the pull request:
    • Provide a clear title and description
    • Link to any related issues
    • Request a review from maintainers

Coding Guidelines

TypeScript

  • Use TypeScript for all new code
  • Avoid any types when possible
  • Provide proper interfaces for props

Astro Components

  • Use .astro extension
  • Export a Props interface
  • Use semantic HTML
  • Support the class prop for customization

Styling

  • Use Tailwind CSS for styling
  • Support color theming via CSS variables
  • Ensure accessibility with proper contrast ratios

Accessibility

  • Use semantic HTML elements
  • Include proper ARIA labels when needed
  • Test with keyboard navigation
  • Ensure sufficient color contrast

Project Structure

src/
├── components/
│   ├── ui/          # Component implementations
│   ├── blog/        # Blog components
│   ├── global/      # Layout components
│   └── landing/     # Homepage components
├── content/
│   └── components/  # MDX documentation
├── pages/
├── styles/
└── utils/

Questions or Need Help?

License

By contributing to Bearnie, you agree that your contributions will be licensed under its MIT License.

Thank you for making Bearnie better! 🙏