Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (132 loc) · 4.75 KB

CONTRIBUTING.md

File metadata and controls

188 lines (132 loc) · 4.75 KB

Contributing to Setlist Player

Thank you for your interest in contributing to Setlist Player! This document provides guidelines and instructions for contributing to the project.

Getting Started

Prerequisites

  • Node.js 18+ and npm
  • Composer
  • WordPress development environment

Development Setup

# Clone the repository
git clone https://github.com/ironprogrammer/setlist-player.git
cd setlist-player

# Install dependencies
npm install
composer install

# Start development build (watches for changes)
npm start

# Build for production
npm run build

Project Structure

setlist-player/
├── build/              # Compiled assets (generated by build process)
├── includes/           # PHP classes (API wrapper, REST controller, settings, block registration)
├── src/                # Source files (block.json, React components, SCSS, render.php)
├── tests/              # PHPUnit and Jest tests
└── setlist-player.php  # Main plugin file

Development Workflow

Making Changes

  1. Fork the repository
  2. Create a feature branch from trunk: 
    git checkout -b feature/amazing-feature
  3. Make your changes
  4. Write or update tests as needed
  5. Run linting and tests (see below)
  6. Commit your changes
  7. Push to your fork
  8. Open a Pull Request against trunk

Code Standards

This project follows WordPress coding standards:

Linting

Run linting checks before committing:

# Lint everything
npm run lint

# Lint specific file types
npm run lint:js      # JavaScript
npm run lint:css     # CSS/SCSS
npm run lint:php     # PHP

Formatting

Auto-format code to match standards:

# Format everything
npm run format

# Format specific file types
npm run format:php   # PHP only

Testing

Test Environment Setup

Set up the test environment (first time only):

npm run test:setup

Running Tests

# Run all tests (PHP + JavaScript)
npm test

# Run PHP tests only
npm run test:php

# Run JavaScript tests only
npm run test:js

# Run PHP tests after rebuilding
npm run test:php:build

# Run a specific PHP test function
npm run test:php -- --filter=test_validate_api_key

# Run a specific JavaScript test file
npm run test:js -- utils.test.js

Writing Tests

  • PHP Tests: Add PHPUnit tests in tests/test-*.php
  • JavaScript Tests: Add Jest tests in tests/js/*.test.js

Commit Messages

Follow these guidelines for commit messages:

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Focus on what was implemented, not how you got there
  • First line should be a brief summary (50 chars or less)
  • Add detailed explanation in the body if needed

Example

Add playlist export functionality

- Add export button to block toolbar
- Implement JSON export format
- Add import validation

Pull Request Process

  1. Update Documentation: Ensure README.md and other docs reflect your changes
  2. Add Tests: Include tests that cover your changes
  3. Run All Checks: Ensure linting and tests pass
  4. Update Changelog: Add an entry to the changelog section in readme.txt
  5. Describe Your Changes: Provide a clear description of what and why in the PR
  6. Link Issues: Reference any related issues in your PR description

PR Checklist

  • Code follows WordPress coding standards
  • All tests pass (npm test)
  • Linting passes (npm run lint)
  • Documentation updated
  • Commit messages follow guidelines
  • No merge conflicts with trunk

Creating a Distribution Package

To create a WordPress.org-ready distribution package:

# Build production assets
npm run build

# Generate distribution zip
npm run plugin-zip

This creates setlist-player.zip containing only the files needed for distribution (no source files, tests, or dev dependencies).

Questions or Problems?

Code of Conduct

Be respectful, constructive, and professional in all interactions. We're all here to make this plugin better!