penpot/CONTRIBUTING.md

Contributing Guide

Thank you for your interest in contributing to Penpot. This guide covers how to propose changes, submit fixes, and follow project conventions.

For architecture details, module-specific guidelines, and AI-agent instructions, see AGENTS.md. For final user technical documentation, see the docs/ directory or the rendered Help Center.

Table of Contents

• Prerequisites
• Reporting Bugs
• Pull Requests
  • Workflow
  • Title format
  • Description
  • Branch naming
  • Review process
  • What we won't accept
  • Good first issues
• Commit Guidelines
  • Commit types
  • Rules
  • Examples
• Formatting and Linting
• Changelog
• Code of Conduct
• Developer's Certificate of Origin (DCO)

Prerequisites

• Language: Penpot is written primarily in Clojure (backend), ClojureScript (frontend/exporter), and Rust (render-wasm). Familiarity with the Clojure ecosystem is expected for most contributions.
• Issue tracker: We use GitHub Issues for public bugs and Taiga for internal project management. Changelog entries reference both.

Reporting Bugs

Report bugs via GitHub Issues. Before filing, search existing issues to avoid duplicates.

Include the following when possible:

1. Steps to reproduce the error.
2. Browser and browser version used.
3. DevTools console exception stack trace (if available).

For security bugs or issues better discussed in private, email support@penpot.app or report them on Github Security Advisories

Note: We do not have a formal bug bounty program. Security contributions are recognized in the changelog.

Pull Requests

Workflow

1. Read the DCO — see Developer's Certificate of Origin below. All code patches must include a Signed-off-by line.
2. Discuss before building — open a GitHub Issue or start a GitHub Discussion before starting work on a new feature or significant change. For planned features on the roadmap, reference the corresponding Taiga story. No PR will be accepted without prior discussion, whether it is a new feature, a planned one, or a quick win.
3. Bug fixes — you may submit a PR directly, but we still recommend filing an issue first so we can track it independently of your fix.
4. Format and lint — run the checks described in Formatting and Linting before submitting.

Title format

Pull request titles must follow the same convention as commit subjects:

:emoji: <subject>

• Use the imperative mood (e.g. "Fix", not "Fixed").
• Capitalize the first letter of the subject.
• Do not end the subject with a period.
• Keep the subject to 70 characters or fewer.
• Use one of the commit type emojis listed below.

When a PR contains multiple unrelated commits, choose the emoji that best represents the dominant change.

Examples:

:bug: Fix unexpected error on launching modal
:sparkles: Enable new modal for profile
:zap: Improve performance of dashboard navigation

Note: When a PR is squash-merged, the PR title becomes the commit message on the main branch. Getting the title right matters.

Description

Every pull request should include a description that helps reviewers understand the change quickly:

1. What and why — describe the change and its motivation.
2. Link related issues — use Closes #1234 or reference a Taiga story (e.g. Taiga #5678).
3. Screenshots or recordings — required for any UI-visible change.
4. Testing notes — how did you verify the change? Any edge cases?
5. Breaking changes — call out anything that affects existing users or requires migration steps.

Branch naming

Use a descriptive branch name that reflects the type and scope of the change:

<type>/<short-description>

Types: fix, feat, refactor, docs, chore, perf.

Optionally include the issue number:

fix/9122-email-blacklisting
feat/export-webp
refactor/layout-sizing

Review process

• Maintainers review PRs when time permits. Please be patient.
• Address review feedback by pushing new commits — do not force-push during review, as it breaks comment threads.
• PRs require at least one approval before merge.
• We use squash-merge by default. The PR title becomes the final commit message, so follow the title format above.

What we won't accept

To save time on both sides, please avoid submitting PRs that:

• Introduce new dependencies without prior discussion.
• Change the build system or CI configuration without maintainer approval.
• Mix unrelated changes in a single PR — keep PRs focused on one concern.
• Skip the discussion step for non-bug-fix changes.

Good first issues

We use the easy fix label to mark issues appropriate for newcomers.

Commit Guidelines

Commit messages must follow this format:

:emoji: <subject>

[body]

[footer]

Commit types

Emoji	Description
🐛	Bug fix
✨	Improvement or enhancement
🎉	New feature
♻️	Refactor
💄	Cosmetic changes
🚑	Critical bug fix
📚	Documentation
🚧	Work in progress
💥	Breaking change
🔧	Configuration update
⚡	Performance improvement
🐳	Docker-related change
📎	Other non-relevant changes
⬆️	Dependency update
⬇️	Dependency downgrade
🔥	Removal of code or files
🌐	Add or update translations
🚀	Epic or highlight

Rules

• Use the imperative mood in the subject (e.g. "Fix", not "Fixed")
• Capitalize the first letter of the subject
• Add clear and concise description on the body
• Do not end the subject with a period
• Keep the subject to 70 characters or fewer
• Separate the subject from the body with a blank line

Examples

:bug: Fix unexpected error on launching modal
:sparkles: Enable new modal for profile
:zap: Improve performance of dashboard navigation
:ambulance: Fix critical bug on user registration process
:tada: Add new approach for user registration

Formatting and Linting

We use cljfmt for formatting and clj-kondo for linting.

# Check formatting (does not modify files)
./scripts/check-fmt

# Fix formatting (modifies files in place)
./scripts/fmt

# Lint
./scripts/lint

Ideally, run these as git pre-commit hooks. Husky is a convenient option for setting this up.

Changelog

When your change is user-facing or otherwise notable, add an entry to CHANGES.md following the same commit-type conventions. Reference the relevant GitHub issue or Taiga user story.

Code of Conduct

This project follows the Contributor Covenant. The full Code of Conduct is available at help.penpot.app/contributing-guide/coc and in the repository's CODE_OF_CONDUCT.md.

To report unacceptable behavior, open an issue or contact a project maintainer directly.

Developer's Certificate of Origin (DCO)

By submitting code you agree to and can certify the following:

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Signed-off-by

All code patches (documentation is excluded) must contain a sign-off line at the end of the commit body. Add it automatically with git commit -s.

Signed-off-by: Your Real Name <your.email@example.com>

• Use your real name — pseudonyms and anonymous contributions are not allowed.
• The Signed-off-by line is mandatory and must match the commit author.