Skip to content

Latest commit

 

History

History
175 lines (104 loc) · 9.37 KB

CONTRIBUTING.md

File metadata and controls

175 lines (104 loc) · 9.37 KB
Raw

Contributing to the ROHD Hardware Component Library

Thank you for considering contributing to the ROHD Hardware Component Library (ROHD-HCL)! Contributions from the community are vital to making this a successful project.

Anyone interested in participating in ROHD-HCL is more than welcome to help!

Check out the component list to see what's already implemented and where there's more work to do.

Code of Conduct

ROHD-HCL adopts the Contributor Covenant v2.1 for the code of conduct. It can be accessed here.

Getting Help

Chat on Discord

Discord is a free online instant messaging app which you can use directly in your web browser or install to your device. Feel free to join to look around at the conversations and have a real-time discussion with the ROHD community. This a great place to ask questions, get help, engage with the rest of the community, and discuss new ideas.

Join the Discord server here: https://discord.com/invite/jubxF84yGw

GitHub Discussions

GitHub Discussions is a place where you can find announcements, ask questions, share ideas, show new things you're working on, or just discuss in general with the community! If you have a question or need some help, this is a great place to go.

You can access the discussions area here: https://github.com/intel/rohd-hcl/discussions

GitHub Issues

If something doesn't seem right, you're stuck, there's a critical feature/enhancement missing, you find a bug, etc. then filing an issue on the GitHub repository is a great option. Please try to provide as much detail as possible. Complete, stand-alone reproduction instructions are extremely helpful for bugs!

You can file an issue here: https://github.com/intel/rohd-hcl/issues/new/choose

Stack Overflow

Stack Overflow is a great tool to ask questions and get answers from the community. Use the rohd and/or rohd-hcl tag when asking your question so that others in the community who subscribe to that tag can find and answer your question more quickly!

Meetings in the ROHD Forum

The ROHD Forum is a periodic virtual meeting for developers and users of ROHD that anyone can join. Feel free to join the call!

Getting Started

Requirements

You must have Dart installed on your system to use ROHD and ROHD-HCL. You can find detailed instructions for how to install Dart here: https://dart.dev/get-dart

Setup Recommendations

On your own system

Visual Studio Code (VSCode) is a great IDE for development. You can find installation instructions for VSCode here: https://code.visualstudio.com/Download

The Dart extension extends VSCode with support for the Dart programming language and provides tools for effectively editing, refactoring and running. Check out the detailed information: https://dartcode.org/

If you're developing on a remote host, VSCode has a Remote SSH extension that can help: https://code.visualstudio.com/docs/remote/ssh

If you're on Microsoft Windows, you may want to consider developing with Ubuntu WSL for a Linux environment: https://learn.microsoft.com/windows/wsl/install

In GitHub Codespaces

GitHub Codespaces are a great feature provided by GitHub allowing you to get into a development environment based on a pre-configured container very quickly! You can use them for a limited number of hours per month for free. ROHD-HCL has set up GitHub Codespaces so that you can immediately start running examples and developing.

The below button will allow you to create a GitHub Codespace with ROHD-HCL already cloned and ready to roll:

Open in GitHub Codespaces

To run the component Configurator, especially useful for visualizing the RTL output of your component using different parameters:

cd confapp
flutter run --profile -d web-server --web-hostname=0.0.0.0 --web-port=3000

Cloning and Running the Tests

Once requirements are installed, you can clone and run the test suite:

git clone https://github.com/intel/rohd-hcl.git
cd rohd-hcl
dart pub get
dart test

How to Contribute

Reporting Vulnerabilities

Please report any vulnerabilities according to the information provided in the SECURITY.md file.

Reporting Bugs

Please report any bugs you find as a GitHub issue. Please try to provide as much detail as possible. Complete, stand-alone reproduction instructions are extremely helpful for bugs!

Some helpful information you can include:

  • Output of dart --version
  • Your dependencies from pubspec.yaml
  • The version of ROHD and ROHD-HCL you're using
  • Command you ran and output
  • Reproduction code and steps

Suggesting Enhancements

If you have an idea for a feature or enhancement that would make ROHD better, feel free to submit a GitHub issue! Discussion on the ticket about pros & cons, strategy, etc. is encouraged.

Discussing Issues

If you have an opinion or helpful information on any open issue, feel free to comment! Even if you don't have the time to implement a change, providing valuable input is great too!

Fix or implement an Issue

Take a look around the issues on the repo and see if there's any you'd like to take ownership of. For your first contributions, look for issues tagged with good first issue, which are intended to be easier to get started with. Feel free to ask for help or guidance!

Pull Requests

If you have a change that you have implemented and would like to contribute, you can open a pull request. Please try to make sure you have implemented tests covering the changes, if applicable. Smaller, simpler pull requests are easier to review.

Be sure to run the test suite (dart test) before asking for your code to be merged. You may also locally generate API documentation (dart doc) to make sure it looks right and doesn't have any errors. You should use the dart formatter on all code (dart format .), and may prefer to have it automatically format on every file save. If you are using VSCode with the Dart extension, then consider using the recommended settings: https://dartcode.org/docs/recommended-settings/

Tests must pass, documentation must generate, and the formatter must be run on every pull request or the automated GitHub Actions flow will fail.

Maintainers of the project and other community members will provide feedback and help iterate as necessary until the contribution is ready to be merged.

Please include the SPDX tag near the top of any new files you create:

// SPDX-License-Identifier: BSD-3-Clause

Here is an example of a recommended file header template:

// Copyright (C) 2021-2023 Intel Corporation
// SPDX-License-Identifier: BSD-3-Clause
//
// example.dart
// A very basic example of a counter module.
//
// 2021 September 17
// Author: Max Korbel <[email protected]>

Adding a New Component

To add a new component to the library, you can follow the steps below, referencing other components as examples.

  1. Create the dart code for constructing the module in lib/src.
  2. Create unit tests in test/.
  3. Create a Configurator for the component (enabling things like schematic generation, web-app generation, etc.).
    1. Create a new config in lib/src/component_config/commponents.
    2. Update the component registry in lib/src/component_config/components/component_registry.dart.
  4. Add documentation to doc/components/name.md.

If you would like to generate and view schematics locally, you'll need to have access to some tools. You can either use the dev container (via Codespaces or VS Code) or install the software from tool/gh_actions/install_opencadsuite.sh and tool/gh_actions/install_d3_hwschematic.sh. Then you can just run tool/gh_actions/create_htmls.sh, which will generate component schematic HTML documents in the build/ directory.

The confapp/ directory contains the source code for the Flutter configuration app, if you would like to run that locally.

Creating a New Package

Not every new contribution has to go directly into the ROHD or ROHD-HCL frameworks! If you have an idea for a reusable piece of hardware, tooling, verification collateral, or anything else that helps the ROHD ecosystem but is somewhat standalone, you can make your own package that depends on ROHD. Building an ecosystem of reusable components is important to the success of ROHD. Reach out if you want some help or guidance deciding if or how you should create a new package.

Style

Like ROHD, ROHD-HCL follows the official Dart recommended style guides and lints. The analyzer will help ensure that your code is written consistently with the rest of ROHD.

Here are some links to help guide you on style as recommended by Dart:

We recommend following these same guidelines for any of your own packages you may create for the ecosystem, as well.