CONTRIBUTING.md: Initial version

This commit is contained in:
Krystine Sherwin 2025-01-17 15:08:35 +13:00
parent eac2294cab
commit eaebf6ab02
No known key found for this signature in database
1 changed files with 71 additions and 0 deletions

71
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,71 @@
# Introduction
Thanks for thinking about contributing to the Yosys project. If this is your
first time contributing to an open source project, please take a look at the
following guide:
https://opensource.guide/how-to-contribute/#orienting-yourself-to-a-new-project.
# Using the issue tracker
The [issue tracker](https://github.com/YosysHQ/yosys/issues) is used for
tracking bugs or other problems with Yosys or its documentation. It is also the
place to go for requesting new features.
When [creating a new issue](https://github.com/YosysHQ/yosys/issues/new/choose),
we have a few templates available. Please make use of these! It will make it
much easier for someone to respond and help.
### Bug reports
Before you submit an issue, please have a search of the existing issues in case
one already exists. Making sure that you have a minimal, complete and
verifiable example (MVCE) is a great way to quickly check an existing issue
against a new one. Stack overflow has a guide on [how to create an
MVCE](https://stackoverflow.com/help/minimal-reproducible-example). The
[`bugpoint`
command](https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/bugpoint.html)
in Yosys can be helpful for this process.
# Using pull requests
If you are working on something to add to Yosys, or fix something that isn't
working quite right, make a PR! An open PR, even as a draft, tells everyone
that you're working on it and they don't have to. It can also be a useful way
to solicit feedback on in-progress changes. See below to find the best way to
[ask us questions](#asking-questions).
In general, all changes to the code are done as a
[PR](https://github.com/YosysHQ/yosys/pulls), with [Continuous Integration
(CI)](https://github.com/YosysHQ/yosys/actions) tools that automatically run the
full suite of tests compiling and running Yosys. Please make use of this! If
you're adding a feature: add a test! Not only does it verify that your feature
is working as expected, but it can also be a handy way for people to see how the
feature is used. If you're fixing a bug: add a test! If you can, do this
first; it's okay if the test starts off failing - you already know there is a
bug. CI also helps to make sure that your changes still work under a range of
compilers, settings, and targets.
### Labels
We use [labels](https://github.com/YosysHQ/yosys/labels) to help categorise
issues and PRs. If a label seems relevant to your work, please do add it; this
also includes the labels beggining with 'status-'. The 'merge-' labels are used
by maintainers for tracking and communicating which PRs are ready and pending
merge; please do not use these labels if you are not a maintainer.
# Asking questions
If you have a question about how to use Yosys, please ask on our [discussions
page](https://github.com/YosysHQ/yosys/discussions) or in our [community
slack](https://join.slack.com/t/yosyshq/shared_invite/zt-1aopkns2q-EiQ97BeQDt_pwvE41sGSuA).
The slack is also a great place to ask questions about developing or
contributing to Yosys.
We have open dev 'jour fixe' (JF) meetings where developers from YosysHQ and the
community come together to discuss open issues and PRs. This is also a good
place to talk to us about how to implement larger PRs. Please join the
community slack if you would like to join the next meeting, the link is
available in the description of the #devel-discuss channel.