docs: shuffle and expand contributing info

.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,70 +1,63 @@
-# 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
 
+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/).
 
-# 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
-questions](#asking-questions).
-
-In general, all changes to the code are done as a PR, with [Continuous
-Integration (CI)](https://github.com/YosysHQ/yosys/actions) tools that
-automatically run the full suite of tests compiling and running Yosys.  Please
-make use of this!  If you're adding a feature: add a test!  Not only does it
-verify that your feature is working as expected, but it can also be a handy way
-for people to see how the feature is used.  If you're fixing a bug: add a test!
-If you can, do this first; it's okay if the test starts off failing - you
-already know there is a bug.  CI also helps to make sure that your changes still
-work under a range of compilers, settings, and targets.
+working quite right,
+make a [pull request (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 above to find the best way to [ask us questions](#asking-questions).
+
+### Continuous integration
+
+[Continuous Integration (CI)](https://github.com/YosysHQ/yosys/actions) tools
+automatically compile Yosys and run it with the full suite of tests.
+If you're a first time contributor, a maintainer has to trigger a run for you.
+We test on various platforms, compilers. Sanitizer builds are only tested
+on the main branch.
 
 ### Labels
 
 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
-
-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.
+### Coding style
 
-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).

README.md

@@ -246,6 +246,8 @@ Building the documentation
 
 Note that there is no need to build the manual if you just want to read it.
 Simply visit https://yosys.readthedocs.io/en/latest/ instead.
+If you're offline, you can read the sources, replacing `.../en/latest`
+with `docs/source`.
 
 In addition to those packages listed above for building Yosys from source, the
 following are used for building the website: