diff options
| -rw-r--r-- | CONTRIBUTING.md | 73 | ||||
| -rw-r--r-- | README.md | 7 |
2 files changed, 76 insertions, 4 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5848b863 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing to Typst +Thank you for considering to contribute to Typst. We want to foster a welcoming +and productive atmosphere for contributors. Therefore, we outline a few steps to +land your contribution below. + +1. Before starting significant work on a feature or refactoring, please + find/open an [issue] or start a thread in the [#contributors] channel on + Discord to discuss the design. Feel also free to ping a maintainer/team + member to get some input on your idea. Don't be shy! Typst is a complex + project with a long-term vision and it's frustrating to find out that your + idea does not align with that vision _after_ you have already implemented + something. +2. Fork the Typst repository and start with your contribution. If you, at any + point in this process, are unsure about how to do something in the Typst + codebase, reach out to a maintainer or a more experienced contributor. Also + have a look at the [`ARCHITECTURE.md`][architecture] file. It explains how + the compiler works. +3. Create a pull request (PR) in the Typst repository, outlining your + contribution, the technical rationale behind it, and, if it includes a new + feature, how users will use it. Best to link to an existing issue with this + information here. +4. When you send a PR, automated CI checks will run. Your PR can only be merged + if CI passes and will often also only get its first review round once it has + the green checkmark. You can ping a maintainer if you need guidance with + failing CI (or anything else). +5. A maintainer will review your PR. In this review, we check code quality, + bugs, and whether the contribution aligns with what was previously discussed. + If you think that a review comment misses something or is not quite right, + please challenge it! +6. If the review passes, your PR will be merged and ship in the next version of + Typst. You will appear as one of the contributors in the [changelog]. + Thank you! + +Below are some signs of a good PR: +- Implements a single, self-contained feature or bugfix that has been discussed + previously. +- Adds/changes as little code and as few interfaces as possible. Should changes + to larger-scale abstractions be necessary, these should be discussed + throughout the implementation process. +- Adds tests if appropriate (with reference images for visual tests). See the + [testing] readme for more details. +- Contains documentation comments on all new Rust types. +- Comes with brief documentation for all new Typst definitions + (elements/functions), ideally with a concise example that fits into ~5-10 + lines with <38 columns (check out existing examples for inspiration). This + part is not too critical, as we will touch up the documentation before making + a release. + +Sometimes, a contributor can become unresponsive during a review process. This +is okay! We will, however, close PRs on which we are waiting for a contributor +response after an extended period of time to avoid filling up the PR tracker +with many stale PRs. In the same way, it may take a while for us to find time to +review your PR. If there is no response after a longer while (1-2 weeks), feel +free to ping us, as we may have missed it. + +While Typst is an open-source project, it is also the product of a startup. We +always judge technical contributions to the project based on their technical +merits. However, as a company, our immediate priorities can and do change often +and sometimes without prior notice. This affects the design and decision making +process as well as the development and review velocity. Some proposals may also +have direct impact on our viability as a company, in which case we carefully +consider them from the business perspective. + +If you are unsure whether your idea is a good fit for this project, please +discuss it with us! The core question is "Does this help to make Typst the prime +technical typesetting app?". If the answer is yes, your idea is likely right for +Typst! + +[issue]: https://github.com/typst/typst/issues +[testing]: https://github.com/typst/typst/blob/main/tests/README.md +[#contributors]: https://discord.com/channels/1054443721975922748/1088371867913572452 +[architecture]: https://github.com/typst/typst/blob/main/ARCHITECTURE.md +[changelog]: https://typst.app/docs/changelog/ @@ -161,10 +161,8 @@ public beta. ## Contributing We would love to see contributions from the community. If you experience bugs, -feel free to open an issue or send a PR with a fix. For new features, we would -invite you to open an issue first so we can explore the design space together. -If you want to contribute and are wondering how everything works, also check out -the [`ARCHITECTURE.md`][architecture] file. It explains how the compiler works. +feel free to open an issue. If you would like to implement a new feature or bug +fix, please follow the steps outlined in the [contribution guide][contributing]. To build Typst yourself, first ensure that you have the [latest stable Rust][rust] installed. Then, clone this repository and build the @@ -220,4 +218,5 @@ instant preview. To achieve these goals, we follow three core design principles: [rust]: https://rustup.rs/ [releases]: https://github.com/typst/typst/releases/ [architecture]: https://github.com/typst/typst/blob/main/ARCHITECTURE.md +[contributing]: https://github.com/typst/typst/blob/main/CONTRIBUTING.md [`comemo`]: https://github.com/typst/comemo/ |