From 8ba612bc2338e7eed52e7478cc830bccac0acd49 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 29 Apr 2025 10:13:29 +1200 Subject: [PATCH] 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. --- CONTRIBUTING.md | 16 +-- docs/source/using_yosys/bugpoint.rst | 136 +----------------- .../extending_yosys/contributing.rst | 136 +++++++++++++++++- 3 files changed, 144 insertions(+), 144 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c4376cc4..74f9ab10d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst index 6f58e3d5b..89c58a8f4 100644 --- a/docs/source/using_yosys/bugpoint.rst +++ b/docs/source/using_yosys/bugpoint.rst @@ -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 </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 -grep "" - 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/ diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 69258aa5f..70170fc48 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -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 </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 -grep "" + 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/