Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
391 lines (289 loc) · 9.07 KB

CONTRIBUTING.md

File metadata and controls

391 lines (289 loc) · 9.07 KB

Contributing to macwidget-studio 🎨

First off, thank you for considering contributing to macwidget-studio! It's people like you that make this project better for everyone.

PRs Welcome Contributors

📋 Table of Contents

📜 Code of Conduct

This project and everyone participating in it is governed by our commitment to creating a welcoming and inclusive environment. By participating, you are expected to:

  • ✅ Be respectful and inclusive
  • ✅ Welcome newcomers and help them get started
  • ✅ Accept constructive criticism gracefully
  • ✅ Focus on what is best for the community
  • ❌ Don't use inappropriate language or imagery
  • ❌ Don't engage in trolling or harassment

🤝 How Can I Contribute?

Reporting Bugs 🐛

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

  • Clear title: Brief description of the issue
  • Steps to reproduce: Detailed steps to recreate the bug
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Screenshots: If applicable
  • Environment:
    • macOS version
    • Node.js version
    • npm version
    • Browser (if applicable)

Bug Report Template:

**Bug Description**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - macOS: [e.g. 13.0]
 - Node: [e.g. 18.0.0]
 - npm: [e.g. 8.0.0]

Suggesting Features 💡

We love new ideas! When suggesting features:

  • Check existing suggestions first
  • Explain the problem your feature would solve
  • Describe the solution you'd like to see
  • Consider alternatives you've thought about
  • Add mockups/examples if possible

Improving Documentation 📚

Documentation improvements are always welcome:

  • Fix typos or clarify instructions
  • Add examples or tutorials
  • Improve code comments
  • Translate documentation

🚀 Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/macwidget-studio.git
cd macwidget-studio
git checkout dev

2. Set Up Development Environment

# Install dependencies
npm install

# Start development server
npm run dev

3. Create a Branch

# Create a descriptive branch name
git checkout -b feature/amazing-new-widget
# or
git checkout -b fix/button-alignment-issue

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Adding tests
  • chore/ - Maintenance tasks

🔄 Development Workflow

Local Development

  1. Make your changes in your feature branch
  2. Test thoroughly - ensure nothing breaks
  3. Run linting - npm run lint
  4. Build the project - npm run build to ensure it compiles
  5. Test the build - npm run preview to test production build

Code Quality Checklist

Before submitting:

  • Code follows the project's TypeScript style
  • All TypeScript types are properly defined
  • No console.log statements left in code
  • Code is properly formatted
  • No ESLint errors or warnings
  • Changes work in development mode (npm run dev)
  • Changes work in production build (npm run build && npm run preview)

📝 Coding Guidelines

TypeScript Best Practices

// ✅ DO: Use proper types
interface WidgetProps {
  title: string;
  isVisible: boolean;
  onClose: () => void;
}

const Widget: React.FC<WidgetProps> = ({ title, isVisible, onClose }) => {
  // component code
};

// ❌ DON'T: Use 'any' type
const Widget = (props: any) => {
  // component code
};

React Component Structure

// ✅ DO: Organize components clearly
import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';

interface MyComponentProps {
  initialValue: number;
}

export const MyComponent: React.FC<MyComponentProps> = ({ initialValue }) => {
  // 1. Hooks
  const [count, setCount] = useState(initialValue);
  
  // 2. Effects
  useEffect(() => {
    // side effects
  }, []);
  
  // 3. Handlers
  const handleClick = () => {
    setCount(count + 1);
  };
  
  // 4. Render
  return (
    <div>
      <p>Count: {count}</p>
      <Button onClick={handleClick}>Increment</Button>
    </div>
  );
};

Styling with Tailwind

// ✅ DO: Use Tailwind utility classes
<div className="flex items-center gap-4 p-4 rounded-lg bg-gray-100">
  <h1 className="text-2xl font-bold">Title</h1>
</div>

// ❌ DON'T: Use inline styles
<div style={{ display: 'flex', padding: '16px' }}>
  <h1 style={{ fontSize: '24px' }}>Title</h1>
</div>

File Naming Conventions

  • Components: PascalCase.tsx (e.g., WidgetCard.tsx)
  • Utilities: camelCase.ts (e.g., formatDate.ts)
  • Types: PascalCase.ts (e.g., WidgetTypes.ts)
  • Hooks: use + PascalCase.ts (e.g., useWidgetData.ts)

💬 Commit Message Guidelines

We follow the Conventional Commits specification:

Format

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

<body>

<footer>

Types

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

Examples

# Feature
git commit -m "feat(widgets): add weather widget component"

# Bug fix
git commit -m "fix(layout): correct responsive breakpoint for mobile"

# Documentation
git commit -m "docs(readme): update installation instructions"

# Refactoring
git commit -m "refactor(utils): simplify date formatting function"

Good Commit Messages

# ✅ Good
feat(widgets): add customizable color picker
fix(ui): resolve button alignment on Safari
docs(contributing): add code review guidelines

# ❌ Bad
update stuff
fix bug
changes

🔍 Pull Request Process

Before Submitting

  1. Update your branch with the latest dev branch:

    git checkout dev
git pull origin dev
git checkout your-feature-branch
git rebase dev

  2. Ensure all checks pass:

    • Code builds successfully
    • No linting errors
    • All tests pass (if applicable)
    • Documentation is updated

Creating the Pull Request

  1. Push your branch: git push origin feature/your-feature-name
  2. Open a Pull Request on GitHub
  3. Fill out the PR template completely
  4. Link related issues using keywords (e.g., "Closes #123")

PR Title Format

<type>: <description>

# Examples:
feat: Add weather widget with live updates
fix: Correct widget positioning on multi-monitor setup
docs: Improve installation guide with screenshots

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing
Describe how you tested these changes

## Screenshots (if applicable)
Add screenshots here

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-reviewed the code
- [ ] Commented complex code sections
- [ ] Updated documentation
- [ ] No new warnings introduced
- [ ] Tested on macOS

Review Process

  1. Automated checks will run automatically
  2. Maintainer review - we'll review within 2-3 days
  3. Address feedback - make requested changes
  4. Approval - once approved, we'll merge!

👥 Community

Getting Help

  • GitHub Discussions: Ask questions and share ideas
  • Issues: Report bugs or request features
  • Pull Requests: Share your code contributions

Recognition

Contributors will be:

  • Listed in our README
  • Mentioned in release notes
  • Added to the contributors graph

🎓 Learning Resources

New to the tech stack? Here are some helpful resources:

📞 Questions?

Don't hesitate to ask questions! You can:

  • Open a discussion on GitHub
  • Comment on relevant issues
  • Reach out to maintainers

Thank You! 🙏

Your contributions make macwidget-studio better for everyone. We appreciate your time and effort!

Happy Coding