Skip to content

Latest commit

 

History

History
117 lines (88 loc) · 4.57 KB

CONTRIBUTING.md

File metadata and controls

117 lines (88 loc) · 4.57 KB
Raw

Design Goals - Simplicity

  • Easy to use
  • Easy to develop

Easy to use

  • Don't mimick API spec. Ansible spec should be a simplified version of API spec.
  • Goal is to expose minimum attributes to create, update or delete the entity
  • Keep backward & forward compatibility in mind when creating ansible spec
  • Look at the example of ansible spec for VM. Only 13 attributes are exposed from API to cater to 80-90% of use cases.

Easy to develop

  • Use scripts/codegento automatically generate code for the module development

    $python scripts/codegen subnets

  • scripts/codegen provides 3 things out of the box

    a. Client SDK.

    b. Ansible module plugin with run_module() implementation.

    c. Bootstrap code for creating and deleting entity.

  • Takes 3 steps to develop the module

    1. Define Ansible spec & type validator

    Example:

        def get_module_spec():
        mutually_exclusive = [("name", "uuid")]
        overlay_ipam_spec = dict(...)
        external_subnet_spec = dict(...)
        overlay_subnet_spec = dict(...)

        module_args = dict(
            name=dict(type="str", required=False),
            subnet_uuid=dict(type="str", required=False),
            vlan_subnet=dict(type="dict", options=vlan_subnet_spec),
            external_subnet=dict(type="dict", options=external_subnet_spec),
            overlay_subnet=dict(type="dict", options=overlay_subnet_spec),
        )

        return module_args
    1. Define ansible_param as key and _build_spec_* method as value in self.build_spec_methods map.

    Example:

    self.build_spec_methods = {
        "name": self._build_spec_name,
        "vlan_subnet": self._build_spec_vlan_subnet,
        "external_subnet": self._build_spec_external_subnet,
        "overlay_subnet": self._build_spec_overlay_subnet,
    }
    1. Implement _get_default_spec(self) and _build_spec_*(self, payload, config) methods

    Example:

        def _get_default_spec(self):
        return deepcopy(
            {
                "api_version": "3.1.0",
                "metadata": {"kind": "subnet"},
                "spec": {
                    "name": "",
                    "resources": {"ip_config": {}, "subnet_type": None},
                },
            }
        )

    def _build_spec_name(self, payload, value):
        payload["spec"]["name"] = value
        return payload, None

Workflow

  1. Create a github issue with following details

  • Title should contain one of the follwoing

    • [Feat] Develop ansible module for <api_name>
    • [Imprv] Modify ansible module to support <new_functionality>
    • [Bug] Fix <summary of issue> bug in <ansible_module_name>

  • Labels should contain one of the following

    • feature
    • enhancement
    • bug
    • test

  • Project should be selected

  • Assignees - assign yourself

  • Task list for list of tasks that needs to be developed as part of the fix

    • unit tests
    • integration tests
    • sanity tests
    • documentation
  1. Create one of the following git branch from main branch. Use issue#<id> from 1).
  • feat/<module_name>_issue#<id>
  • imprv/issue#<id>
  • bug/issue#<id>

  1. Develop sanity, unit and integrtaion tests.

  2. Create a pull request

  3. Ensure 85% code coverage on the pull request. Pull request with less than 85% coverage will be rejected.

  4. Link the pull request in issue#<id>

  5. After the pull request is merged, close the issue#<id>