Shuffle around information about bug reports and contributions

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -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/).
 
 

CONTRIBUTING.md

@@ -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:
+## Asking questions
-https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html.
 
-# 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
+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.
-`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.
 
+## 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
+working quite right,
-open PR, even as a draft, tells everyone that you're working on it and they
+make a [pull request (PR)](https://github.com/YosysHQ/yosys/pulls).
-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
+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
+Learn more [here](https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html).
-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.

docs/source/yosys_internals/extending_yosys/contributing.rst

@@ -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 reproduction steps should be a minimal, complete and verifiable
-  the minimized design (Verilog or RTLIL), followed by a code-block containing
+example `MVCE`_.
-  the minimized yosys script OR a command line call to yosys with
+Providing an MVCE with your bug report drastically increases the likelihood that
-  code-formatting (starting and ending with single backquotes)
+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
+Alternatively, you can provide a single code-block which includes the minimized
-  design as a "here document" followed by the sequence of commands which
+design as a "here document" followed by the sequence of commands which
-  reproduce the error
+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
+Expected Behaviour
-  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
+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
+- the part of the source code that triggers the bug
-  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
@@ -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
+Anything else you think might be helpful or relevant when verifying or fixing
-  comment on that issue
+the bug.
-- could include any additional context as to what you were doing when you first
+
-  encountered the bug
+Once you have created the issue, any additional details can be added as a
-- was this issue discovered through the use of a fuzzer
+comment on that issue. You can include any additional context as to what you
-- if you've minimized the script, consider including the `bugpoint` script you
+were doing when you first encountered the bug.
-  used, or the original script, e.g.
+
+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 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`_
-  + if the design is too big for a comment, consider turning it into a `Gist`_
 
 .. _Gist: https://gist.github.com/