Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
305 lines (233 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

305 lines (233 loc) · 10.3 KB

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

  • 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 [email protected] 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 before starting work on a new feature or significant change. For planned features on the roadmap, reference the corresponding Taiga story. Do not expect your contribution to be accepted if you submit it without prior discussion — this applies to new features, planned features, and quick wins alike.
  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

  • We are a small team and maintainers juggle reviews alongside other tasks. Please do not expect your code to be reviewed instantly.
  • Reviews are handled in dedicated blocks of time, usually in the order PRs arrive. It may take a few days to get a first review, especially when urgent tasks come up.
  • 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 good first issue 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

For frontend SCSS, we use stylelint for linting and Prettier for formatting:

cd frontend

# Lint SCSS
pnpm run lint:scss (does not modify files)

# Fix SCSS formatting (modifies files in place)
pnpm run fmt:scss

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 <[email protected]>
  • Use your real name — pseudonyms and anonymous contributions are not allowed.
  • The Signed-off-by line is mandatory and must match the commit author.