mirror of
https://github.com/YosysHQ/yosys
synced 2025-06-07 06:33:24 +00:00
docs: Shuffling bug reporting guidelines
Move the "creating an issue" section from bugpoint.rst to "reporting bugs" in `contributing.rst`. Fix link to `CONTRIBUTING.md`. Update `CONTRIBUTING.md` to refer to the bugpoint guide instead of the stack overflow guide.
This commit is contained in:
Krystine Sherwin
parent
b23a081f80
commit
8ba612bc23
3 changed files with 144 additions and 144 deletions
|
|
@ -19,14 +19,14 @@ 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.
|
||||
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.
|
||||
|
||||
|
||||
# Using pull requests
|
||||
|
|
|
|||
|
|
@ -491,7 +491,7 @@ Identifying issues
|
|||
.. _the existing issues: https://github.com/YosysHQ/yosys/issues
|
||||
|
||||
- if there are no existing or related issues already, then check out the steps
|
||||
for :ref:`using_yosys/bugpoint:creating an issue on github`
|
||||
for :ref:`yosys_internals/extending_yosys/contributing:reporting bugs`
|
||||
|
||||
|
||||
Why context matters
|
||||
|
|
@ -526,137 +526,3 @@ Why context matters
|
|||
bug in ``+/xilinx/cells_map.v``, and carried on
|
||||
- but by following the failure back you've managed to identify a problem with
|
||||
`opt_expr` that could be causing other problems either now or in the future
|
||||
|
||||
|
||||
Creating an issue on GitHub
|
||||
---------------------------
|
||||
|
||||
- use the `bug report template`_
|
||||
|
||||
.. _bug report template: https://github.com/YosysHQ/yosys/issues/new?template=bug_report.yml
|
||||
|
||||
- short title briefly describing the issue, e.g.
|
||||
|
||||
techmap of wide mux with undefined inputs raises error during synth_xilinx
|
||||
|
||||
+ tells us what's happening ("raises error")
|
||||
+ gives the command affected (`techmap`)
|
||||
+ an overview of the input design ("wide mux with undefined inputs")
|
||||
+ and some context where it was found ("during `synth_xilinx`")
|
||||
|
||||
|
||||
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)
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
min.v
|
||||
```verilog
|
||||
// minimized Verilog design
|
||||
```
|
||||
|
||||
min.ys
|
||||
```
|
||||
read_verilog min.v
|
||||
# minimum sequence of commands to reproduce error
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
`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
|
||||
|
||||
+ see :doc:`/using_yosys/more_scripting/load_design` for more on heredocs.
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
```
|
||||
read_rtlil <<EOF
|
||||
# minimized RTLIL design
|
||||
EOF
|
||||
# minimum sequence of commands
|
||||
```
|
||||
|
||||
- any environment variables or command line options should also be mentioned
|
||||
- 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
|
||||
|
||||
.. warning::
|
||||
|
||||
Please try to avoid the use of any external plugins/tools in the reproduction
|
||||
steps if they are not directly related to the issue being raised. This
|
||||
includes frontend plugins such as GHDL or slang; use `write_rtlil` on the
|
||||
minimized design instead. This also includes tools which provide a wrapper
|
||||
around Yosys such as OpenLane; you should instead minimize your input and
|
||||
reproduction steps to just the Yosys part.
|
||||
|
||||
"Expected Behaviour"
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- 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"
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- any error messages go here
|
||||
- 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
|
||||
|
||||
+ 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
|
||||
number for the first relevant line, then while holding shift click on the
|
||||
line number for the last relevant line), click on the ``...`` that appears
|
||||
and select "Copy permalink"
|
||||
+ should look something like
|
||||
``https://github.com/YosysHQ/yosys/blob/<commit_hash>/path/to/file#L139-L147``
|
||||
+ clicking on "Preview" should reveal a code block containing the lines of
|
||||
source specified, with a link to the source file at the given commit
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
Minimized with
|
||||
```
|
||||
read_verilog design.v
|
||||
# original sequence of commands prior to error
|
||||
bugpoint -script <failure.ys> -grep "<string>"
|
||||
write_rtlil min.il
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
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`_
|
||||
|
||||
.. _Gist: https://gist.github.com/
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Contributing to Yosys
|
|||
|CONTRIBUTING|_ file.
|
||||
|
||||
.. |CONTRIBUTING| replace:: :file:`CONTRIBUTING.md`
|
||||
.. _CONTRIBUTING: https://github.com/YosysHQ/yosys/CONTRIBUTING.md
|
||||
.. _CONTRIBUTING: https://github.com/YosysHQ/yosys/blob/main/CONTRIBUTING.md
|
||||
|
||||
Coding Style
|
||||
------------
|
||||
|
|
@ -42,3 +42,137 @@ for implicit type casts, always use ``GetSize(foobar)`` instead of
|
|||
``foobar.size()``. (``GetSize()`` is defined in :file:`kernel/yosys.h`)
|
||||
|
||||
Use range-based for loops whenever applicable.
|
||||
|
||||
|
||||
Reporting bugs
|
||||
--------------
|
||||
|
||||
- use the `bug report template`_
|
||||
|
||||
.. _bug report template: https://github.com/YosysHQ/yosys/issues/new?template=bug_report.yml
|
||||
|
||||
- short title briefly describing the issue, e.g.
|
||||
|
||||
techmap of wide mux with undefined inputs raises error during synth_xilinx
|
||||
|
||||
+ tells us what's happening ("raises error")
|
||||
+ gives the command affected (`techmap`)
|
||||
+ an overview of the input design ("wide mux with undefined inputs")
|
||||
+ and some context where it was found ("during `synth_xilinx`")
|
||||
|
||||
|
||||
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)
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
min.v
|
||||
```verilog
|
||||
// minimized Verilog design
|
||||
```
|
||||
|
||||
min.ys
|
||||
```
|
||||
read_verilog min.v
|
||||
# minimum sequence of commands to reproduce error
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
`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
|
||||
|
||||
+ see :doc:`/using_yosys/more_scripting/load_design` for more on heredocs.
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
```
|
||||
read_rtlil <<EOF
|
||||
# minimized RTLIL design
|
||||
EOF
|
||||
# minimum sequence of commands
|
||||
```
|
||||
|
||||
- any environment variables or command line options should also be mentioned
|
||||
- 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
|
||||
|
||||
.. warning::
|
||||
|
||||
Please try to avoid the use of any external plugins/tools in the reproduction
|
||||
steps if they are not directly related to the issue being raised. This
|
||||
includes frontend plugins such as GHDL or slang; use `write_rtlil` on the
|
||||
minimized design instead. This also includes tools which provide a wrapper
|
||||
around Yosys such as OpenLane; you should instead minimize your input and
|
||||
reproduction steps to just the Yosys part.
|
||||
|
||||
"Expected Behaviour"
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- 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"
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- any error messages go here
|
||||
- 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
|
||||
|
||||
+ 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
|
||||
number for the first relevant line, then while holding shift click on the
|
||||
line number for the last relevant line), click on the ``...`` that appears
|
||||
and select "Copy permalink"
|
||||
+ should look something like
|
||||
``https://github.com/YosysHQ/yosys/blob/<commit_hash>/path/to/file#L139-L147``
|
||||
+ clicking on "Preview" should reveal a code block containing the lines of
|
||||
source specified, with a link to the source file at the given commit
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: markdown
|
||||
|
||||
Minimized with
|
||||
```
|
||||
read_verilog design.v
|
||||
# original sequence of commands prior to error
|
||||
bugpoint -script <failure.ys> -grep "<string>"
|
||||
write_rtlil min.il
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
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`_
|
||||
|
||||
.. _Gist: https://gist.github.com/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue