Contributing
Note
Abstract
This document describes the development process of KIWI NG and how you can be part of it. This description applies to version 11.1.1.
The core appliance builder is developed in Python and follows the test-driven development rules.
If you want to implement a bigger feature, consider opening an issue on
GitHub first to discuss the changes. Or, join the discussion in the
#kiwi channel on Matrix.
Fork the upstream repository
On GitHub, navigate to: https://github.com/OSInside/kiwi.
In the top-right corner of the page, click Fork.
Create a local clone of the forked repository
$ git clone https://github.com/YOUR-USERNAME/kiwi
$ git remote add upstream https://github.com/OSInside/kiwi.git
Install Required Operating System Packages
KIWI NG requires additional packages at runtime that are not
provided by pip. Those will be pulled in by installing
the following package:
kiwi-systemdeps
The package is provided on the Open Build Service in the
Virtualization:Appliances:Builder
project. For manual inspection of the packages
that are pulled in from the above kiwi-systemdeps package, please refer
to the package/python-kiwi-spec-template spec file from the
checked-out Git repository.
Create a Python Virtual Development Environment
The following commands initialize and activate a development environment for Python 3:
$ poetry install --all-extras
Note
To create the python virtual env for another version of Python, e.g. 3.11, call the following prior the poetry install
$ poetry env use python3.11
The command above automatically creates the application script called kiwi-ng, which allows you to run KIWI NG from the Python sources inside the virtual environment using Poetry:
$ poetry run kiwi-ng --help
Running the Unit Tests
Before submitting your changes via a pull request, ensure that all tests pass and that the code has the required test coverage via the command:
$ make check
$ make test
Coding Style
KIWI NG follows the general PEP8 guidelines.
Documentation
KIWI NG uses Sphinx for the user documentation and man pages.
$ make docs
Bumping the Version
The KIWI NG project follows the Semantic Versioning scheme. We use the bumpversion tool for consistent versioning.
AI policy
KIWI NG has a policy of human-centric development. Only humans can be authors
and are ultimately responsible for the quality of their contributions.
That said, assisted development with “AI” tools (particularly contemporary
LLM-based tools) is permitted with the restriction that such usage is clearly
labeled with the Assisted-by: trailer in the pull request and commit message.
The format of the trailer is as such: Assisted-by:.
Examples of such trailers:
Tool |
Trailer |
|---|---|
Claude |
|
Gemini |
|
GitHub Copilot |
|
ChatGPT |
|
The trailers are required for the following scenarios:
AI wrote or generated code that ended up in the commit
AI substantially modified or refactored existing code
AI generated an implementation that the contributor then adapted
It is not required for the following scenarios:
AI was used for research only - asking questions, understanding APIs, exploring approaches - but the human wrote all the code
AI performed purely mechanical tasks like formatting, running commands, or committing
All submitted changes must be at least self-reviewed and all other guidelines continue to apply (follow code style, pass tests, make tests for new functionality, etc.)
Intentional obfuscation of AI tooling usage is grounds for rejection and may result in being blocked from future contributions.
Creating an RPM Package
We provide a template for an RPM spec file in
package/python-kiwi-spec-template alongside a rpmlint
configuration file and an automatically updated
python-kiwi.changes.
To create the necessary files to build an RPM package via rpmbuild, run:
$ make build
The sources are collected in the dist/ directory. These can be
directly built with rpmbuild, fedpkg, or submitted
to the Open Build Service using osc.