mirror of https://github.com/YosysHQ/yosys.git
Shuffle around information about bug reports and contributions
This commit is contained in:
Emil J. Tywoniak
parent
58c7dc7cc2
commit
436a247d60
|
|
@ -6,6 +6,8 @@ body:
|
|||
attributes:
|
||||
value: >
|
||||
|
||||
Learn more [here](https://yosyshq.readthedocs.io/projects/yosys/en/latest/yosys_internals/extending_yosys/contributing.html#reporting-bugs) about how to report bugs. We fix well-reported bugs the fastest.
|
||||
|
||||
If you have a general question, please ask it on the [Discourse forum](https://yosyshq.discourse.group/).
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,41 +1,44 @@
|
|||
# Introduction
|
||||
# Contributing to Yosys
|
||||
|
||||
Thanks for thinking about contributing to the Yosys project. If this is your
|
||||
Thanks for considering helping out. If this is your
|
||||
first time contributing to an open source project, please take a look at the
|
||||
following guide:
|
||||
following guide about the basics:
|
||||
https://opensource.guide/how-to-contribute/#orienting-yourself-to-a-new-project.
|
||||
|
||||
Information about the Yosys coding style is available on our Read the Docs:
|
||||
https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html.
|
||||
## Asking questions
|
||||
|
||||
# Using the issue tracker
|
||||
If you have a question about how to use Yosys, please ask on our [Discourse forum](https://yosyshq.discourse.group/).
|
||||
The Discourse is also a great place to ask questions about developing or
|
||||
contributing to Yosys.
|
||||
|
||||
We have open [dev 'jour fixe' (JF) meetings](https://docs.google.com/document/d/1SapA6QAsJcsgwsdKJDgnGR2mr97pJjV4eeXg_TVJhRU/edit?usp=sharing) 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.
|
||||
|
||||
## 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 check out the [how-to guide for
|
||||
`bugpoint`](https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html).
|
||||
This guide will take you through the process of using the [`bugpoint`
|
||||
command](https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html) in Yosys to
|
||||
produce a [minimal, complete and verifiable
|
||||
example](https://stackoverflow.com/help/minimal-reproducible-example) (MVCE).
|
||||
Providing an MVCE with your bug report drastically increases the likelihood that
|
||||
someone will be able to help resolve your issue.
|
||||
Learn more [here](https://yosyshq.readthedocs.io/projects/yosys/en/latest/yosys_internals/extending_yosys/contributing.html#reporting-bugs) about how to report bugs. We fix well-reported bugs the fastest.
|
||||
|
||||
## Contributing code
|
||||
|
||||
# Using pull requests
|
||||
### 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](https://github.com/YosysHQ/yosys/pulls)! 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
|
||||
working quite right,
|
||||
make a [pull request (PR)](https://github.com/YosysHQ/yosys/pulls).
|
||||
|
||||
If you're adding complex functionality, or modifying core parts of yosys,
|
||||
we highly recommend discussing your motivation and approach
|
||||
ahead of time on the [Discourse forum](https://yosyshq.discourse.group/).
|
||||
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, with [Continuous
|
||||
|
|
@ -53,18 +56,11 @@ work under a range of compilers, settings, and targets.
|
|||
|
||||
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
|
||||
also includes the labels beginning 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
|
||||
### Coding style
|
||||
|
||||
If you have a question about how to use Yosys, please ask on our [Discourse forum](https://yosyshq.discourse.group/) or in our [discussions
|
||||
page](https://github.com/YosysHQ/yosys/discussions).
|
||||
The Discourse is also a great place to ask questions about developing or
|
||||
contributing to Yosys.
|
||||
|
||||
We have open [dev 'jour fixe' (JF) meetings](https://docs.google.com/document/d/1SapA6QAsJcsgwsdKJDgnGR2mr97pJjV4eeXg_TVJhRU/edit?usp=sharing) 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.
|
||||
Learn more [here](https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html).
|
||||
|
|
|
|||
|
|
@ -1,14 +1,6 @@
|
|||
Contributing to Yosys
|
||||
=====================
|
||||
|
||||
.. note::
|
||||
|
||||
For information on making a pull request on github, refer to our
|
||||
|CONTRIBUTING|_ file.
|
||||
|
||||
.. |CONTRIBUTING| replace:: :file:`CONTRIBUTING.md`
|
||||
.. _CONTRIBUTING: https://github.com/YosysHQ/yosys/blob/main/CONTRIBUTING.md
|
||||
|
||||
Coding Style
|
||||
------------
|
||||
|
||||
|
|
@ -47,11 +39,13 @@ Use range-based for loops whenever applicable.
|
|||
Reporting bugs
|
||||
--------------
|
||||
|
||||
- use the `bug report template`_
|
||||
A good bug report includes the following information:
|
||||
|
||||
.. _bug report template: https://github.com/YosysHQ/yosys/issues/new?template=bug_report.yml
|
||||
|
||||
- short title briefly describing the issue, e.g.
|
||||
Title
|
||||
~~~~~
|
||||
|
||||
briefly describe the issue, for example:
|
||||
|
||||
techmap of wide mux with undefined inputs raises error during synth_xilinx
|
||||
|
||||
|
|
@ -64,10 +58,18 @@ Reporting bugs
|
|||
Reproduction Steps
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ideally a code-block (starting and ending with triple backquotes) containing
|
||||
the minimized design (Verilog or RTLIL), followed by a code-block containing
|
||||
the minimized yosys script OR a command line call to yosys with
|
||||
code-formatting (starting and ending with single backquotes)
|
||||
The reproduction steps should be a minimal, complete and verifiable
|
||||
example `MVCE`_.
|
||||
Providing an MVCE with your bug report drastically increases the likelihood that
|
||||
someone will be able to help resolve your issue.
|
||||
One way to minimize a design is to use the `bugpoint_` command.
|
||||
You can learn more in the `how-to guide for bugpoint_`.
|
||||
|
||||
The reproduction steps are ideally a code-block (starting and ending with
|
||||
triple backquotes) containing
|
||||
the minimized design (Verilog or RTLIL), followed by a code-block containing
|
||||
the minimized yosys script OR a command line call to yosys with
|
||||
code-formatting (starting and ending with single backquotes).
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
|
|
@ -86,9 +88,9 @@ Reproduction Steps
|
|||
|
||||
`yosys -p ': minimum sequence of commands;' min.v`
|
||||
|
||||
- alternatively can provide a single code-block which includes the minimized
|
||||
design as a "here document" followed by the sequence of commands which
|
||||
reproduce the error
|
||||
Alternatively, you can provide a single code-block which includes the minimized
|
||||
design as a "here document" followed by the sequence of commands which
|
||||
reproduce the error
|
||||
|
||||
+ see :doc:`/using_yosys/more_scripting/load_design` for more on heredocs.
|
||||
|
||||
|
|
@ -101,7 +103,9 @@ Reproduction Steps
|
|||
# minimum sequence of commands
|
||||
```
|
||||
|
||||
- any environment variables or command line options should also be mentioned
|
||||
Don't forget to mention:
|
||||
|
||||
- any important environment variables or command line options
|
||||
- if the problem occurs for a range of values/designs, what is that range
|
||||
- if you're using an external tool, such as ``valgrind``, to detect the issue,
|
||||
what version of that tool are you using and what options are you giving it
|
||||
|
|
@ -115,24 +119,31 @@ Reproduction Steps
|
|||
around Yosys such as OpenLane; you should instead minimize your input and
|
||||
reproduction steps to just the Yosys part.
|
||||
|
||||
"Expected Behaviour"
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
.. _MVCE: https://stackoverflow.com/help/minimal-reproducible-example
|
||||
.. _bugpoint: https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html
|
||||
.. _how-to guide for bugpoint: https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html
|
||||
|
||||
- if you have a similar design/script that doesn't give the error, include it
|
||||
here as a reference
|
||||
- if the bug is that an error *should* be raised but isn't, are there any other
|
||||
commands with similar error messages
|
||||
|
||||
|
||||
"Actual Behaviour"
|
||||
Expected Behaviour
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- any error messages go here
|
||||
Describe what you'd expect to happen when we follow the reproduction steps
|
||||
if the bug was fixed.
|
||||
|
||||
If you have a similar design/script that doesn't give the error, include it
|
||||
here as a reference. If the bug is that an error *should* be raised but isn't,
|
||||
note if there are any other commands with similar error messages.
|
||||
|
||||
|
||||
Actual Behaviour
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Describe what you actually see when you follow the reproduction steps.
|
||||
|
||||
This can include:
|
||||
- any error messages
|
||||
- any details relevant to the crash that were found with ``--trace`` or
|
||||
``--debug`` flags
|
||||
- if you identified the point of failure in the source code, you could mention
|
||||
it here, or as a comment below
|
||||
|
||||
- the part of the source code that triggers the bug
|
||||
+ if possible, use a permalink to the source on GitHub
|
||||
+ you can browse the source repository for a certain commit with the failure
|
||||
and open the source file, select the relevant lines (click on the line
|
||||
|
|
@ -145,16 +156,19 @@ Reproduction Steps
|
|||
source specified, with a link to the source file at the given commit
|
||||
|
||||
|
||||
Additional details
|
||||
Additional Details
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- once you have created the issue, any additional details can be added as a
|
||||
comment on that issue
|
||||
- could include any additional context as to what you were doing when you first
|
||||
encountered the bug
|
||||
- was this issue discovered through the use of a fuzzer
|
||||
- if you've minimized the script, consider including the `bugpoint` script you
|
||||
used, or the original script, e.g.
|
||||
Anything else you think might be helpful or relevant when verifying or fixing
|
||||
the bug.
|
||||
|
||||
Once you have created the issue, any additional details can be added as a
|
||||
comment on that issue. You can include any additional context as to what you
|
||||
were doing when you first encountered the bug.
|
||||
|
||||
If this issue discovered through the use of a fuzzer, ALWAYS declare that.
|
||||
If you've minimized the script, consider including the `bugpoint` script you
|
||||
used, or the original script, for example:
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
|
|
@ -171,8 +185,7 @@ Additional details
|
|||
Minimized from
|
||||
`yosys -p ': original sequence of commands to produce error;' design.v`
|
||||
|
||||
- if you're able to, it may also help to share the original un-minimized design
|
||||
|
||||
+ if the design is too big for a comment, consider turning it into a `Gist`_
|
||||
If possible, it may also help to share the original un-minimized design.
|
||||
If the design is too big for a comment, consider turning it into a `Gist`_
|
||||
|
||||
.. _Gist: https://gist.github.com/
|
||||
|
|
|
|||
Loading…
Reference in New Issue