# How to Contribute Code or Documentation to Different-AI/OpenWork: A Complete Guide

> Learn how to contribute code or documentation to the different-ai/openwork repository. Follow our guide to fork, branch, and submit your pull request effectively.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Contributing to the different-ai/openwork repository requires forking the repo, creating a descriptive branch, and opening a pull request against the `dev` branch after following the project's Code of Conduct and documentation standards.**

The OpenWork project actively welcomes contributions from developers and technical writers. Whether you're fixing a bug, adding a feature, or improving documentation, the repository follows a standardized open-source workflow defined in its governance files. This guide covers both code and documentation contributions with exact commands and file paths from the source code.

## Prerequisites: Understanding the Repository Structure

Before contributing, familiarize yourself with the key entry points and policies that govern the project.

- **Main entry point**: The [[`README.md`](https://github.com/different-ai/openwork/blob/main/README.md)](https://github.com/different-ai/openwork/blob/dev/README.md) contains project overview, installation instructions, and architecture basics.
- **Community standards**: The [[`CODE_OF_CONDUCT.md`](https://github.com/different-ai/openwork/blob/main/CODE_OF_CONDUCT.md)](https://github.com/different-ai/openwork/blob/dev/CODE_OF_CONDUCT.md) defines expected behavior; you must acknowledge this in any pull request.
- **Support guidelines**: The [[`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md)](https://github.com/different-ai/openwork/blob/dev/SUPPORT.md) explains how to report issues and request help.

OpenWork uses **pnpm** for package management and targets the **`dev`** branch for all contributions.

## How to Contribute Documentation

Documentation contributions follow a lightweight markdown-based workflow. All user-facing docs live in the [`docs/`](https://github.com/different-ai/openwork/tree/dev/docs) directory and deploy automatically to [openworklabs.com/docs](https://openworklabs.com/docs) after merge.

### Step 1: Fork and Clone the Repository

Create your personal copy of the repository and set up local development:

```bash

# Click Fork on GitHub first, then:

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

# Verify you're on the default branch

git checkout dev

```

### Step 2: Create a Descriptive Branch

Use the `docs/` prefix for documentation changes to make the purpose immediately clear:

```bash
git checkout -b docs/<topic-description>

```

Example branch names:
- `docs/add-cli-quickstart`
- `docs/fix-desktop-app-typo`
- `docs/update-marketplace-architecture`

### Step 3: Add or Edit Markdown Files

All documentation uses **GitHub-flavored markdown** (`*.md` files). Existing examples include:
- [`docs/desktop-app-policies.md`](https://github.com/different-ai/openwork/blob/main/docs/desktop-app-policies.md)
- [`docs/extensions-manifest-foundation.md`](https://github.com/different-ai/openwork/blob/main/docs/extensions-manifest-foundation.md)
- [`docs/marketplace-capabilities-architecture.md`](https://github.com/different-ai/openwork/blob/main/docs/marketplace-capabilities-architecture.md)

**To add a new document:**

```bash
cat <<EOF > docs/cli-quickstart.md

# OpenWork CLI Quick-Start

This guide shows how to install and run OpenWork from the command line.

[Install instructions](https://github.com/different-ai/openwork/blob/dev/README.md#install-with-your-ai-agent)
EOF

```

**Style requirements:**
- Use logical heading hierarchy (`#` for title, `##` for sections)
- Include optional front-matter for descriptions
- Use markdown links, never raw URLs
- Link to source files using exact paths: `[OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts)`

### Step 4: Validate and Commit

Optional but recommended: run the test suite to catch syntax errors:

```bash
pnpm dev    # Start local dev server

pnpm test   # Run full test suite

```

Write a **conventional commit** message:

```bash
git add docs/cli-quickstart.md
git commit -m "docs: add CLI quick-start guide"

```

### Step 5: Open a Pull Request

Push your branch and create a PR against the `dev` branch:

```bash
git push origin docs/cli-quickstart

```

**Required PR description elements:**
- Brief summary of changes
- Issue references (e.g., `Closes #123`)
- Confirmation of Code of Conduct compliance

Respond promptly to reviewer feedback with additional commits.

## How to Contribute Code

Code contributions follow the identical branch-and-PR workflow with additional quality gates.

### Branch Naming Conventions

| Prefix | Use Case |
|--------|----------|
| `feat/` | New features or capabilities |
| `fix/` | Bug fixes |
| `refactor/` | Code restructuring without behavior change |
| `test/` | Test additions or improvements |

### Key Source File Locations

When contributing code, you may need to reference or modify these canonical paths:

- **[`packages/types/src/openwork-provider.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/openwork-provider.ts)** — Core provider interface definitions
- **[`CODE_OF_CONDUCT.md`](https://github.com/different-ai/openwork/blob/main/CODE_OF_CONDUCT.md)** — Must acknowledge in PRs
- **[`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md)** — Reference for issue reporting standards

### Development Commands

```bash

# Install dependencies

pnpm install

# Start development environment

pnpm dev

# Run test suite before submitting

pnpm test

```

## Contribution Checklist for All PRs

Before submitting any contribution to different-ai/openwork, verify:

- [ ] Branch targets `dev`, not `main`
- [ ] Branch name follows `docs/`, `feat/`, `fix/`, or `refactor/` convention
- [ ] Commit messages use conventional format (`type: description`)
- [ ] Code of Conduct acknowledgment included in PR description
- [ ] Related issues linked with `Closes #XXX` syntax
- [ ] Tests pass (`pnpm test`)
- [ ] Documentation updated for behavioral changes

## Summary

- **Fork and clone** the repository, then create prefixed branches targeting `dev`
- **Documentation** lives in `docs/` as markdown files with internal links to source code
- **Code changes** follow identical PR workflow with `pnpm test` validation required
- **Commit format** uses conventional prefixes: `docs:`, `feat:`, `fix:`, `refactor:`
- **Governance compliance** requires acknowledging the Code of Conduct in every PR

## Frequently Asked Questions

### What branch should I target for contributions to openwork?

Target the **`dev`** branch exclusively. The `main` branch represents stable releases; all active development and contribution review happens on `dev`. Your PR will fail automated checks if opened against the wrong branch.

### Do I need to run tests for documentation-only changes?

Running `pnpm test` is **optional** for pure documentation edits, but recommended. Documentation still renders through the build system, and the test suite catches markdown syntax errors and broken internal links that would fail in CI.

### How do I link to source files from documentation?

Use absolute GitHub URLs pointing to the `dev` branch with this pattern:

```markdown
[ComponentName.ts](https://github.com/different-ai/openwork/blob/dev/path/to/file.ts)

```

For example: `[OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts)`.

### Where do I find examples of existing documentation?

Browse the [`docs/`](https://github.com/different-ai/openwork/tree/dev/docs) directory. Key reference files include [`desktop-app-policies.md`](https://github.com/different-ai/openwork/blob/main/desktop-app-policies.md) for policy-style docs and [`extensions-manifest-foundation.md`](https://github.com/different-ai/openwork/blob/main/extensions-manifest-foundation.md) for technical specification documents.