Contributing Guide - Web Stories for WordPress

Welcome Contributors!

We’d love to accept your patches and contributions to this project. There are just a few guidelines you need to follow.

Before contributing, make sure you’ve completed the Getting Started setup and have a local environment running.

Prerequisites

Before you can contribute, you need:

Development Environment

Set up your local development environment following the Getting Started guide.

Sign the CLA

All contributions must be accompanied by a Contributor License Agreement (CLA).

Understand the Codebase

Review the Architecture to understand the project structure.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

Sign the CLA

Head over to Google’s CLA site to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once. If you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.

Getting Started with Contributions

1. Fork and Clone the Repository

# Fork the repository on GitHub, then clone your fork
git clone [email protected]:YOUR_USERNAME/web-stories-wp.git
cd web-stories-wp

# Add upstream remote
git remote add upstream [email protected]:googleforcreators/web-stories-wp.git

2. Create a Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a new branch for your changes
git checkout -b feature/your-feature-name

3. Make Your Changes

composer install
npm install

4. Test Your Changes

Before submitting, ensure all tests pass:

npm run test:js

5. Commit Your Changes

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add feature: description of your changes"

The project uses lint-staged with husky to automatically lint and format code before commits.

6. Push and Create Pull Request

# Push your branch
git push origin feature/your-feature-name

Then create a pull request on GitHub from your branch to googleforcreators/web-stories-wp:main.

Code Review Process

All submissions, including submissions by project members, require review.

Submit Pull Request

Create a PR with a clear description of the changes and why they’re needed.

Automated Checks

Wait for automated tests and linters to pass. Fix any issues that arise.

Code Review

Maintainers will review your code. Be responsive to feedback and make requested changes.

Approval and Merge

Once approved, a maintainer will merge your PR.

We use GitHub pull requests for code review. Consult GitHub Help for more information on using pull requests.

Coding Standards

JavaScript/TypeScript

The project uses:

ESLint for linting JavaScript/TypeScript
Prettier for code formatting
WordPress coding standards via @wordpress/eslint-plugin

Run linters:

npm run lint:js
npm run lint:js:fix  # Auto-fix issues

Format code:

npm run format:js

PHP

The project follows WordPress PHP coding standards:

PHP_CodeSniffer for linting
PHPStan for static analysis
PHPMD for mess detection

Run linters:

npm run lint:php
npm run lint:php:fix     # Auto-fix issues
npm run lint:phpstan     # Static analysis
npm run lint:phpmd       # Mess detection

Format code:

npm run format:php

CSS

The project uses Stylelint for CSS and styled-components:

npm run lint:css
npm run format:css      # Auto-fix CSS
npm run format:css-in-js # Auto-fix styled-components

Other Files

Markdown:

npm run lint:md
npm run format:md

YAML/XML:

npm run format:yml
npm run format:xml

Automated Formatting

The project uses lint-staged to automatically format files on commit:

{
  "*.js": ["eslint --fix", "stylelint --fix"],
  "*.php": ["npm run lint:php:fix"],
  "*.css": ["stylelint --fix"],
  "*.md": ["eslint --fix", "markdownlint -f"],
  "*.json": ["prettier --write"]
}

See package.json:297-314 for the complete configuration.

Writing Tests

When to Write Tests

Always include tests when:

Adding new features
Fixing bugs
Modifying existing functionality

Test Types

Unit Tests

Test individual functions and components in isolation

Integration Tests

Test how components work together in the browser

E2E Tests

Test complete user workflows from start to finish

See the Testing Guide for detailed information on writing and running tests.

Commit Message Guidelines

Write clear, descriptive commit messages: Good commit messages:

Add support for video captions in story editor

Fix race condition in media upload

Update dependencies to latest versions

Avoid:

fixed bug
update
WIP

Pull Request Guidelines

PR Title

Use a clear, descriptive title:

Add video captions support
Fix media upload race condition
Update React to v18

PR Description

Include:

What - What changes are being made
Why - Why these changes are needed
How - How the changes solve the problem
Testing - How to test the changes
Screenshots - Visual changes (if applicable)

Template:

## Summary
Brief description of changes

## Motivation
Why are these changes needed?

## Implementation
How do the changes work?

## Testing Instructions
1. Step-by-step testing guide
2. Expected behavior

## Screenshots
(if applicable)

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Linters pass
- [ ] All tests pass

Community Guidelines

This project follows Google’s Open Source Community Guidelines. Be respectful and inclusive:

Use welcoming and inclusive language
Be respectful of differing viewpoints
Accept constructive criticism gracefully
Focus on what’s best for the community

Development Scripts Reference

Build Scripts

npm run build        # Production build (PHP + JS)
npm run build:js     # JavaScript production build
npm run dev          # Development build with watch
npm run serve        # Dev server with Fast Refresh

Testing Scripts

npm run test         # Run all tests
npm run test:js      # JavaScript unit tests
npm run test:php     # PHP unit tests
npm run test:karma   # Integration tests
npm run test:e2e     # End-to-end tests

Linting Scripts

npm run lint         # Run all linters
npm run lint:js      # Lint JavaScript
npm run lint:php     # Lint PHP
npm run lint:css     # Lint CSS
npm run lint:md      # Lint Markdown

Formatting Scripts

npm run format       # Format all files
npm run format:js    # Format JavaScript
npm run format:php   # Format PHP
npm run format:css   # Format CSS
npm run format:md    # Format Markdown

Environment Scripts

npm run env:start      # Start Docker environment
npm run env:stop       # Stop Docker environment
npm run env:reset-site # Reset WordPress database

See package.json:198-295 for all available scripts.

Getting Help

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and discuss ideas

Getting Started

Development setup guide

Architecture

Understand the codebase

Thank You!

Thank you for contributing to Web Stories for WordPress! Your contributions help make the web more visual and engaging for everyone.

Get Started

Story Editor

Features

Publishing

Developer Guide

​Welcome Contributors!

​Prerequisites

​Contributor License Agreement

Sign the CLA

​Getting Started with Contributions

​1. Fork and Clone the Repository

​2. Create a Branch

​3. Make Your Changes

​4. Test Your Changes

​5. Commit Your Changes

​6. Push and Create Pull Request

​Code Review Process

​Coding Standards

​JavaScript/TypeScript

​PHP

​CSS

​Other Files

​Automated Formatting

​Writing Tests

​When to Write Tests

​Test Types

Unit Tests

Integration Tests

E2E Tests

​Commit Message Guidelines

​Pull Request Guidelines

​PR Title

​PR Description

​Community Guidelines

​Development Scripts Reference

​Build Scripts

​Testing Scripts

​Linting Scripts

​Formatting Scripts

​Environment Scripts

​Getting Help

GitHub Issues

GitHub Discussions

Getting Started

Architecture

​Thank You!

Build docs developers (and LLMs) love

Welcome Contributors!

Prerequisites

Contributor License Agreement

Getting Started with Contributions

1. Fork and Clone the Repository

2. Create a Branch

3. Make Your Changes

4. Test Your Changes

5. Commit Your Changes

6. Push and Create Pull Request

Code Review Process

Coding Standards

JavaScript/TypeScript

PHP

CSS

Other Files

Automated Formatting

Writing Tests

When to Write Tests

Test Types

Commit Message Guidelines

Pull Request Guidelines

PR Title

PR Description

Community Guidelines

Development Scripts Reference

Build Scripts

Testing Scripts

Linting Scripts

Formatting Scripts

Environment Scripts

Getting Help

Thank You!