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

@@ -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
+Before you submit an issue, please check out the [how-to guide for
-one already exists.  Making sure that you have a minimal, complete and
+`bugpoint`](https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html).
-verifiable example (MVCE) is a great way to quickly check an existing issue
+This guide will take you through the process of using the [`bugpoint`
-against a new one.  Stack overflow has a guide on [how to create an
+command](https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html) in Yosys to
-MVCE](https://stackoverflow.com/help/minimal-reproducible-example).  The
+produce a [minimal, complete and verifiable
-[`bugpoint`
+example](https://stackoverflow.com/help/minimal-reproducible-example) (MVCE).
-command](https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/bugpoint.html)
+Providing an MVCE with your bug report drastically increases the likelihood that
-in Yosys can be helpful for this process.
+someone will be able to help resolve your issue.
 
 
 # Using pull requests

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 <<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/

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 <<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/