Skip to content

contributing.md

Latest commit

 

History

History
183 lines (138 loc) · 6.46 KB

contributing.md

File metadata and controls

183 lines (138 loc) · 6.46 KB

Contributing to the kernel_settings Linux System Role

Where to start

The first place to go is Contribute. This has all of the common information that all role developers need:

  • Role structure and layout
  • Development tools - How to run tests and checks
  • Ansible recommended practices
  • Basic git and github information
  • How to create git commits and submit pull requests

Bugs and needed implementations are listed on Github Issues. Issues labeled with help wanted are likely to be suitable for new contributors!

Code is managed on Github, using Pull Requests.

Python Code

The Python code needs to be compatible with the Python versions supported by the role platform.

For example, see meta for the platforms supported by the role.

If the role provides Ansible modules (code in library/ or module_utils/) - these run on the managed node, and typically[1] use the default system python:

  • EL6 - python 2.6
  • EL7 - python 2.7 or python 3.6 in some cases
  • EL8 - python 3.6
  • EL9 - python 3.9

If the role provides some other sort of Ansible plugin such as a filter, test, etc. - these run on the control node and typically use whatever version of python that Ansible uses, which in many cases is not the system python, and may be a modularity release such as python311.

In general, it is a good idea to ensure the role python code works on all versions of python supported by tox-lsr from py36 on, and on py27 if the role supports EL7, and on py26 if the role supports EL6.[1]

[1] Advanced users may set ansible_python_interpreter to use a non-system python on the managed node, so it is a good idea to ensure your code has broad python version compatibility, and do not assume your code will only ever be run with the default system python.

Testing kernel_settings modules

It is recommended to use tox to set up your virtualenv for development/testing purposes:

dnf/yum install python-tox
tox -e py38

You can also use the virtualenv created by tox just like any other virtualenv created by python-virtualenv:

. .tox/env-py38/bin/activate
python
>>> import package.that.only.exists.in.venv

The unit tests and other tests are run by default when you use tox by itself or tox -e py38 for a specific python versioned environment. Note that other operating system packages may be required to be installed in order for tox to use pip to install python dependencies e.g. for python packages which have native components.

I would also strongly encourage you to use an IDE for development. For example, Visual Studio code python extension auto-discovers tests and allows you to run and debug unit tests. However, you may need to create a .env file like this, in order for code navigation, auto-completion, and test discovery to work correctly:

PYTHONPATH=/full/path/to/tuned:/full/path/to/linux-system-roles/kernel_settings/library

Testing the module

Ansible Module Development Guide

Using a tox python virtualenv from the kernel_settings directory:

. .tox/env-py38/bin/activate
TESTING=true [TEST_PROFILE=kernel_settings] python \
  library/kernel_settings.py args.json

looks for test profiles under tests/tuned/etc/tuned

to run the code in the debugger:

TESTING=true [TEST_PROFILE=kernel_settings] python -mpdb \
  library/kernel_settings.py args.json

Where args.json looks like this:

{
    "ANSIBLE_MODULE_ARGS": {
        "name": "kernel_settings",
        "sysctl": [
            {"name": "fs.inotify.max_user_watches", "value": 524288},
            {"name": "kernel.threads-max", "value": 30001}
        ],
        "sysfs": [
            {"name": "/sys/kernel/kexec_crash_size", "value": 337641472}
        ],
        "bootloader": [
            {"name": "cmdline", "value": [
                {"name": "mitigations", "value": "on"},
                {"name": "another"}
                ]
            }
        ],
        "selinux": [
            {"name": "avc_cache_threshold", "value": 512}
        ],
        "purge": false
    }
}

Running CI Tests Locally

Use tox-lsr with qemu

The latest version of tox-lsr supports qemu testing. https://github.com/linux-system-roles/tox-lsr#qemu-testing

Steps:

  1. If you are using RHEL or CentOS, enable the EPEL repository for your platform - https://docs.fedoraproject.org/en-US/epel/

  2. Use yum or dnf to install standard-test-roles-inventory-qemu

  3. Install tox

    • Use yum/dnf to install python3-tox - if that does not work, then use pip install --user tox, then make sure ~/.local/bin is in your $PATH

  4. Install tox-lsr https://github.com/linux-system-roles/tox-lsr#how-to-get-it

    pip install --user git+https://github.com/linux-system-roles/tox-lsr@main

  5. Download the config file to ~/.config/linux-system-roles.json from https://github.com/linux-system-roles/linux-system-roles.github.io/blob/main/download/linux-system-roles.json

  6. Assuming you are in a git clone of a role repo which has a tox.ini file - you can use e.g.

    tox -e qemu-ansible-core-2-20 -- --image-name centos-9 tests/tests_default.yml

There are many command line options and environment variables which can be used to control the behavior, and you can customize the testenv in tox.ini. See https://github.com/linux-system-roles/tox-lsr#qemu-testing

This method supports RHEL also - will download the latest image for a compose, and will set up the yum repos to point to internal composes.

See https://linux-system-roles.github.io/contribute.html for general development guidelines.