Skip to content

Contributing

Contributions are welcome: bug reports, documentation fixes, support for more hardware, and code. This project is a proof of concept, so expect rough edges.

Where things go

The project is split over several repositories. Send a change to the one that owns the code:

Change Repository
Build configuration (kas files), CI, this documentation ethernet-switch-os
The configuration backend, CLI data model, SNMP clixon-switch-rs
The distro, the userspace, the web UI, firmware update meta-ethernet-switch-os
Realtek RTL83xx machines, kernel, device trees meta-rtl83xx-bsp
The Raspberry Pi switch meta-rpi-managed-switch-bsp
The QEMU x86-64 switch meta-qemu-switch-bsp
The RTL838x emulator rtl838x-qemu

See Layers and kas files for how the layers fit together, and Adding a board if you want to bring up new hardware.

Reporting a problem

Open an issue in the repository that owns the code, or in ethernet-switch-os if you are not sure which one that is. Say which board you use, the firmware version (shown on the status page) and how to reproduce the problem.

Sending a change

  1. Fork the repository and create a branch from master.
  2. Build the board you changed. While you work on a layer, add kas/opt/local-layers.yml so kas does not reset your commits, see Working on a layer.
  3. Try the result. You do not need hardware for most changes, see Testing and CI.
  4. Open a pull request against master. CI builds every board.

Keep a change to one topic and describe why it is needed, not only what it does.

Documentation

Documentation changes are as welcome as code. The pages are Markdown files in docs/ and the navigation is in mkdocs.yml. Build it locally with build --strict before you send it, as CI does, see Building this documentation.

Documenting a new feature

Each feature has one page in docs/features/, with the same four parts: an introduction (what the feature does, its rules, what the status fields mean), then how to configure it in the Web UI, the CLI and over RESTCONF. To add one:

  1. Copy docs/features/_template.md to docs/features/<feature>.md. Its comments say what goes where.
  2. Fill in all four parts. If an interface cannot configure the feature, say so in its part instead of leaving it out.
  3. Add the page under Features in the nav of mkdocs.yml.
  4. Add a row to the feature table in Getting started, and a card row to Using the web UI if the status page shows it.
  5. Add its configuration paths to YANG models.

License

The project is licensed under the MIT License. By contributing you agree that your contribution is licensed the same way.