Contributing Guide
To set up a development environment, build, and run the checks, see Development Guide.
Submitting Pull Requests
This document exists to define some conventions and standards for all pull requests. These guidelines are not rigid and may be evaluated on a case-by-case basis, but contributors are encouraged to follow them.
The process takes inspiration from Submitting patches: the essential guide to getting your code into the kernel, although the requirements here are less stringent than those of the Linux kernel.
This guide also serves as a single reference point for contributors, avoiding the need to repeatedly explain common issues with pull requests.
Describe Your Changes
Describe the problem you are trying to solve. Whether your patch is a one-line bug fix or a 5000-line new feature, there must be a clear underlying problem that motivated the work.
Convince the reviewer that the problem is real, worth fixing, and that it makes sense to read past the first paragraph.
Once the problem is established, describe what you are doing to solve it, in technical detail. Explain the change in plain English so the reviewer can verify that the code behaves as intended.
Separate Your Changes
Each logical change should be separated into its own commit or pull request.
It is acceptable to group multiple commits into a single pull request if they address a single issue (for example, a tracked issue). Keep in mind that smaller, focused pull requests are easier to review and are typically merged faster.
Style-Check Your Changes
Before submitting, ensure that your code follows standard Rust style conventions.
Please run:
There is no intention to deviate from standard Rust formatting or linting rules, so these tools should be considered mandatory.
Sign Your Work – Developer’s Certificate of Origin
Signing off commits improves tracking of who authored which changes. While this practice originates from Linux kernel development and mailing-list workflows, the simple Signed-off-by line is useful even here—especially when preserving authorship of work that may otherwise be abandoned.
The sign-off is a single line added at the end of the commit message, certifying that you wrote the code or otherwise have the right to submit it as an open-source contribution.
Developer’s Certificate of Origin 1.1
By making a contribution to this project, I certify that:
-
The contribution was created in whole or in part by me, and I have the right to submit it under the open-source license indicated in the file; or
-
The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open-source license, and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open-source license (unless I am permitted to submit under a different license), as indicated in the file; or
-
The contribution was provided directly to me by some other person who certified (a), (b), or (c), and I have not modified it.
-
I understand and agree that this project and the contribution are public, and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open-source license(s) involved.
To indicate agreement, add the following line to your commit message:
Signed-off-by: Ayush Singh <ayush@beagleboard.org>
Use a known identity—anonymous contributions are not accepted.
If you use:
git commit -s
the sign-off will be added automatically. Reverts should also include a sign-off; using:
git revert -s
will take care of this for you.
Updating Screenshots
The screenshots in assets/screenshots (used by the README and the Flathub metainfo) are generated from the bb-imager-gui-ui page examples:
make screenshots # all pages
make screenshot-review # a single page
-
A KDE Plasma session is required. Flathub wants window decorations in screenshots, and GNOME/sway screenshots do not include them. Capturing uses
spectacle, and conversion to webp usescwebp(libwebp-toolson Fedora,webpon Debian/Ubuntu). Inside a toolbox/distrobox, both are run on the host viaflatpak-spawn --hostautomatically. -
Each page is shown in the example’s default state. To change what a screenshot shows, change the default state of the corresponding example in
bb-imager-gui-ui/examples. -
Keep the mouse pointer away from the window that opens, and do not switch focus while capturing:
spectaclecaptures the active window, and hover states would show up in the image. -
If remote icons are missing in the result, increase the delay before capture, e.g.
make screenshots SCREENSHOT_DELAY=6.