From b3c33839336d19bd19691a3f14a27558486ffd0a Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Mon, 26 Jan 2026 19:53:38 +0100 Subject: [PATCH] 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.