Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (70 loc) · 2.26 KB

CONTRIBUTING.md

File metadata and controls

102 lines (70 loc) · 2.26 KB
Raw

Contributing to HeadlessX

Thanks for contributing to HeadlessX.

Before You Start

Local Development

  1. Install dependencies:
pnpm install
  1. Create your environment files:
cp .env.example .env

If you are using Docker for infrastructure:

cp infra/docker/.env.example infra/docker/.env
  1. Prepare local services and runtime dependencies as needed:
pnpm db:push
pnpm camoufox:fetch
  1. Start the workspace:
pnpm dev

Important:

  • pnpm dev starts the app processes, not PostgreSQL or Redis
  • queue-backed features require Redis and the worker
  • YouTube features now work in the full Docker stack through the bundled yt-engine service, or locally through pnpm yt-engine:dev

Project Areas

  • apps/api - Express API, worker, queue flows, MCP
  • apps/web - Next.js dashboard
  • apps/yt-engine - Python YouTube engine
  • apps/go-html-to-md-service - Go HTML-to-Markdown sidecar
  • docs - setup, API, and project guides

Contribution Workflow

  1. Fork the repository
  2. Create a focused branch
  3. Make your changes
  4. Run the relevant checks
  5. Open a pull request with a clear summary

Recommended Checks

Run the checks relevant to your changes before opening a pull request:

pnpm build
pnpm lint

Add any extra app-specific verification that applies to your change.

Pull Requests

  • Keep changes focused and reviewable
  • Update docs when behavior, setup, routes, or configuration change
  • Include screenshots for UI changes when useful
  • Mention infrastructure requirements if your change depends on Redis, PostgreSQL, Docker, or external services

Commit Messages

  • Use imperative mood
  • Keep the first line concise
  • Prefer conventional, scoped messages when possible

Examples:

  • feat(api): add remote MCP endpoint
  • fix(web): align scraper run button styles
  • docs: refresh setup and API guides

Additional Guides