From d84a97bdb12e870dc47ced05e8929b6d159d6e32 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 16:50:37 +0100 Subject: [PATCH 1/8] contributing: reformulate HQ GmbH involvement --- .../yosys_internals/extending_yosys/contributing.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 458d7dc36..f2ee144c5 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -317,10 +317,12 @@ Reviewing PRs is a totally valid form of external contributing to the project! Who's the reviewer? ~~~~~~~~~~~~~~~~~~~ -Yosys HQ is a company with the inherited mandate to make decisions on behalf -of the open source project. As such, we at HQ are collectively the maintainers. -Within HQ, we allocate reviews based on expertise with the topic at hand -as well as member time constraints. +Yosys HQ GmbH is a company with a mandate to make decisions for the good +of Yosys HQ open source software. It was co-founded by Claire Xenia Wolf, +the original author of Yosys. +Within it, we allocate reviews based on expertise with the topic at hand +as well as member time constraints. However, decisions including reviews +are also contributed by people external to the company. If you're intimately acquainted with a part of the codebase, we will be happy to defer to your experience and have you review PRs. The official way we like From 163e7e35abbd6198a7b354e1d6e5109514bbf7a3 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 16:52:09 +0100 Subject: [PATCH 2/8] contributing: finish cut off sentence --- docs/source/yosys_internals/extending_yosys/contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index f2ee144c5..c9d4c43e5 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -341,7 +341,8 @@ and stop being responsive, in the future, we might decide to remove such code if convenient and costly to maintain. It's simply more respectful of the users' time to explicitly cut something out than let it "bitrot". Larger projects like LLVM or linux could not survive without such things, but Yosys is far smaller, -and there are expectations +and there are implicit expectations of stability we aim to +relatively respect. .. TODO this deserves its own section elsewhere I think? But it would be distracting elsewhere From a8205de36829e63b4ac8e99183c754f3a3583657 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 16:56:02 +0100 Subject: [PATCH 3/8] contributing: require bug report inputs to pass check --- docs/source/yosys_internals/extending_yosys/contributing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index c9d4c43e5..74cab2650 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -27,6 +27,8 @@ The reproduction steps should be a minimal, complete and verifiable example `MVCE`_. Providing an MVCE with your bug report drastically increases the likelihood that someone will be able to help resolve your issue. +Make sure that your report input is free of any problems as reported by the +`check_` command. One way to minimize a design is to use the `bugpoint_` command. You can learn more in the `how-to guide for bugpoint_`. @@ -86,6 +88,7 @@ Don't forget to mention: .. _MVCE: https://stackoverflow.com/help/minimal-reproducible-example .. _bugpoint: https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html +.. _check: https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_passes_status.html#check-check-for-obvious-problems-in-the-design .. _how-to guide for bugpoint: https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html Expected Behaviour From cf607f77b921d3c92853fdf6e7ec1a120f941873 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 16:59:21 +0100 Subject: [PATCH 4/8] contributing: fix links --- .../source/yosys_internals/extending_yosys/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 74cab2650..7fcbbc011 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -28,9 +28,9 @@ example `MVCE`_. Providing an MVCE with your bug report drastically increases the likelihood that someone will be able to help resolve your issue. Make sure that your report input is free of any problems as reported by the -`check_` command. -One way to minimize a design is to use the `bugpoint_` command. -You can learn more in the `how-to guide for bugpoint_`. +`check`_ command. +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 From 1ca5c6bec6ed37bcfb323b8e3daa9d27ac8c9cac Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 17:00:14 +0100 Subject: [PATCH 5/8] contributing: Yosys HQ -> YosysHQ --- docs/source/yosys_internals/extending_yosys/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 7fcbbc011..9ef86edd9 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -320,8 +320,8 @@ Reviewing PRs is a totally valid form of external contributing to the project! Who's the reviewer? ~~~~~~~~~~~~~~~~~~~ -Yosys HQ GmbH is a company with a mandate to make decisions for the good -of Yosys HQ open source software. It was co-founded by Claire Xenia Wolf, +YosysHQ GmbH is a company with a mandate to make decisions for the good +of YosysHQ open source software. It was co-founded by Claire Xenia Wolf, the original author of Yosys. Within it, we allocate reviews based on expertise with the topic at hand as well as member time constraints. However, decisions including reviews From fd5a44056a98e3beb411aa992c946a5eccdd994b Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 17:17:25 +0100 Subject: [PATCH 6/8] .github: fix label for links --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 2c1483345..2ed92c913 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -6,7 +6,7 @@ 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. + Learn more in our [Reporting bugs](https://yosyshq.readthedocs.io/projects/yosys/en/latest/yosys_internals/extending_yosys/contributing.html#reporting-bugs) docs section. We fix well-reported bugs the fastest. If you have a general question, please ask it on the [Discourse forum](https://yosyshq.discourse.group/). From b3c33839336d19bd19691a3f14a27558486ffd0a Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 19:53:38 +0100 Subject: [PATCH 7/8] docs: consolidate contributing.md into contributing.rst harder --- CONTRIBUTING.md | 60 ++----------------- .../extending_yosys/contributing.rst | 39 ++++++++++-- 2 files changed, 40 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6eadbec31..ab698b6ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,59 +5,11 @@ first time contributing to an open source project, please take a look at the following guide about the basics: https://opensource.guide/how-to-contribute/#orienting-yourself-to-a-new-project. -## Asking questions +Check out our [Contributing guidelines](https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html) to learn the best ways to -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. ++ get help ++ report bugs ++ contribute code ++ review code -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. - -### Bug reports - -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 - -If you are working on something to add to Yosys, or fix something that isn't -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 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. - - -### Coding style - -Learn more [here](https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html). +If you're reading this file offline and don't have internet access, you can read the `contributing.rst` file [locally](docs/source/yosys_internals/extending_yosys/contributing.rst). diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 9ef86edd9..c19ef71da 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -4,8 +4,10 @@ Contributing to Yosys Reporting bugs -------------- -A good bug report includes the following information: +We fix well-reported bugs the fastest. A good bug report is an issue on the `issue tracker`_ +and includes the following information: +.. _`issue tracker`: https://github.com/YosysHQ/yosys/issues Title ~~~~~ @@ -28,9 +30,9 @@ example `MVCE`_. Providing an MVCE with your bug report drastically increases the likelihood that someone will be able to help resolve your issue. Make sure that your report input is free of any problems as reported by the -`check`_ command. -One way to minimize a design is to use the `bugpoint`_ command. -You can learn more in the `how-to guide for bugpoint`_. +`check` command. +One way to minimize a design is to use the `bugpoint` command. +You can learn more in the :doc:`how-to guide for bugpoint `. The reproduction steps are ideally a code-block (starting and ending with triple backquotes) containing @@ -87,7 +89,6 @@ Don't forget to mention: reproduction steps to just the Yosys part. .. _MVCE: https://stackoverflow.com/help/minimal-reproducible-example -.. _bugpoint: https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html .. _check: https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_passes_status.html#check-check-for-obvious-problems-in-the-design .. _how-to guide for bugpoint: https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html @@ -179,6 +180,12 @@ based on their descriptions first, code second. Before you build or fix something, also search for existing `issues`_. +We have open `developer 'jour fixe' (Dev JF) meetings`_ +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. + +.. _`developer 'jour fixe' (Dev JF) meetings`: https://docs.google.com/document/d/1SapA6QAsJcsgwsdKJDgnGR2mr97pJjV4eeXg_TVJhRU/edit?usp=sharing .. _`Discourse forum`: https://yosyshq.discourse.group/ .. _`issues`: https://github.com/YosysHQ/yosys/issues @@ -300,6 +307,26 @@ Otherwise stick to the `Linux Kernel Coding Style`_. .. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst +Pull requests (PRs) +~~~~~~~~~~~~~~~~~~~ + +If you are working on something to add to Yosys, or fix something that isn't +working quite right, +make a `pull request (PR)`_. + +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. + +We use `labels`_ to help categorise +issues and PRs. If a label seems relevant to your work, please do add it; this +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. + +.. _`pull request (PR)`: https://github.com/YosysHQ/yosys/pulls +.. _`labels`: https://github.com/YosysHQ/yosys/labels + Git style ~~~~~~~~~ @@ -381,3 +408,5 @@ they just are good enough to merge as-is. The CI is required to go green for merging. New contributors need a CI run to be triggered by a maintainer before their PRs take up computing resources. It's a single click from the github web interface. +We test on various platforms, compilers. Sanitizer builds are only tested +on the main branch. From bc8262574bb2e5b78554dea0aa7229464d6f0294 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 28 Jan 2026 11:47:19 +0100 Subject: [PATCH 8/8] contributing: small responses to feedback --- CONTRIBUTING.md | 2 +- .../yosys_internals/extending_yosys/contributing.rst | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab698b6ec..849d1fb00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,4 +12,4 @@ Check out our [Contributing guidelines](https://yosys.readthedocs.io/en/latest/y + contribute code + review code -If you're reading this file offline and don't have internet access, you can read the `contributing.rst` file [locally](docs/source/yosys_internals/extending_yosys/contributing.rst). +If you're reading this file offline and don't have internet access, you can [read the contributing.rst file locally](docs/source/yosys_internals/extending_yosys/contributing.rst). diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index c19ef71da..1ff77a1fd 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -89,7 +89,6 @@ Don't forget to mention: reproduction steps to just the Yosys part. .. _MVCE: https://stackoverflow.com/help/minimal-reproducible-example -.. _check: https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_passes_status.html#check-check-for-obvious-problems-in-the-design .. _how-to guide for bugpoint: https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html Expected Behaviour @@ -372,7 +371,7 @@ if convenient and costly to maintain. It's simply more respectful of the users' time to explicitly cut something out than let it "bitrot". Larger projects like LLVM or linux could not survive without such things, but Yosys is far smaller, and there are implicit expectations of stability we aim to -relatively respect. +respect within reason. .. TODO this deserves its own section elsewhere I think? But it would be distracting elsewhere @@ -408,5 +407,5 @@ they just are good enough to merge as-is. The CI is required to go green for merging. New contributors need a CI run to be triggered by a maintainer before their PRs take up computing resources. It's a single click from the github web interface. -We test on various platforms, compilers. Sanitizer builds are only tested -on the main branch. +We test on various platforms and compilers. Sanitizer builds are only +tested on the main branch.