Skip to content

How to Contribute to Welma

Contributions are very welcome. The checklist below summarizes the important information for any new contribution.

If you would like to contribute a new feature, make sure to discuss it beforehand with the Welma team, to avoid duplicating effort, and to keep a consistent direction for the project.

Email: contact@theembeddedkit.io

Coding Style

  • Follow the Recipe Style Guide of Yocto Project.
  • Use 4-space indentation for python and shell snippets.
  • Wrap lines at 80 characters (this is not only to deal with small screens but also to facilitate review after a small change in a line).
  • In comments, add a space after the leading # character.

  • Source files shall end with an newline character (LF, \n, ASCII 0x0a)

  • In conf/layer.conf, name BBFILE_COLLECTIONS with suffix -layer and without prefix meta-. Eg:

    meta-openembedded/meta-networking/conf/layer.conf
    BBFILE_COLLECTIONS += "networking-layer"

  • Name your images *-image*, as some tools (eg: runqemu) expect this pattern. Eg: 

    core-image-minimal.bb
welma-image-minimal.bb

Add Support for a New Machine

  • Add machine specific configuration:

    • In a repository named meta-welma-<vendor-suffix> (the suffix being defined on a case-by-case basis)
    • Use BSP components supplied by open-source communities or by vendors (board manufacturers), as much as possible, to minimize future maintenance costs.
    • See Support your machine (Arm)

  • Update/Create informative files:

    • license-digest
    • templates

  • In the end, the following must be achieved:

    • one can connect to the development image via SSH to 169.254.0.1 or fe80::1
    • if the board has a HW watchdog, then it must be configured and started before the kernel
    • the device has fixed MAC address (that does not change on reboot)
    • demo images run succesfully (meta-demo-headless, meta-demo-graphics/*)
    • swupdate, mender, mender-connected integrations

  • Create automatic tests (repository: welma-test): 

    welma-test/machine-${MACHINE}`
├── target.yml
├── tests-all.yml
└── tests-all-mender.yml

  • Add related jobs in ci: build, cvescan, test

  • Update welma-documentation, and create a page dedicated to the new machine, with:

    • Board identification
    • Boot sequence: description of the boot sequence on Welma
    • First installation
    • Regular boot: how to configure the machine for a regular boot
    • Appendix:
      • Practical instructions for developers: connecting the board, boot mode switches...
      • Specific technical choices (watchdog...)

Git Workflow

Our Git workflow is as follows:

The key aspects are:

  • Make an empty first commit.

  • Work in branches prefixed by feature/ or fix/:

    • Make clean commits as they are not automatically squashed during the merging and will remain visible.
    • Keep a linear git history by rebasing feature/ or fix/ branches onto develop.

  • Branches feature/ or fix/ are merged into develop:

    • Do merge requests and peer reviews.
    • Make a merge commit (no fast-forward).

In repositories that stick to Yocto revisions:

  • Branch master is named kirkstone or scarthgap depending on the Yocto branch alignment.
  • Branch develop is named kirkstone-next or scarthgap-next.