Developer Guide =============== Deploy for development ---------------------- This project uses pip to manage the package. If you want to work on the project yourself you can create the necessary links via:: $ pip3 install --user -e . That will install a backlink ~/.local/bin/kas to this project. Now you are able to call it from anywhere. For local development, use the **run-kas** wrapper from the project root directory. In this case, replace ``kas`` with ``path/to/run-kas``. Making Changes -------------- These sections provide an overview of common modifications along with the required steps. Changes of the project configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When changing the project configuration, you need to update the json configuration schema (``schema-kas.json``). Further, a short description of the changes needs to be added to :doc:`format-changelog`. After making the changes, you need to update the minimum and maximum values of ``header.version``. If the version was already updated after the last release, the version bump is not required. Add a new CLI option ^^^^^^^^^^^^^^^^^^^^ Options that take a parameter (e.g. ``--format json``) must be handled in ``kas-container`` as well. To keep the handling in ``kas-container`` simple, try to choose a unique option name across all plugins. Add a new sub-command (plugin) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To add a new sub-command, you need to create a new python file in the ``kas/plugins`` directory. It then needs to be imported and registered in ``kas/plugins/__init__.py``. Further, it needs to be registered in ``kas-container``, as well as in the ``container-entrypoint``. Each sub-command must be documented and have its own man page. The documentation is generated from the docstrings of the sub-command file and must be registered in ``docs/userguide/plugins.rst``. In addition, a manpage should be added in ``docs/_man/kas-plugin-`` and registered in ``docs/conf.py`` (as ``kas-.1``). Add support for new credentials ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Credentials are passed using environment variables. For details, see :ref:`checkout-creds-label`. These can either contain the credential directly or point to a credential file (e.g. ``.netrc``). To add support for a new credential, the following steps are required: - document the variable in :ref:`env-vars-label` - add the variable to the ``ENV_VARS`` list in ``libcmds.py::SetupHome`` - add a forward of the variable in ``kas-container`` - add the variable to the ``test_environment_variables.py`` test For variables pointing to a credential file, the following applies in addition: - the variable should end in ``_FILE`` (exceptions may apply) - ``kas-container`` - bind-mount the variable into ``/var/kas/userdata/`` - rewrite the variable to the path inside the container If the variable does not end in ``_FILE``, manual processing in the ``container-entrypoint`` script is needed to support it under rootless docker. Container image build --------------------- To build the container images kas provides, there is a script provided for your convenience. It uses docker buildx and requires BuildKit 0.13.0 or newer. To start the build both container variants, invoke:: $ scripts/build-container.sh You can limit the target type to either Yocto/OE (``kas``) or isar (``kas-isar``) via the ``--target`` options. See the script help for more options. Since release 4.3, the containers officially provided via ghcr.io are fully reproducible. To test this, you can use the following script, e.g. to validate that release:: $ scripts/reproduce-container.sh kas:4.3 Both scripts also support building/checking of the arm64 container images. See the help of both scripts for more details. Testing ------- The kas project has an extensive test suite. When adding new features or fixing bugs, it is recommended to add a test. The tests are written using the pytest framework. Decoupling from the calling environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please make sure to decouple the tests from your local environment. To simplify this, we provide the ``monkeykas`` fixture to clean up the environment prior to each test. When adding new kas environment variables, make sure to add these to the cleanup handler as well. When writing tests, no assumptions about the values of the following environment variables should be made (they also can be unset): - ``KAS_WORK_DIR`` - ``KAS_BUILD_DIR`` As tests might want to check data in the work or build dir, we provide the following helpers to safely access the corresponding paths (by reading the value from the environment variable at call time): - ``monkeykas.get_kwd()``: absolute path to the current kas work dir - ``monkeykas.get_kbd()``: absolute path to the current kas build dir - ``monkeykas.move_to_kwd(path)``: move the path to into the ``KAS_WORK_DIR``, if needed Tests that explicitly check for correct handling of the directory layout are encouraged to parameterize these paths by temporarily setting them via ``monkeykas.setenv()``. Tests that rely on features that might be subject to the current working directory should be marked with the ``dirsfromenv`` marker. By that, various combinations of ``KAS_WORK_DIR`` and ``KAS_BUILD_DIR`` are tested. Executing the testsuite ^^^^^^^^^^^^^^^^^^^^^^^ .. note:: The menu plugin tests require the ``snack`` package to be installed. On most distros this is packaged in ``python3-newt``, on Arch Linux it is part of libnewt. To run the tests, invoke:: $ python3 -m pytest Online and offline testing ^^^^^^^^^^^^^^^^^^^^^^^^^^ Some tests require internet access to fetch resources. These tests are marked with the ``online`` marker. To run these tests, invoke:: $ python3 -m pytest -m online To run all tests except the online tests, invoke:: $ python3 -m pytest -m "not online" When adding new tests, please consider whether they require internet access or not and mark them accordingly. In general, we prefer offline tests. Measure code coverage ^^^^^^^^^^^^^^^^^^^^^ To measure the code coverage of the unit tests, the ``pytest-cov`` package is required. On Debian systems, this is provided in ``python3-pytest-cov``. Once installed, run:: $ python3 -m pytest --cov --cov-report html The coverage in HTML format can then be found in `htmlcov`. Community Resources ------------------- Project home: - https://github.com/siemens/kas Source code: - https://github.com/siemens/kas.git - ``git@github.com:siemens/kas.git`` Documentation: - https://kas.readthedocs.org Mailing list: - kas-devel@googlegroups.com - Subscription: - kas-devel+subscribe@googlegroups.com - https://groups.google.com/forum/#!forum/kas-devel/join - Archives - https://groups.google.com/forum/#!forum/kas-devel - https://www.mail-archive.com/kas-devel@googlegroups.com/ Class reference documentation ----------------------------- ``kas.kas`` Module ^^^^^^^^^^^^^^^^^^ .. automodule:: kas.kas :members: ``kas.libkas`` Module ^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.libkas :members: ``kas.libcmds`` Module ^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.libcmds :members: ``kas.config`` Module ^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.config :members: ``kas.repos`` Module ^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.repos :members: ``kas.includehandler`` Module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.includehandler :members: ``kas.kasusererror`` Module ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.kasusererror :members: ``kas.plugins`` Module ^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: kas.plugins :members: