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](https://documenso.com/blog/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](https://github.com/documenso/documenso/issues) and [discussions](https://github.com/documenso/documenso/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](./SECURITY.md) 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 <code>main</code>. All pull requests should be made against this branch. If you need help getting started, [join us on Discord](https://documen.so/discord).

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
   own GitHub account and then
   [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
2. Create a new branch:

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

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

3. See the [Developer Setup](https://github.com/documenso/documenso/blob/main/README.md#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:

```bash
npm run build
```

## AI-Assisted Development with OpenCode

We use [OpenCode](https://opencode.ai) 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](https://opencode.ai/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](https://opencode.ai) for other install methods):
   ```bash
   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.