Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
324 lines (216 loc) · 8.95 KB

CONTRIBUTING.md

File metadata and controls

324 lines (216 loc) · 8.95 KB
Raw

Contributing to Monochrome

Thank you for your interest in contributing to Monochrome! This guide will help you get started with development, understand our codebase, and follow our contribution workflow.

Table of Contents

Development Setup

Prerequisites

Quick Start

  1. Fork the Repository

  2. clone the repository:

    git clone https://github.com/YOUR_USERNAME/monochrome.git
cd monochrome

  3. Install dependencies:

    bun install
# or
npm install

  4. Start the development server:

    bun run dev
# or
npm run dev

  5. Open your browser: Navigate to http://localhost:5173/

Code Quality

We maintain high code quality standards. All code must pass our linting checks before being merged.

Our Tool Stack

Tool Purpose Files
ESLint JavaScript linting *.js
Stylelint CSS linting *.css
HTMLHint HTML validation *.html
Prettier Code formatting All

Available Commands

# Check everything (runs all linters)
bun run lint

# Auto-format all code
bun run format

# Fix JavaScript issues automatically
bun run lint:js -- --fix

# Fix CSS issues automatically
bun run lint:css -- --fix

# Check HTML
bun run lint:html

# Check specific file types
bun run lint:js
bun run lint:css

⚠️ Important: A GitHub Action automatically runs bun run lint on every push and pull request. Please ensure all checks pass before committing.

Key Directories

  • /js - All JavaScript source code

    • Keep modules focused and single-purpose
    • Use ES6+ features
    • Keep the code easy to work with/maintain

  • /public - Static assets copied directly to build

    • Images should be optimized before adding
    • Keep file sizes reasonable
    • Use appropriate formats (PNG where possible)

Before You Contribute

To ensure a smooth contribution process and avoid wasted effort, please adhere to the following guidelines before starting any major work.

Consult on Major Features

If you're looking into contributing a big feature, please speak with us before starting work. You might be implementing something we are already working on, or a feature that could create more issues long-term. You can reach us via a GitHub Issue or on our Discord.

Open Draft PRs Early

Whether you've spoken with us or not, we highly recommend opening Draft Pull Requests early. This allows us to catch potential issues before you spend too much time on them. Large PRs that appear suddenly are often difficult to review, and we may close them if they conflict with internal work we haven't pushed yet.

AI as a Tool

AS A TOOL, AI is a great way to help you navigate our (admittedly messy) codebase or refactor logic. We actually encourage using it to speed up your workflow, but we have a zero-tolerance policy for Vibecoding.

Permissible (and encouraged):

  • Using AI as a tutor to help you understand a specific module or issue.
  • Using AI to help clean up your code or write clearer PR descriptions.
  • Making sure you understand every line of code you submit.
  • Mentioning in your PR if you used AI to help with a specific section.

Prohibited (AI Slop):

  • Vibecoding the entire PR (letting AI write the code without human oversight).
  • Submitting code you don't actually understand or haven't tested.
  • Ignoring edge cases because the AI didn't suggest them.

⚠️: If we can verify that a Pull Request is just unvetted AI/Vibecoded Work, it will be automatically closed without review. If you can't explain your code, it doesn't belong in Monochrome.

No Hard Feelings

If we end up closing your Pull Request, please don't feel bad about it! We really appreciate you taking the time to help out with Monochrome.

There are a lot of reasons why we might close a PR, and most of them have nothing to do with you. It might be because:

  • We’re already working on the same thing behind the scenes.
  • The feature doesn't quite fit where the project is headed right now.
  • We’re still undecided on how a certain part of the app should work.
  • It doesn't quite follow the guidelines we've set here.

In short: we don't hate you, and we aren't trying to be mean. We know how much work goes into a PR, and we're grateful you chose to spend your time on our project. Even if a PR gets closed, we'd still love to have you around the community!

Contributing Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/description-of-fix

2. Make Your Changes

  • Follow existing code style
  • Write clear, self-documenting code
  • Add comments for complex logic
  • Update documentation if needed

3. Test Your Changes

# Run all linters
bun run lint

# Test the build
bun run build

4. Commit Your Changes

Follow our commit message guidelines.

git add .
git commit -m "feat(player): add keyboard shortcut for loop toggle" # example commit message

5. Push and Create a Pull Request

git push origin feature/your-feature-name

Then open a pull request on GitHub with:

  • Clear title describing the change
  • Detailed description of what changed and why
  • Reference any related issues

Commit Message Guidelines

We use Conventional Commits for clear, structured commit messages.

Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Type Description
feat New feature
fix Bug fix
docs Documentation changes
style Code style changes (formatting, semicolons, etc.)
refactor Code refactoring without changing behavior
perf Performance improvements
test Adding or updating tests
chore Maintenance tasks (dependencies, build, etc.)

Scopes

Common scopes in our project:

  • player - Audio player functionality
  • ui - User interface components
  • api - API integration
  • library - Library management
  • playlists - Playlist functionality
  • lyrics - Lyrics display
  • downloads - Download functionality
  • auth - Authentication
  • pwa - Progressive Web App features
  • settings - Settings/preferences
  • theme - Theming system

Examples

# Feature addition
feat(playlists): add shuffle playlist button

# Bug fix
fix(metadata): resolve corrupted Hi-res metadata issue

# Refactoring
refactor(downloads): simplify cancel download logic

# Documentation
docs(README): improve installation instructions

# Maintenance
chore(deps): bump lyrics package to fix vulnerability

# Style changes
style(player): fix indentation in audio controls

Tips

  • Use the present tense ("add feature" not "added feature")
  • Use imperative mood ("move cursor to..." not "moves cursor to...")
  • Don't capitalize the first letter
  • No period at the end
  • Keep the first line under 72 characters

📋 Cheat Sheet: Conventional Commits Cheat Sheet

Deployment

Deployment is fully automated via Cloudflare Pages.

How It Works

  1. Push changes to the main branch
  2. Cloudflare automatically builds and deploys
  3. Changes are live a minute

Configuration Notes

The project uses a relative base path (./) in vite.config.js. This allows the same build artifact to work on both:

  • Cloudflare Pages (served from root)
  • GitHub Pages (served from /monochrome/)

Hash routing is used to ensure compatibility across all hosting platforms.

Manual Deployment

If you need to deploy manually:

# Build for production
bun run build

# The `dist/` folder contains the deployable files

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers and help them learn
  • Focus on constructive feedback
  • Respect different viewpoints and experiences

Thank you for contributing to Monochrome!