Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (132 loc) · 4.34 KB

CONTRIBUTING.md

File metadata and controls

185 lines (132 loc) · 4.34 KB

Contributing to Browser Music

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

Code of Conduct

Be respectful and inclusive. We want this to be a welcoming community for everyone.

How Can I Contribute?

Reporting Bugs

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

  • Clear title and description
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Screenshots if applicable
  • Browser and OS information
  • Console errors if any

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

  • Clear title and description of the feature
  • Use case - why would this be useful?
  • Mockups or examples if applicable

Pull Requests

  1. Fork the repository
  2. Create a new branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Test your changes thoroughly
  5. Commit with clear messages (git commit -m 'Add amazing feature')
  6. Push to your fork (git push origin feature/amazing-feature)
  7. Open a Pull Request

Development Setup

Prerequisites

  • Node.js (v16 or higher)
  • npm or yarn
  • Modern web browser (Chrome, Firefox, Safari, or Edge)

Setup Steps

# Clone your fork
git clone https://github.com/YOUR_USERNAME/BrowserMusic.git
cd BrowserMusic

# Install dependencies
npm install

# Start dev server
npm run dev

Project Structure

src/
├── audio/              # Audio engines for instruments
├── components/         # React components
│   ├── Header/        # App header
│   ├── TR909/         # TR-909 components
│   └── TB303/         # TB-303 components
├── App.tsx            # Main app component
└── main.tsx           # Entry point

Coding Guidelines

TypeScript

  • Use TypeScript for all new code
  • Define proper types and interfaces
  • Avoid any type when possible
  • Use meaningful variable and function names

React

  • Use functional components with hooks
  • Keep components small and focused
  • Extract reusable logic into custom hooks
  • Use proper prop types

Audio/Tone.js

  • Clean up audio nodes in useEffect cleanup
  • Avoid creating audio nodes in render
  • Use Tone.Transport for timing
  • Handle audio context state properly

CSS

  • Use CSS modules or scoped styles
  • Follow BEM naming convention when appropriate
  • Ensure responsive design (mobile, tablet, desktop)
  • Test on different screen sizes

Git Commits

  • Use clear, descriptive commit messages
  • Start with a verb: "Add", "Fix", "Update", "Remove"
  • Keep commits focused on single changes
  • Reference issues when applicable

Testing

Before submitting a PR, test your changes:

  • Works on desktop browsers (Chrome, Firefox, Safari)
  • Works on mobile devices (iOS, Android)
  • No console errors
  • Audio works correctly
  • Responsive design looks good
  • Performance is acceptable

Audio Development Tips

Working with Tone.js

  1. Always start audio context properly

    await Tone.start()

  2. Clean up audio nodes

    useEffect(() => {
  const synth = new Tone.Synth()
  return () => synth.dispose()
}, [])

  3. Use Transport for sequencing

    Tone.Transport.scheduleRepeat((time) => {
  // Your code
}, '16n')

Testing Audio

  • Test with headphones and speakers
  • Check for clicking/popping sounds
  • Verify timing is accurate
  • Test at different BPM values
  • Check CPU usage

Adding New Features

When adding new instruments or features:

  1. Create audio engine in src/audio/
  2. Create UI components in src/components/
  3. Add to main app if needed
  4. Update documentation
  5. Add examples to README

Documentation

  • Update README.md for new features
  • Add JSDoc comments for complex functions
  • Include usage examples
  • Update CHANGELOG.md

Questions?

Feel free to open an issue for:

  • Questions about the codebase
  • Discussion about features
  • Help with development setup

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You!

Your contributions make Browser Music better for everyone. Thank you for taking the time to contribute!