# How Contribution to the Open-SEO Project Is Managed: A Complete Guide

> Discover how contributions to the open-seo project are managed. Learn about our issue-first, fork-and-branch workflow, test-driven development, and maintainer review process. Contribute effectively today.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Contributions to the open-seo project follow an issue-first, fork-and-branch workflow that emphasizes test-driven development and maintainer review before automated release note generation.**

The `every-app/open-seo` repository maintains a lightweight, community‑driven contribution process designed to lower barriers for new contributors while keeping the TypeScript codebase stable. Whether you are reporting bugs, suggesting features, or submitting code, the workflow is documented directly in the repository’s [`README.md`](https://github.com/every-app/open-seo/blob/main/README.md) and [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md) files.

## The Issue-First Contribution Model

Every contribution starts with an **issue**. The [`README.md`](https://github.com/every-app/open-seo/blob/main/README.md) explicitly directs potential contributors to “Open an issue for bugs, UX friction, or feature requests” and to “open an issue and describe what you want to build” when they are unsure where to start.

This issue-first approach ensures that:

- **Duplicate work is avoided** by checking existing issues before coding
- **Design discussions happen early** before implementation effort is spent
- **Maintainers can triage** and provide guidance on approach

If you want to implement a feature directly, the documentation still encourages opening a PR, but referencing a related issue (e.g., `Fixes #123`) significantly speeds up review.

## Fork, Branch, and Local Development Setup

Once an issue exists (or you have claimed an existing one), the standard GitHub flow applies. You will work in a **pnpm-based monorepo** that uses TypeScript, Vite, and Cloudflare Workers.

First, fork the repository and create a short-lived feature branch:

```bash

# Clone your fork

git clone https://github.com/<your-username>/open-seo.git
cd open-seo

# Create a descriptive branch

git checkout -b fix-search-bug

```

The project structure places source code under `src/`, frontend assets under `web/`, and database schemas under `drizzle/`. Typical changes involve editing files in these directories, with build configuration managed by [`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts) and `wrangler.jsonc`.

Install dependencies using the required package manager:

```bash
pnpm install

```

## Testing Requirements Before Submitting

The open-seo project requires **automated testing** before any pull request can be merged. The repository uses **Vitest** for unit tests and **Playwright** for end-to-end testing.

Verify your changes locally by running:

```bash

# Run unit tests

pnpm test

# Run end-to-end tests (optional but recommended)

pnpm playwright

```

These commands are defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) and rely on [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) and [`playwright.config.ts`](https://github.com/every-app/open-seo/blob/main/playwright.config.ts) for configuration. The `e2e/` directory contains the Playwright tests that run against the full application, ensuring that changes do not break existing functionality across the Cloudflare Worker deployment target.

## Pull Request and Review Process

After committing your changes, push the branch to your fork and open a Pull Request against the `main` branch:

```bash
git push origin fix-search-bug

```

In the PR description, reference the related issue (e.g., `Fixes #123 – resolves the search-timeout bug`). The README explicitly encourages this pattern “if you want to implement a feature directly.”

**Maintainer review** follows the guidelines in [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md). This document outlines the release-notes generation process and emphasizes high-quality PRs. Reviewers verify that:

- Tests pass in CI
- Code follows the existing TypeScript patterns
- Documentation is updated where necessary

## Release and Post-Merge Workflow

Once a PR is approved and merged, the release process is handled by maintainers using automated tooling. The key component is `scripts/release-notes.mjs`, a CLI helper that creates changelog entries from git commits.

Maintainers generate release notes by running:

```bash

# Generate notes since the last semver tag

pnpm release:notes

# Or with explicit range

pnpm release:notes -- --from v0.0.7 --to HEAD

```

The changelog is stored under `release-notes/` and a GitHub draft release is created. According to [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md), this “Release notes workflow” ensures consistent documentation of changes. After release, the new version is published via Docker images or Cloudflare Worker builds as described in the README and `docs/SELF_HOSTING_*.md` files.

## Summary

- **Issue-first workflow**: Open an issue in the GitHub tracker before coding to discuss bugs or features.
- **Fork-and-branch**: Create short-lived branches from your fork using standard GitHub flow.
- **Test-driven**: Run `pnpm test` (Vitest) and `pnpm playwright` (E2E) locally before submitting.
- **PR-oriented**: Submit against `main` with issue references; follow maintainer review in [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md).
- **Automated releases**: Merged PRs are documented via `scripts/release-notes.mjs` and released through the maintainer pipeline.

## Frequently Asked Questions

### Do I need to open an issue before submitting a pull request?

While the [`README.md`](https://github.com/every-app/open-seo/blob/main/README.md) states you can open a PR directly “if you want to implement a feature,” the recommended path is to open an issue first. This allows maintainers to validate the approach and prevents duplicate work. If you open a PR without a corresponding issue, you should still reference any related discussion or clearly describe the problem being solved.

### What testing is required before my PR can be merged?

You must run the **Vitest** unit test suite using `pnpm test` and verify that all existing tests pass. Additionally, the repository maintains **Playwright** end-to-end tests in the `e2e/` directory, which you can run with `pnpm playwright`. Maintainers will verify these tests pass in CI before merging, as documented in the repository’s testing workflow files.

### How are release notes generated for the open-seo project?

Release notes are generated automatically using `scripts/release-notes.mjs`, which is invoked via `pnpm release:notes`. This script aggregates commits since the last semantic version tag and formats them into a markdown file stored under `release-notes/`. Maintainers then use this file to create GitHub draft releases, ensuring every contribution is properly documented in the changelog.

### Who can review and merge contributions?

Reviews are conducted by project **maintainers**, whose workflow is defined in [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md). While community members can provide feedback on PRs, only maintainers can perform the final merge and trigger the release workflow. The document specifies that maintainers focus on code quality, test coverage, and adherence to the monorepo structure before approving changes.