mirror of
https://github.com/penpot/penpot.git
synced 2026-04-25 11:18:36 +00:00
📚 Improve CONTRIBUTING.md file
This commit is contained in:
Andrey Antukh
parent
cc03f3f884
commit
edfa437ce7
294
CONTRIBUTING.md
294
CONTRIBUTING.md
@ -1,211 +1,195 @@
|
|||||||
# Contributing Guide #
|
# Contributing Guide
|
||||||
|
|
||||||
Thank you for your interest in contributing to Penpot. This is a
|
Thank you for your interest in contributing to Penpot. This guide covers
|
||||||
generic guide that details how to contribute to the project in a way that
|
how to propose changes, submit fixes, and follow project conventions.
|
||||||
is efficient for everyone. If you are looking for specific documentation on
|
|
||||||
different parts of the platform, please refer to the `docs/` directory,
|
|
||||||
or the rendered version at the [Help Center](https://help.penpot.app/).
|
|
||||||
|
|
||||||
## Reporting Bugs ##
|
For architecture details, module-specific guidelines, and AI-agent
|
||||||
|
instructions, see [AGENTS.md](AGENTS.md). For final user technical
|
||||||
|
documentation, see the `docs/` directory or the rendered [Help
|
||||||
|
Center](https://help.penpot.app/).
|
||||||
|
|
||||||
We are using [GitHub Issues](https://github.com/penpot/penpot/issues)
|
## Table of Contents
|
||||||
for our public bugs. We keep a close eye on them and try to make it
|
|
||||||
clear when we have an internal fix in progress. Before filing a new
|
|
||||||
task, try to make sure your problem doesn't already exist.
|
|
||||||
|
|
||||||
If you found a bug, please report it, as far as possible, with:
|
- [Prerequisites](#prerequisites)
|
||||||
|
- [Reporting Bugs](#reporting-bugs)
|
||||||
|
- [Pull Requests](#pull-requests)
|
||||||
|
- [Commit Guidelines](#commit-guidelines)
|
||||||
|
- [Formatting and Linting](#formatting-and-linting)
|
||||||
|
- [Changelog](#changelog)
|
||||||
|
- [Code of Conduct](#code-of-conduct)
|
||||||
|
- [Developer's Certificate of Origin (DCO)](#developers-certificate-of-origin-dco)
|
||||||
|
|
||||||
- a detailed explanation of steps to reproduce the error
|
## Prerequisites
|
||||||
- the browser and browser version used
|
|
||||||
- a dev tools console exception stack trace (if available)
|
|
||||||
|
|
||||||
If you found a bug which you think is better to discuss in private (for
|
- **Language**: Penpot is written primarily in Clojure (backend), ClojureScript
|
||||||
example, security bugs), consider first sending an email to
|
(frontend/exporter), and Rust (render-wasm). Familiarity with the Clojure
|
||||||
`support@penpot.app`.
|
ecosystem is expected for most contributions.
|
||||||
|
- **Issue tracker**: We use [GitHub Issues](https://github.com/penpot/penpot/issues)
|
||||||
|
for public bugs and [Taiga](https://tree.taiga.io/project/penpot/) for
|
||||||
|
internal project management. Changelog entries reference both.
|
||||||
|
|
||||||
**We don't have a formal bug bounty program for security reports; this
|
## Reporting Bugs
|
||||||
is an open source application, and your contribution will be recognized
|
|
||||||
in the changelog.**
|
|
||||||
|
|
||||||
|
Report bugs via [GitHub Issues](https://github.com/penpot/penpot/issues).
|
||||||
|
Before filing, search existing issues to avoid duplicates.
|
||||||
|
|
||||||
## Pull Requests ##
|
Include the following when possible:
|
||||||
|
|
||||||
If you want to propose a change or bug fix via a pull request (PR),
|
1. Steps to reproduce the error.
|
||||||
you should first carefully read the section **Developer's Certificate of
|
2. Browser and browser version used.
|
||||||
Origin**. You must also format your code and commits according to the
|
3. DevTools console exception stack trace (if available).
|
||||||
instructions below.
|
|
||||||
|
|
||||||
If you intend to fix a bug, it's fine to submit a pull request right
|
For security bugs or issues better discussed in private, email
|
||||||
away, but we still recommend filing an issue detailing what you're
|
`support@penpot.app` or report them on [Github Security
|
||||||
fixing. This is helpful in case we don't accept that specific fix but
|
Advisories](https://github.com/penpot/penpot/security/advisories)
|
||||||
want to keep track of the issue.
|
|
||||||
|
|
||||||
If you want to implement or start working on a new feature, please
|
> **Note:** We do not have a formal bug bounty program. Security
|
||||||
open a **question*- / **discussion*- issue for it. No PR
|
> contributions are recognized in the changelog.
|
||||||
will be accepted without a prior discussion about the changes,
|
|
||||||
whether it is a new feature, an already planned one, or a quick win.
|
|
||||||
|
|
||||||
If it is your first PR, you can learn how to proceed from
|
## Pull Requests
|
||||||
[this free video
|
|
||||||
series](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
|
|
||||||
|
|
||||||
We use the `easy fix` tag to indicate issues that are appropriate for beginners.
|
### Workflow
|
||||||
|
|
||||||
## Commit Guidelines ##
|
1. **Read the DCO** — see [Developer's Certificate of Origin](#developers-certificate-of-origin-dco)
|
||||||
|
below. All code patches must include a `Signed-off-by` line.
|
||||||
|
2. **Discuss before building** — open a question/discussion issue before
|
||||||
|
starting work on a new feature or significant change. 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](#formatting-and-linting) before submitting.
|
||||||
|
|
||||||
We have very precise rules on how our git commit messages must be formatted.
|
### Good first issues
|
||||||
|
|
||||||
The commit message format is:
|
We use the `easy fix` label to mark issues appropriate for newcomers.
|
||||||
|
|
||||||
|
## Commit Guidelines
|
||||||
|
|
||||||
|
Commit messages must follow this format:
|
||||||
|
|
||||||
```
|
```
|
||||||
<type> <subject>
|
:emoji: <subject>
|
||||||
|
|
||||||
[body]
|
[body]
|
||||||
|
|
||||||
[footer]
|
[footer]
|
||||||
```
|
```
|
||||||
|
|
||||||
Where type is:
|
### Commit types
|
||||||
|
|
||||||
- :bug: `:bug:` a commit that fixes a bug
|
| Emoji | Description |
|
||||||
- :sparkles: `:sparkles:` a commit that adds an improvement
|
|-------|-------------|
|
||||||
- :tada: `:tada:` a commit with a new feature
|
| :bug: | Bug fix |
|
||||||
- :recycle: `:recycle:` a commit that introduces a refactor
|
| :sparkles: | Improvement or enhancement |
|
||||||
- :lipstick: `:lipstick:` a commit with cosmetic changes
|
| :tada: | New feature |
|
||||||
- :ambulance: `:ambulance:` a commit that fixes a critical bug
|
| :recycle: | Refactor |
|
||||||
- :books: `:books:` a commit that improves or adds documentation
|
| :lipstick: | Cosmetic changes |
|
||||||
- :construction: `:construction:` a WIP commit
|
| :ambulance: | Critical bug fix |
|
||||||
- :boom: `:boom:` a commit with breaking changes
|
| :books: | Documentation |
|
||||||
- :wrench: `:wrench:` a commit for config updates
|
| :construction: | Work in progress |
|
||||||
- :zap: `:zap:` a commit with performance improvements
|
| :boom: | Breaking change |
|
||||||
- :whale: `:whale:` a commit for Docker-related stuff
|
| :wrench: | Configuration update |
|
||||||
- :paperclip: `:paperclip:` a commit with other non-relevant changes
|
| :zap: | Performance improvement |
|
||||||
- :arrow_up: `:arrow_up:` a commit with dependency updates
|
| :whale: | Docker-related change |
|
||||||
- :arrow_down: `:arrow_down:` a commit with dependency downgrades
|
| :paperclip: | Other non-relevant changes |
|
||||||
- :fire: `:fire:` a commit that removes files or code
|
| :arrow_up: | Dependency update |
|
||||||
- :globe_with_meridians: `:globe_with_meridians:` a commit that adds or updates
|
| :arrow_down: | Dependency downgrade |
|
||||||
translations
|
| :fire: | Removal of code or files |
|
||||||
|
| :globe_with_meridians: | Add or update translations |
|
||||||
|
| :rocket: | Epic or highlight |
|
||||||
|
|
||||||
More info:
|
### Rules
|
||||||
|
|
||||||
- https://gist.github.com/parmentf/035de27d6ed1dce0b36a
|
- Use the **imperative mood** in the subject (e.g. "Fix", not "Fixed").
|
||||||
- https://gist.github.com/rxaviers/7360908
|
- Capitalize the first letter of the subject.
|
||||||
|
- Do not end the subject with a period.
|
||||||
|
- Keep the subject to **65 characters** or fewer.
|
||||||
|
- Separate the subject from the body with a **blank line**.
|
||||||
|
|
||||||
Each commit should have:
|
### Examples
|
||||||
|
|
||||||
- A concise subject using the imperative mood.
|
```
|
||||||
- The subject should capitalize the first letter, omit the period
|
:bug: Fix unexpected error on launching modal
|
||||||
at the end, and be no longer than 65 characters.
|
:sparkles: Enable new modal for profile
|
||||||
- A blank line between the subject line and the body.
|
:zap: Improve performance of dashboard navigation
|
||||||
- An entry in the CHANGES.md file if applicable, referencing the
|
:ambulance: Fix critical bug on user registration process
|
||||||
GitHub or Taiga issue/user story using these same rules.
|
:tada: Add new approach for user registration
|
||||||
|
```
|
||||||
|
|
||||||
Examples of good commit messages:
|
## Formatting and Linting
|
||||||
|
|
||||||
- `:bug: Fix unexpected error on launching modal`
|
We use [cljfmt](https://github.com/weavejester/cljfmt) for formatting and
|
||||||
- `:bug: Set proper error message on generic error`
|
[clj-kondo](https://github.com/clj-kondo/clj-kondo) for linting.
|
||||||
- `:sparkles: Enable new modal for profile`
|
|
||||||
- `:zap: Improve performance of dashboard navigation`
|
|
||||||
- `:wrench: Update default backend configuration`
|
|
||||||
- `:books: Add more documentation for authentication process`
|
|
||||||
- `:ambulance: Fix critical bug on user registration process`
|
|
||||||
- `:tada: Add new approach for user registration`
|
|
||||||
|
|
||||||
## Formatting and Linting ##
|
|
||||||
|
|
||||||
You will want to make sure your code is formatted and linted before submitting
|
|
||||||
a PR. We use [cljfmt](https://github.com/weavejester/cljfmt) and
|
|
||||||
[clj-kondo](https://github.com/clj-kondo/clj-kondo) for this. After installing
|
|
||||||
them on your system, you can run them with:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Check formatting
|
# Check formatting (does not modify files)
|
||||||
|
./scripts/check-fmt
|
||||||
|
|
||||||
|
# Fix formatting (modifies files in place)
|
||||||
./scripts/fmt
|
./scripts/fmt
|
||||||
|
|
||||||
# Lint
|
# Lint
|
||||||
./scripts/lint
|
./scripts/lint
|
||||||
```
|
```
|
||||||
|
|
||||||
Ideally, you should run these commands as git pre-commit hooks. A convenient way
|
Ideally, run these as git pre-commit hooks.
|
||||||
of defining them is to use [Husky](https://typicode.github.io/husky/#/).
|
[Husky](https://typicode.github.io/husky/#/) is a convenient option for
|
||||||
|
setting this up.
|
||||||
|
|
||||||
## Code of Conduct ##
|
## Changelog
|
||||||
|
|
||||||
As contributors and maintainers of this project, we pledge to respect
|
When your change is user-facing or otherwise notable, add an entry to
|
||||||
all people who contribute through reporting issues, posting feature
|
[CHANGES.md](CHANGES.md) following the same commit-type conventions. Reference
|
||||||
requests, updating documentation, submitting pull requests or patches,
|
the relevant GitHub issue or Taiga user story.
|
||||||
and other activities.
|
|
||||||
|
|
||||||
We are committed to making participation in this project a
|
## Code of Conduct
|
||||||
harassment-free experience for everyone, regardless of level of
|
|
||||||
experience, gender, gender identity and expression, sexual
|
|
||||||
orientation, disability, personal appearance, body size, race,
|
|
||||||
ethnicity, age, or religion.
|
|
||||||
|
|
||||||
Examples of unacceptable behavior by participants include the use of
|
This project follows the [Contributor Covenant](https://www.contributor-covenant.org/).
|
||||||
sexual language or imagery, derogatory comments or personal attacks,
|
The full Code of Conduct is available at
|
||||||
trolling, public or private harassment, insults, or other
|
[help.penpot.app/contributing-guide/coc](https://help.penpot.app/contributing-guide/coc/)
|
||||||
unprofessional conduct.
|
and in the repository's [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
||||||
|
|
||||||
Project maintainers have the right and responsibility to remove, edit,
|
To report unacceptable behavior, open an issue or contact a project maintainer
|
||||||
or reject comments, commits, code, wiki edits, issues, and other
|
directly.
|
||||||
contributions that are not aligned with this Code of Conduct. Project
|
|
||||||
maintainers who do not follow the Code of Conduct may be removed from
|
|
||||||
the project team.
|
|
||||||
|
|
||||||
This Code of Conduct applies both within project spaces and in public
|
|
||||||
spaces when an individual is representing the project or its
|
|
||||||
community.
|
|
||||||
|
|
||||||
Instances of abusive, harassing, or otherwise unacceptable behavior
|
|
||||||
may be reported by opening an issue or contacting one or more of the
|
|
||||||
project maintainers.
|
|
||||||
|
|
||||||
This Code of Conduct is adapted from the Contributor Covenant, version
|
|
||||||
1.1.0, available from [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/)
|
|
||||||
|
|
||||||
## Developer's Certificate of Origin (DCO)
|
## Developer's Certificate of Origin (DCO)
|
||||||
|
|
||||||
By submitting code you agree to and can certify the following:
|
By submitting code you agree to and can certify the following:
|
||||||
|
|
||||||
Developer's Certificate of Origin 1.1
|
> **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.
|
||||||
|
|
||||||
By making a contribution to this project, I certify that:
|
### Signed-off-by
|
||||||
|
|
||||||
(a) The contribution was created in whole or in part by me and I
|
All code patches (**documentation is excluded**) must contain a sign-off line
|
||||||
have the right to submit it under the open source license
|
at the end of the commit body. Add it automatically with `git commit -s`.
|
||||||
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.
|
|
||||||
|
|
||||||
Then, all your code patches (**documentation is excluded**) should
|
|
||||||
contain a sign-off at the end of the patch/commit description body. It
|
|
||||||
can be automatically added by adding the `-s` parameter to `git commit`.
|
|
||||||
|
|
||||||
This is an example of what the line should look like:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Signed-off-by: Andrey Antukh <niwi@niwi.nz>
|
Signed-off-by: Your Real Name <your.email@example.com>
|
||||||
```
|
```
|
||||||
|
|
||||||
Please, use your real name (sorry, no pseudonyms or anonymous
|
- Use your **real name** — pseudonyms and anonymous contributions are not
|
||||||
contributions are allowed).
|
allowed.
|
||||||
|
- The `Signed-off-by` line is **mandatory** and must match the commit author.
|
||||||
The commit Signed-off-by is mandatory and should match the commit author.
|
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user