documenso/CONTRIBUTING.md

Contributing to Documenso

We are no longer accepting external pull requests.

Aside from a small group of trusted contributors we reach out to directly, we no longer merge external PRs. New pull requests will usually be closed with a request to open an issue instead. This is a security decision, not a judgement on your work. Read Why We're Pausing External Pull Requests for the full reasoning.

Documenso stays open source. You can still read, audit, run, and fork the code. The best way to contribute is through detailed issues.

How to contribute now

The most useful contribution is a detailed issue. Treat it like a spec. The more detail, the better:

• The problem you're trying to solve, and who it affects
• How you expect the feature or change to behave
• Edge cases, constraints, and anything you've already considered
• Examples, mockups, or references where they help

Before opening an issue, search existing issues and discussions for related items. If a proposal is detailed and fits where Documenso is heading, we'll pick it up and build against it.

For security vulnerabilities, do not open a public issue. Follow our Security Policy instead.

---

The sections below are for trusted contributors working with us directly, and for anyone running Documenso locally or maintaining a fork.

English only PRs and Issues

Please write all issues, pull requests, and related comments in English so maintainers and the wider contributor community can follow the discussion.

Taking issues

Before taking an issue, ensure that:

• The issue has been assigned the public label
• The issue is clearly defined and understood
• No one has been assigned to the issue
• No one has expressed intention to work on it

You can then:

1. Comment on the issue with your intention to work on it
2. Begin work on the issue

Always feel free to ask questions or seek clarification on the issue.

Developing

The development branch is main. All pull requests should be made against this branch. If you need help getting started, join us on Discord.

1. Fork this repository to your own GitHub account and then clone it to your local device.
2. Create a new branch:

• Create a new branch (include the issue id and something readable):

  git checkout -b feat/doc-999-somefeature-that-rocks
  

3. See the Developer Setup for more setup details.

Building

Note

Please ensure you can make a full production build before pushing code or creating PRs.

You can build the project with:

npm run build

AI-Assisted Development with OpenCode

We use OpenCode for AI-assisted development. OpenCode provides custom commands and skills to help maintain consistency and streamline common workflows.

OpenCode works with most major AI providers (Anthropic, OpenAI, Google, etc.) or you can use Zen for optimized coding models. Configure your preferred provider in the OpenCode settings.

Important

: All AI-generated code must be thoroughly reviewed by the contributor before submitting a PR. You are responsible for understanding and validating every line of code you submit. If we detect that contributors are simply throwing AI-generated code over the wall without proper review, they will be blocked from the repository.

Getting Started

1. Install OpenCode (see opencode.ai for other install methods):

   curl -fsSL https://opencode.ai/install | bash
   

2. Configure your AI provider (or use Zen for optimized models)
3. Run opencode in the project root

Available Commands

Use these commands in OpenCode by typing the command name:

Command	Description
/implement <spec-path>	Implement a spec from .agents/plans/ autonomously
/continue <spec-path>	Continue implementing a spec from a previous session
/interview <file-path>	Deep-dive interview to flesh out a spec or design
/document <module-path>	Generate MDX documentation for a module or feature
/commit	Create a conventional commit for staged changes
/create-plan <slug>	Create a new plan file in .agents/plans/
/create-scratch <slug>	Create a scratch file for notes in .agents/scratches/
/create-justification <slug>	Create a justification file in .agents/justifications/

Typical Workflow

1. Create a plan: Use /create-plan my-feature to draft a spec for a new feature
2. Flesh out the spec: Use /interview .agents/plans/<file>.md to refine requirements
3. Implement: Use /implement .agents/plans/<file>.md to build the feature
4. Continue if needed: Use /continue .agents/plans/<file>.md to pick up where you left off
5. Commit: Use /commit to create a conventional commit

Agent Files

The .agents/ directory stores AI-generated artifacts:

• .agents/plans/ - Feature specs and implementation plans
• .agents/scratches/ - Temporary notes and explorations
• .agents/justifications/ - Decision rationale and technical justifications

These files use a unique ID format ({word}-{word}-{word}-{slug}.md) to prevent conflicts.