Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
206 lines (154 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

206 lines (154 loc) · 6.75 KB

Contribute to the CI Framework

Thank you for your interest in that project, and for taking time to contribute!

Create a new role

Run the following command to get your new role ready:

[laptop]$ make new_role ROLE_NAME=my_wonderful_role

Consuming install_yamls variables

CI Framework sets a couple of facts that are useful enough to mention, the cifmw_install_yamls_vars, that contains all the install_yamls variables that should be passed to any install_yamls target, and the cifmw_install_yamls_default, that contains the default values of every possible parameter of the install_yamls Makefiles.

Here is an example, based on a common use-case, on how to use those variables

:linenos:
---
- name: Deploy EDPM
  vars:
    make_edpm_deploy_env: "{{ cifmw_install_yamls_environment | combine({'PATH': cifmw_path }) }}"
    make_edpm_deploy_dryrun: "{{ cifmw_edpm_deploy_dryrun | bool }}"
  ansible.builtin.import_role:
    name: 'install_yamls_makes'
    tasks_from: 'make_edpm_deploy'

:linenos:
---
# Fetch openstackdataplane resources from the default namespace declared in install_yamls
# Makefile. If the NAMESPACE has been overridden by cifmw_install_yamls_vars this variable
# already points to the overridden value.
- name: Get info about dataplane node
  environment:
    PATH: "{{ cifmw_path }}"
  ansible.builtin.command: |
    oc get openstackdataplane -n {{ cifmw_install_yamls_defaults['NAMESPACE'] }}

Documentation

A new role must get proper documentation. Please edit the README.md located in the role directory in order to explain its use and details the exposed parameters. Documentation must properly build and display in the CI preview job in order for the PR to be accepted.

Testing

A new role must get proper Molecule testing. Please edit the default ones, add new scenarios if needed.

Then, you can run the following command in order to run tests locally:

[laptop]$ make run_ctx_pre_commit
[laptop]$ make run_ctx_ansible_test

This will create a container, and run tests in it (pre-commit and ansible-test).

`podman` is needed for this step.

One can also run:

[laptop]$ make enable-git-hooks

in order to configure automatic run of pre-commit tests in a local repository before pushing changing to any branch (see .githooks/pre-push)

Can't get Molecule

If your role can't be tested via molecule, you can remove the "molecule" directory generated in the role, and re-run make role_molecule to re-generate the the jobs and project list.

Please add a note in the role README.md for future reference.

A few words about using Git

Before you make a pull request, make sure that:

  • the title of your git commit message begins with the role name in brackets: [my_wonderful_role] or (my_wonderful_role)
  • the git commit body message is longer than 10 characters and describes the reason why you added this change
  • sign your git commit using the Signed-Off-By option by adding: --signoff or -s when using the command: git commit.
  • if you already make a commit, and you want to add Signed-Off-By, use command: git commit --amend --signoff

AI/LLM Assisted Development

When using AI tools for contributions, follow these guidelines to ensure transparency and code quality.

Attribution Requirements

  • Major AI contribution (substantial code/logic generation): Use Co-Authored-By:
  • Minor AI assistance (refactoring/optimization): Use Assisted-By:
[role_name] Add EDPM validation logic

Implements connectivity tests and health monitoring for EDPM nodes.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Signed-off-by: Your Name <your.email@example.com>

[role_name] Refactor validation error handling

Simplified logic and improved debugging messages.

Assisted-By: Gemini <noreply@google.com>
Signed-off-by: Your Name <your.email@example.com>

Code Quality Requirements

Before submitting AI-assisted code:

  • Review all generated code for correctness and security
  • Ensure compliance with existing project patterns and naming conventions
  • Verify no hardcoded credentials or sensitive data exposure
  • Test thoroughly, especially edge cases and error scenarios
  • Add proper documentation and comments

Review Process

  • Complete thorough self-review before PR submission
  • Standard review policy applies (minimum 2 reviewers)
  • Security-sensitive code requires additional maintainer review
  • Disclose AI assistance scope in PR description

Security and Best Practices

  • Never share sensitive project data with AI tools
  • Don't use AI for credential generation or security policy decisions
  • Provide relevant project context when prompting AI tools
  • Use AI as a starting point, not final solution
  • Maintain human oversight throughout development process

Adding new script

If you want/need to add a new script (python, bash, perl, ...), please provide proper documentation related to its use and usage. Please list the needs the script is covering, also in the commit message.

Testing new script

For random scripts, only the pre-commit target is useful from the Makefile. If you feel you can improve the testing, please create a new target in the Makefile, so that we can integrate it in Prow later on.

Help others debugging issues

If your code adds complex patterns, like consuming data sets and manipulating them in task vars, be sure to use the block/rescue pattern as shown bellow. There are many other examples in the framework code, and such pattern proves being of invaluable help whenever the run hits some uncovered corner case.

# Here we're creating tests in a block. You can of course put anything in such a block.
# You can also use such a block to share variables with multiple tasks.
- name: Try/catch block
  block:
    - name: Ensure all VM types have defined nets parameter
      ansible.builtin.assert:
        quiet: true
        that:
          - item.value.nets is defined
        msg: >-
          Inconsistency detected: VM type "{{ item.key }}"
          doesn't seem to have any network.
      loop: "{{ _cifmw_libvirt_manager_layout.vms | dict2items }}"
      loop_control:
        label: "{{ item.key }}"

# We caught an inconsistency, so we want to dump some data to make
# debugging easier. In this case, since the assert above is using
# the _cifmw_libvirt_manager_layout variable, we want to display it
# to ease debugging.
  rescue:
    - name: Dump built layout
      ansible.builtin.debug:
        var: _cifmw_libvirt_manager_layout

# Since "rescue" removes the errors, we have to get a proper "fail"
# to ensure we stop the whole run.
    - name: Fail for good
      ansible.builtin.fail:
        msg: >-
          Error detected, please check assertions and
          debugging output above.