From 436a247d60c970015564de7a39e466ea3926d7e8 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Tue, 2 Dec 2025 19:48:32 +0100 Subject: [PATCH 1/7] Shuffle around information about bug reports and contributions --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 + CONTRIBUTING.md | 60 ++++++----- .../extending_yosys/contributing.rst | 99 +++++++++++-------- 3 files changed, 86 insertions(+), 75 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index f754d16c7..2c1483345 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 403292b0b..9ce09c013 100644 --- a/CONTRIBUTING.md +++ b/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: -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 -# 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 +working quite right, +make a [pull request (PR)](https://github.com/YosysHQ/yosys/pulls). + +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 -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. +Learn more [here](https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html). diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 70170fc48..1907832f1 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/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 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) +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. +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 - design as a "here document" followed by the sequence of commands which - reproduce the error +Alternatively, you 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. @@ -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 - 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" +Expected 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 - it here, or as a comment below - +- the part of the source code that triggers the bug + 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 - 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. +Anything else you think might be helpful or relevant when verifying or fixing +the bug. + +Once you have created the issue, any additional details can be added as a +comment on that issue. You can include any additional context as to what you +were doing when you first encountered the bug. + +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 the design is too big for a comment, consider turning it into a `Gist`_ +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`_ .. _Gist: https://gist.github.com/ From 6778151207880f4639b67627c7e73307e23859f2 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Tue, 2 Dec 2025 22:32:51 +0100 Subject: [PATCH 2/7] CONTRIBUTING: simplify CI description --- CONTRIBUTING.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ce09c013..c51cc9a68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,16 +41,20 @@ 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 +### 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 From 9c9f4f347e6e95496c13096cd5a4d255371a0718 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 3 Dec 2025 01:48:57 +0100 Subject: [PATCH 3/7] README: mention docs can be read offline --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 427d59c9e..3b2f41768 100644 --- a/README.md +++ b/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: From e2dffbf991f6464ee6494d1d69d16143aab703dd Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 3 Dec 2025 01:49:15 +0100 Subject: [PATCH 4/7] contributing: move to docs, expand --- CONTRIBUTING.md | 17 +- .../extending_yosys/contributing.rst | 167 ++++++++++++++---- 2 files changed, 137 insertions(+), 47 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c51cc9a68..6eadbec31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,19 +27,19 @@ Learn more [here](https://yosyshq.readthedocs.io/projects/yosys/en/latest/yosys_ ## 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). -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). +changes. See above to find the best way to [ask us questions](#asking-questions). ### Continuous integration @@ -49,13 +49,6 @@ 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 diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 1907832f1..6b8b4aa40 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -1,41 +1,6 @@ Contributing to Yosys ===================== -Coding Style ------------- - -Formatting of code -~~~~~~~~~~~~~~~~~~ - -- Yosys code is using tabs for indentation. Tabs are 8 characters. - -- A continuation of a statement in the following line is indented by two - additional tabs. - -- Lines are as long as you want them to be. A good rule of thumb is to break - lines at about column 150. - -- Opening braces can be put on the same or next line as the statement opening - the block (if, switch, for, while, do). Put the opening brace on its own line - for larger blocks, especially blocks that contains blank lines. - -- Otherwise stick to the `Linux Kernel Coding Style`_. - -.. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst - - -C++ Language -~~~~~~~~~~~~ - -Yosys is written in C++17. - -In general Yosys uses ``int`` instead of ``size_t``. To avoid compiler warnings -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 -------------- @@ -189,3 +154,135 @@ 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`_ .. _Gist: https://gist.github.com/ + +Contributing code +----------------- + +Code that matters +~~~~~~~~~~~~~~~~~ + +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`_. + +Before you build or fix something, search for existing `issues`_. + +.. _`Discourse forum`: https://yosyshq.discourse.group/ +.. _`issues`: https://github.com/YosysHQ/yosys/issues + +Making sense +~~~~~~~~~~~~ + +Given enough effort, the behavior of any code can be figured out to any +desired extent. However, the author of the code is by far in the best +position to make this as easy as possible. + +Yosys is a long-standing project and has accumulated a lot of C-style code +that's not written to be read, just written to run. We improve this bit +by bit when opportunities arise, but it is what it is. +New additions are expected to be a lot cleaner. + +Your change should contain exactly what it needs. This means: + +- nothing more than that - no dead code etc +- nothing missing + +Here are some software engineering approaches that help: + +- Use abstraction to model the problem and hide details + - Maximize the usage of types (structs over loose variables), + not necessarily in an object-oriented way + - Use functions, scopes, type aliases +- In new passes, make sure the logic behind how and why it works is actually provided + in coherent comments, and that variable and type naming is consistent with the terms + you use in the description. +- The logic of the implementation should be described in mathematical + or algorithm theory terms. Why would a non-trivial loop be guaranteed to terminate? + Is there some variant? Are you re-implementing a classic data structure from logic + synthesis? +- There's various ways of traversing the design with use-def indices (for getting + drivers and driven signals) available in Yosys. They have advantages and sometimes + disadvantages. Prefer not re-implementing these +- Prefer references over pointers, and smart pointers over raw pointers +- Aggressively deduplicate code. Within functions, within passes, + across passes, even against existing code +- Refactor and document existing code if you touch it, + but in separate commits from your functional changes +- Prefer smaller commits organized by good chunks. Git has a lot of features + like fixup commits, interactive rebase with autosquash +- Prefer declaring things ``const`` +- Prefer range-based for loops over C-style + +Common mistakes +~~~~~~~~~~~~~~~ + +.. - Pointer invalidation when erasing design objects on a module while iterating +.. TODO figure out how it works again and describe it +- Iterating over an entire design and checking if things are selected is more +inefficient than using the ``selected_*`` methods +- Remember to call ``fixup_ports`` at the end if you're modifying module interfaces + +Testing your change +~~~~~~~~~~~~~~~~~~~ + +Untested code can't be maintained. Inevitable codebase-wide changes +are likely to break anything untested. Tests also help reviewers understand +the purpose of the code change in practice. + +Your code needs to come with tests. If it's a feature, a test that covers +representative examples of the added behavior. If it's a bug fix, it should +reproduce the original isolated bug. But in some situations, adding a test +isn't viable. If you can't provide a test, explain this decision. + +Prefer writing unit tests (:file:`tests/unit`) for isolated tests to +the internals of more serious code changes, like those to the core of yosys, +or more algorithmic ones. + +The rest of the test suite is mostly based on running Yosys on various Yosys +and Tcl scripts that manually call Yosys commands. +See :doc:`/yosys_internals/extending_yosys/test_suites` for more information +about how our test suite is structured. +The basic test writing approach is checking +for the presence of some kind of object or pattern with ``-assert-count`` in +:doc:`docs/source/using_yosys/more_scripting/selections.rst`. + +It's often best to use equivalence checking with ``equiv_opt -assert`` +or similar to prove that the changes done to the design by a modified pass +preserve equivalence. But some code isn't meant to preserve equivalence. +Sometimes proving equivalence takes an impractically long time for larger +inputs. + +.. Changes to core parts of Yosys or passes that are included in synthesis flows +.. can change runtime and memory usage - for the better or for worse. This strongly +.. depends on the design involved. Such risky changes should then be benchmarked +.. with various designs. + +.. TODO Emil benchmarking + +Coding style +~~~~~~~~~~~~ + +Yosys is written in C++17. + +In general Yosys uses ``int`` instead of ``size_t``. To avoid compiler warnings +for implicit type casts, always use ``GetSize(foobar)`` instead of +``foobar.size()``. (``GetSize()`` is defined in :file:`kernel/yosys.h`) + +For auto formatting code, a :file:`.clang-format` file is present top-level. +Yosys code is using tabs for indentation. A continuation of a statement +in the following line is indented by two additional tabs. Lines are +as long as you want them to be. A good rule of thumb is to break lines +at about column 150. Opening braces can be put on the same or next line +as the statement opening the block (if, switch, for, while, do). +Put the opening brace on its own line for larger blocks, especially +blocks that contains blank lines. Remove trailing whitespace on sight. +Remember to keep formatting-only commits separate from functional ones. +Otherwise stick to the `Linux Kernel Coding Style`_. + +.. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst + + +.. Reviewing PRs +.. ------------- + +.. TODO Emil review process From 2843ea3008a620c3ba824e66bba6026225369b42 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 3 Dec 2025 13:10:20 +0100 Subject: [PATCH 5/7] contributing: fix rst --- .../extending_yosys/contributing.rst | 55 ++++++++++--------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 6b8b4aa40..6515e9a28 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -105,19 +105,21 @@ 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 + +* any error messages +* any details relevant to the crash that were found with ``--trace`` or ``--debug`` flags -- the part of the source code that triggers the bug - + if possible, use a permalink to the source on GitHub - + you can browse the source repository for a certain commit with the failure +* the part of the source code that triggers the bug + + * 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 + * should look something like ``https://github.com/YosysHQ/yosys/blob//path/to/file#L139-L147`` - + clicking on "Preview" should reveal a code block containing the lines of + * 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 @@ -184,43 +186,46 @@ New additions are expected to be a lot cleaner. Your change should contain exactly what it needs. This means: -- nothing more than that - no dead code etc -- nothing missing +* nothing more than that - no dead code etc +* nothing missing Here are some software engineering approaches that help: -- Use abstraction to model the problem and hide details - - Maximize the usage of types (structs over loose variables), +* Use abstraction to model the problem and hide details + + * Maximize the usage of types (structs over loose variables), not necessarily in an object-oriented way - - Use functions, scopes, type aliases -- In new passes, make sure the logic behind how and why it works is actually provided + * Use functions, scopes, type aliases + +* In new passes, make sure the logic behind how and why it works is actually provided in coherent comments, and that variable and type naming is consistent with the terms you use in the description. -- The logic of the implementation should be described in mathematical +* The logic of the implementation should be described in mathematical or algorithm theory terms. Why would a non-trivial loop be guaranteed to terminate? Is there some variant? Are you re-implementing a classic data structure from logic synthesis? -- There's various ways of traversing the design with use-def indices (for getting +* There's various ways of traversing the design with use-def indices (for getting drivers and driven signals) available in Yosys. They have advantages and sometimes disadvantages. Prefer not re-implementing these -- Prefer references over pointers, and smart pointers over raw pointers -- Aggressively deduplicate code. Within functions, within passes, +* Prefer references over pointers, and smart pointers over raw pointers +* Aggressively deduplicate code. Within functions, within passes, across passes, even against existing code -- Refactor and document existing code if you touch it, +* Refactor and document existing code if you touch it, but in separate commits from your functional changes -- Prefer smaller commits organized by good chunks. Git has a lot of features +* Prefer smaller commits organized by good chunks. Git has a lot of features like fixup commits, interactive rebase with autosquash -- Prefer declaring things ``const`` -- Prefer range-based for loops over C-style +* Prefer declaring things ``const`` +* Prefer range-based for loops over C-style Common mistakes ~~~~~~~~~~~~~~~ .. - Pointer invalidation when erasing design objects on a module while iterating .. TODO figure out how it works again and describe it -- Iterating over an entire design and checking if things are selected is more -inefficient than using the ``selected_*`` methods -- Remember to call ``fixup_ports`` at the end if you're modifying module interfaces + +* Iterating over an entire design and checking if things are selected is more + inefficient than using the ``selected_*`` methods +* Remember to call ``fixup_ports`` at the end if you're modifying module interfaces Testing your change ~~~~~~~~~~~~~~~~~~~ @@ -244,7 +249,7 @@ See :doc:`/yosys_internals/extending_yosys/test_suites` for more information about how our test suite is structured. The basic test writing approach is checking for the presence of some kind of object or pattern with ``-assert-count`` in -:doc:`docs/source/using_yosys/more_scripting/selections.rst`. +:doc:`/using_yosys/more_scripting/selections`. It's often best to use equivalence checking with ``equiv_opt -assert`` or similar to prove that the changes done to the design by a modified pass From 518610bbc4b0587e531e3149f70645614e588290 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Thu, 4 Dec 2025 17:26:51 +0100 Subject: [PATCH 6/7] contributing: split out git style --- .../extending_yosys/contributing.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 6515e9a28..109bfe9b0 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -210,10 +210,6 @@ Here are some software engineering approaches that help: * Prefer references over pointers, and smart pointers over raw pointers * Aggressively deduplicate code. Within functions, within passes, across passes, even against existing code -* Refactor and document existing code if you touch it, - but in separate commits from your functional changes -* Prefer smaller commits organized by good chunks. Git has a lot of features - like fixup commits, interactive rebase with autosquash * Prefer declaring things ``const`` * Prefer range-based for loops over C-style @@ -281,11 +277,22 @@ at about column 150. Opening braces can be put on the same or next line as the statement opening the block (if, switch, for, while, do). Put the opening brace on its own line for larger blocks, especially blocks that contains blank lines. Remove trailing whitespace on sight. -Remember to keep formatting-only commits separate from functional ones. + Otherwise stick to the `Linux Kernel Coding Style`_. .. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst +Git style +~~~~~~~~~ + +We don't have a strict commit message style. + +Some style hints: + +* Refactor and document existing code if you touch it, + but in separate commits from your functional changes +* Prefer smaller commits organized by good chunks. Git has a lot of features + like fixup commits, interactive rebase with autosquash .. Reviewing PRs .. ------------- From 16a420afee756f10c2b291e3d06c62563b1eb8f4 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Fri, 5 Dec 2025 12:16:14 +0100 Subject: [PATCH 7/7] contributing: clarify some things --- .../extending_yosys/contributing.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 109bfe9b0..4d1a74b2f 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -184,10 +184,14 @@ that's not written to be read, just written to run. We improve this bit by bit when opportunities arise, but it is what it is. New additions are expected to be a lot cleaner. -Your change should contain exactly what it needs. This means: +The purpose and behavior of the code changed should be described clearly. +Your change should contain exactly what it needs to match that description. +This means: -* nothing more than that - no dead code etc -* nothing missing +* nothing more than that - no dead code, no undocumented features +* nothing missing - if something is partially built, that's fine, + but you have to make that clear. For example, some passes + only support some types of cells Here are some software engineering approaches that help: @@ -251,7 +255,8 @@ It's often best to use equivalence checking with ``equiv_opt -assert`` or similar to prove that the changes done to the design by a modified pass preserve equivalence. But some code isn't meant to preserve equivalence. Sometimes proving equivalence takes an impractically long time for larger -inputs. +inputs. Also beware, the ``equiv_`` passes are a bit quirky and might even +have incorrect results in unusual situations. .. Changes to core parts of Yosys or passes that are included in synthesis flows .. can change runtime and memory usage - for the better or for worse. This strongly @@ -270,7 +275,8 @@ for implicit type casts, always use ``GetSize(foobar)`` instead of ``foobar.size()``. (``GetSize()`` is defined in :file:`kernel/yosys.h`) For auto formatting code, a :file:`.clang-format` file is present top-level. -Yosys code is using tabs for indentation. A continuation of a statement +Yosys code is using tabs for indentation. A tab is 8 characters wide, +but prefer not relying on it. A continuation of a statement in the following line is indented by two additional tabs. Lines are as long as you want them to be. A good rule of thumb is to break lines at about column 150. Opening braces can be put on the same or next line