mirror of
https://github.com/zizmorcore/zizmor.git
synced 2025-12-23 08:47:33 +00:00
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# Contributing to `zizmor`
|
|
|
|
Thank you for your interest in contributing to `zizmor`!
|
|
|
|
This is intended to be a "high-level" guide with some suggestions
|
|
for ways to contribute. Once you've picked a contribution idea,
|
|
please see our [development docs]
|
|
for concrete guidance on specific development tasks and style prescriptions.
|
|
|
|
## How to contribute
|
|
|
|
Here's a short list of steps you can follow to contribute:
|
|
|
|
1. *Figure out what you want to contribute.* See the
|
|
[contribution ideas](#contribution-ideas) section below if you're looking
|
|
for ideas!
|
|
2. *File or reply to an issue, if appropriate.* Some contributions require
|
|
new issues (like new bugs), while others involve an existing issue
|
|
(like known documentation defects). Others don't require an issue at all,
|
|
like small typo fixes. In general, if you aren't sure, *error on the side
|
|
of making or replying to an issue* — it helps maintain shared
|
|
development context.
|
|
3. *Hack away.* Once you know what you're working on, refer to our
|
|
[development docs] for help with specific development tasks. And don't be
|
|
afraid to ask for help!
|
|
|
|
## Contribution ideas
|
|
|
|
Here are some ways that you can contribute to `zizmor`. These aren't the only
|
|
ways; they're just for inspiration.
|
|
|
|
### Good first issues
|
|
|
|
We use the ["good first issue"] label to track issues that we think are
|
|
(somewhat) easy and/or straightforward, making them good choices for an
|
|
early contribution.
|
|
|
|
To work on one of these, **please leave a comment** on its issue before opening
|
|
a pull request to make sure nobody else duplicates your work!
|
|
|
|
["good first issue"]: https://github.com/zizmorcore/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
|
|
|
|
### Writing documentation
|
|
|
|
One of the best ways to help us with `zizmor` is to help us improve our
|
|
documentation!
|
|
|
|
Here are some things we could use help with:
|
|
|
|
* Improving our [CLI usage recipes](https://docs.zizmor.sh/usage/).
|
|
* Improving the detail in our
|
|
[audit documentation pages](https://docs.zizmor.sh/audits/).
|
|
* Improving our internal (Rust API) documentation, especially in conjunction
|
|
with more unit tests.
|
|
|
|
More generally, see [issues labeled with `documentation`] for a potential
|
|
list of documentation efforts to contribute on.
|
|
|
|
[issues labeled with `documentation`]: https://github.com/zizmorcore/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation
|
|
|
|
### Writing unit tests
|
|
|
|
We can always use more unit tests! Pick a part of the Rust codebase and
|
|
start testing.
|
|
|
|
Keep the cardinal rule of unit testing in mind: a unit test must test
|
|
**a single unit** of behavior. If it tests more than one unit, then
|
|
consider making it an integration test instead.
|
|
|
|
### Reducing false positives/negatives in audits
|
|
|
|
Static analysis is inherently imprecise, and `zizmor` is no exception.
|
|
|
|
We track imprecision bugs with the ["false positive"] and ["false negative"]
|
|
labels. These can sometimes be tricky to address, so we recommend
|
|
(but don't require) leaving an explanatory comment on the issue before
|
|
beginning a pull request.
|
|
|
|
["false positive"]: https://github.com/zizmorcore/zizmor/issues?q=is%3Aopen+label%3Afalse-positive
|
|
|
|
["false negative"]: https://github.com/zizmorcore/zizmor/issues?q=is%3Aopen+label%3Afalse-negative
|
|
|
|
[development docs]: https://docs.zizmor.sh/development/
|
|
|