# Contributor guide

First of all, thanks for considering contributing to SpinalHDL project!

The goal of this document is to guide you in your contribution, to help you to
help us!


## How-to

To keep work organized, contributions are done the following way:

1. Before implementing:
    * If you have an idea of thing you want to implement, please open an issue
      to discuss. It will help to define the goal of the changes, and to figure
      out the potential drawbacks before implementing. Also, it may prevent
      merge conflicts.
    * Else you can find good first issues
      [here for the code](https://github.com/SpinalHDL/SpinalHDL/contribute)
      and
      [here for the docs](https://github.com/SpinalHDL/SpinalDoc-RTD/contribute)
1. When you work is ready for review, feel free to open a pull request (PR). It
   can be seen as suggested modifications that will be reviewed. You can open a
   PR if you want some feedback even if you know your implementation is not
   complete yet. In this case, it is preferred to mark it as a draft PR.
1. Test your code with unit tests. It will make sure that your modifications are
   future-proof and do not break after other changes in the repository.
1. Document your code, using Scaladoc `/** */` and, if relevant, by contributing
   to [the documentation repository](https://github.com/SpinalHDL/SpinalDoc-RTD).

When you open a PR, it contains a checklist so that you do not forget things.

Note for experienced contributors: "contributing" links above are good first
issues if you are discovering the project. If you are used to contributing to
SpinalHDL, the list of priority issues for the code is the
[Current milestone](https://github.com/SpinalHDL/SpinalHDL/milestone/1).
If there are issues labelled as "bug" in this list, please consider fixing them
first.


## File structure

### Root listing

| File              | Description                                 |
| :---              | :---                                        |
| `build.sbt`       | Build file for `sbt`                        |
| `CONTRIBUTING.md` | Contributor guide                           |
| `core/`           | Things imported with `import spinal.core._` |
| `idslpayload/`    | Interface for `idslplgin`                   |
| `idslplugin/`     | Scala compiler iDSL extension               |
| `lib/`            | Things imported with `import spinal.lib._`  |
| `LICENSE`         | Redirection to other `LICENSE` files        |
| `LICENSE_core`    | License for Spinal core                     |
| `LICENSE_lib`     | License for Spinal standard library         |
| `project`         | Build files                                 |
| `README.md`       | Project description                         |
| `scala.yml`       | GitHub-specific file                        |
| `scalaplugin`     | Compiler plugins                            |
| `sim`             | Internals to interact with simulators       |
| `tester`          | All tests                                   |
| `tools.sh`        | `sh` functions to install EDA tools         |

There are several Scala projects in this repository:

- `spinal.core`: the DSL to describe hardware
- `spinal.lib`: the standard library to help designers
- `spinal.sim`: internals to interact with compatible simulators
- `spinal.tester`: global / integration tests


### Projects / libraries

Each project has the following structure:

- `src/`: the source code
- `target/`: files generated by the compiler

Each `src/` directory contains:

- `main/`: the source code
- `test/`: unit tests

Each of these directories have a folder named `scala/` then the path is the path
of the item. Files in other languages (eg: Java) can be put into a folder along
`scala/`.

For instance `UInt` used a SpinalHDL hardware description usually comes from
`import spinal.core._`, as its Scala path is `spinal.core.UInt`. So it is
defined in:

```
File path:
core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  Library name
└── src . . . . . . . . . . . . . . . . . . . . . . . . . . .  It is source code
    └── main . . . . . . . . . . . . . . . . . . . . .   It is in its definition
        └── scala . . . . . . . . . . . . . . . . . . . .  It is some Scala code
            └── spinal/core/UInt.scala . . . . . . . . . . . . . .  Path to item
Scala path:
               `spinal.core.UInt`
```


### Testing

Tests are mostly integration tests, put into `tester` project.

Its `src/` folder contains a `main/` folder, containing scratchpads, and a
`test/` folder containing actual tests.

In `src/test/`, are:

* `python/` for `cocotb` tests
* `resources/` with RTL files useful for tests
* `scala/spinal/tester/scalatest/` with Scala tests
* `scala/spinal/tester/generator/` with scratchpads
* `scala/spinal/tester/misc/` with scratchpads
* `scala/spinal/tester/pending/` with scratchpads

Added to these folders are two scratchpads (from root): `sim/yolo` and
`core/src/test/scala/landa`.


## Notes for triage & reviews

* Activity
  * [All Activity](https://github.com/SpinalHDL/SpinalHDL/pulls?q=sort%3Aupdated-desc)
  * [Current Activity](https://github.com/SpinalHDL/SpinalHDL/issues?q=sort%3Aupdated-desc+is%3Aopen)
* PRs
  * [PRs to merge](https://github.com/SpinalHDL/SpinalHDL/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen+draft%3Afalse) (do not forget to review all PRs)
  * [PRs which need help](https://github.com/SpinalHDL/SpinalHDL/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen+draft%3Atrue+label%3A%22need+more+info+%3Aarrows_counterclockwise%3A%22)
* Issues
  * [In-progress issues](https://github.com/SpinalHDL/SpinalHDL/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
  * [Issues needing approval](https://github.com/SpinalHDL/SpinalHDL/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22need+agreement+%3Aspeech_balloon%3A%22)
