Developer’s guide#

Here a few common agreements within the project.

Everything is pull request based#

Code changes can only be put into the release branch(es) by doing a pull request.

These pull requests then perform a couple of checks automatically. E.g. see Pre-commit tool.

Only if all checks pass and another person reviews and approves the changes, code can be rebased and merged.

Reviews#

You may be automatically assigned to review a code change.

The assignment is randomly chosen by the members of the team, having maintainer status.

Branching strategy#

We do not enforce a branch naming convention at the moment. Still we encourage to use

  • feat/ prefix for features

  • docs/ prefix for documentations changes

  • fix/ prefix for bug fixes

  • chore/ prefix for repeating tasks

Feature branches will be automatically deleted after the code has been merged.

We tend to cleanup outdated branches, from time to time.

Secrets#

CI secrets are exclusively managed through the Github action secrets.

No hardcoded secret shall be used anywhere.

We have Github and tool checks in place, that potentially will automatically revoke the published secret.

Team based permissions#

Access to a repository is managed through the membership in a particular Github organization team.

As a rule of thumb

  • clients/* have read-only access

  • team-distro/* and team-incubator/* have maintainer status.

If you are not seeing a certain repository, feel free to ask to be put into the matching team.

FAQ#

Scotty keeps reverting my changes

When I do `scotty build or scotty shell, my local branches are set back to the default branch and my changes are not applied. Why is that and what can I do about it?

Use uncommitted changes

By default the used kas software will set back all repositories to their defined defaults (defined by the manifest). This will not be done if you have uncommitted local changes in the repository in question.

Switch branch while in shell mode

You can switch the used branches in any repository while being in scotty shell mode. This is the preferred method of locally working on changes.

Scotty uses outdated sources

For my local workspace scotty seems to miss recently added patches/features that were merged. How do I update my local workspace?

Refresh the source tree

Running

$ scotty --force-sync --refresh ...

will update your local workspace to the latest available.

Loss of local changes

By doing so, there is a risk of loosing your local changes. Be sure to have them pushed to remote before the operation

Scotty is missing some tools/libraries

I am working with the latest release version of scotty and it seems that some tool and/or library is missing. What can I do about it?

Use the development scotty docker

There is a real chance that the the missing tool/library was added only in the current development version. You can configure scotty to use the development container by running

$ SCOTTY_DOCKER_IMAGE="ghcr.io/avnet-embedded/scotty:scarthgap" scotty ...

which will very likely fix your issues

How can I test my documentation changes?

I’ve written some changes to the documentation and I want to test them locally, how is that possible?

Run local documentation build

use the generate-docs command. The results will be can be found at build/docs/latest and can be viewed with any browser.

How can I test my changes to the test cases?

I’ve written some changes to some test cases and I want to test them locally, how is that possible?

Run tests against a live target

When using a real piece of hardware you can run the following from a scotty shell environment

$ devtool simplecore-test-target <image-name> <ip of the target> <ip of your host>

runtime cases only

This method applies only the test cases defined under lib/oeqa/runtime/cases

Grab a coffee

Depending on how many test cases are configured for the chosen image, running the test suite can take a while. So it might be the perfect time to grab a coffee.

Run tests against a qemu target

When using QEMU you can run the following from a scotty shell environment

$ bitbake <image-name> -c testimage

runtime cases only

This method applies only the test cases defined under lib/oeqa/runtime/cases

Grab a coffee

Depending on how many test cases are configured for the chosen image, running the test suite can take a while. So it might be the perfect time to grab a coffee.

How can I test my changes to the SDK test cases?

I’ve written some changes to some SDK test cases and I want to test them locally, how is that possible?

Run SDK tests

When using a real piece of hardware you can run the following from a scotty shell environment

$ bitbake <image-name> -c do_testcustomsdk

runtime cases only

This method applies only the test cases defined under lib/oeqa/sdk/cases

Grab a coffee

Depending on how many test cases are configured for the chosen image, running the test suite can take a while. So it might be the perfect time to grab a coffee.

How can I run all the linter tools locally?

Before pushing my changes I want to be sure that all the used linting tools don’t report any issues. How can I run them locally?

Run pre-commit

From the root of the repository with the changes you can run

$ pre-commit run -a

If you haven’t installed pre-commit yet, please see Pre-commit tool

The CI complains about one of my commit messages

In CI one of my commit messages is flagged, what can I do about that?

Follow the commit message guideline

Our policy for commit messages is as follows

  • subject line max. 60 chars

  • body line(s) max. 72 chars

  • subject line needs to match the regex ^.+: .*$

examples

Bad

I touched this file, because of this and that reason

This is a too long subject line and doesn’t match the regex.

Better use

file: change behavior

<reason of the change goes here>

Good

scotty: improve UX

This change adds some user experience improvements,
such as:

- better error messages
- improved workflow

Only in CI

Due to some limitations of the used tool, the checks can only be performed in CI and not locally

I need to patch a 3rd party layer

I need to patch a 3rd party layer to fix an error, how do I do that?

Use kas patch functionality

Before you proceed, please carefully check if it is possible to use a bbappend file to achieve the fix you are trying to code.

If not (e.g. for bbclass, MACHINE and layer configurations) we can make use of the kas patches feature

  • Code your patch against the latest clean manifest checkout of the repo/layer

  • create a patch with git format-patch

  • place the patch file in a SimpleCore™/SimpleSwitch™ layer and reference it in the corresponding configuration file under snippets.

For examples please see our SimpleCore™ repository

Patches are the last resort

Patches to 3rd party layers are the absolute last resort, if the same can be achieved by using other methods, the patch might get rejected in review.

Also creating a patch makes you directly responsible to upstream the patch, by contacting the 3rd party project

CI graphs#

Here a few graphs of the interactions with our CI