Skip to content

Latest commit

 

History

History
172 lines (120 loc) · 5.37 KB

CONTRIBUTING.md

File metadata and controls

172 lines (120 loc) · 5.37 KB
Raw

How to contribute to switchboard

Thank you for considering contributing to this project!

General guidelines

  • Start small, relationships need time to grow
  • All new features must come with pytests
  • Keep PRs short to simplify review
  • Large PRs should be preceded by discussions
  • Discuss with core team before proposing core changes
  • PRs should include changes only to files related to change
  • Comply with coding guidelines/style of project
  • Avoid style only code based PRs

Reporting issues

Check if this issue is already fixed in the latest release. If not, please include the following information in your post:

  • Describe what you expected to happen.
  • Describe what actually happened.
  • Include the full traceback if there was an exception.
  • List your Python, switchboard, and RTL simulator versions.
  • Include a minimal reproducible example

Submitting patches

If there is not an open issue for what you want to submit, prefer opening one for discussion before working on a PR. You can work on any issue that doesn't have an open PR linked to it or a maintainer assigned to it. These show up in the sidebar. No need to ask if you can work on an issue that interests you.

Include the following in your patch:

  • Include tests if your patch adds or changes code (should fail without the patch)
  • Update any relevant docs pages and docstrings.

First time setup

$ git config --global user.name 'your name'
$ git config --global user.email 'your email'

Clone/Fork Repository

  • Fork switchboard to your GitHub account (external contributors only)

  • Clone the main repository locally.

$ git clone https://github.com/{username}/switchboard
$ cd switchboard
  • Retrieve git submodules used in the project
$ git submodule update --init
  • Retrieve dependencies for running examples
$ pip install -r examples/requirements.txt
  • Add fork as a remote to push your work to (external contributors only)
$ git remote add fork https://github.com/{username}/switchboard

Install Python Requirements

  • Create a virtualenv.
$ python3 -m venv env
$ . env/bin/activate
  • Upgrade pip and setuptools.
$ python3 -m pip install --upgrade pip setuptools
  • Install the development dependencies
$ python3 -m pip install -e .[test]
$ python3 -m pip install -r examples/requirements.txt

Start coding

  • Create a branch to identify the issue you would like to work on.
$ git fetch origin
$ git checkout -b your-branch-name origin/main

  • Using your favorite editor, make your changes, and commit

  • Include tests that cover any code changes you make. Make sure the test fails without your patch. Run the tests as described below.

  • Push your commits to your fork on GitHub (external contributors)

$ git push --set-upstream fork your-branch-name
  • Push your commits to your switchboard branch on GitHub (team contributors)
$ git push -u origin your-branch-name

Running the tests

PRs need to pass a regression test suite before they can be merged.

  • The full set of tests that will be run can be found in .github/workflows/regression.yml. This currently includes Python-based tests, C-based tests, a test of FPGA emulation infrastructure, Python linting, and C/C++ linting.
  • The easiest way to run all of the tests locally is to install act, and then run act --rm pull_request in the top level of the repository. Omit --rm if you want the Docker container where the tests run to stay around after a failure (for debugging purposes).

It is also possible to run specific tests locally.

$ cd examples
$ pytest -s
$ cd ..
  • To run C-based tests:
$ cd tests
$ make
$ cd ..
  • To run a test of FPGA emulation infrastructure (requires SystemC):
$ cd examples/fpga_loopback
$ make test
$ cd ../..
  • To run Python linting (requires flake8)
$ flake8 .
  • To run Verilog linting on specific files (requires verible)
$ verible-verilog-lint --rules_config verible_lint.txt FILE1 FILE2 FILE3 ...

Create a Pull Request

Resources

Based on the SiliconCompiler contribution guidelines