Development Guide

Setting up the development environment

• Clone the IBM Cloud Pak Operations CLI GitHub repository:

  git clone https://github.com/IBM/cloud-pak-operations-cli
  

• Execute the following commands to create a virtual environment within the directory the GitHub repository was cloned into:

  • Linux/macOS:

    pip3 install virtualenv
    virtualenv .venv
    . .venv/bin/activate
    pip3 install --editable .
    

  • Windows:

    pip3 install virtualenv
    virtualenv .venv
    .venv/Scripts/activate
    pip3 install --editable .
    

Extending the IBM Cloud Pak Operations CLI

The IBM Cloud Pak Operations CLI is based on the Click package.

Registering a new Click command

To register a new Click command, add the Python module containing the command to the commands directory or one of its subdirectories.

Registering a new Click group

To register a new Click group (e.g., click-group-name), add a Python package (i.e., a directory containing a file named __init__.py) to the commands directory or one of its subdirectories (e.g., click_group_name). For each Python package below the commands directory, a new Click group (i.e., an instance of LazyLoadingMultiCommand) is implictly created.

Writing an IBM Cloud Pak Operations CLI plug-in

The IBM Cloud Pak Operations CLI is extensible via plug-ins, which are regular distribution packages managed by pip.

To add Click commands or command groups to a built-in command group, CLI plug-ins (i.e., distribution packages) must export packages by specifying one or more entry points within the cloud_pak_operations_cli_plugins group in their configuration file.

To specify the built-in command group, the __doc__ attribute of the __init__.py module of an entry point package must be set to the path of the built-in command group in the command hierarchy. Nested built-in command groups must be separated by slashes. If the __doc__ attribute is not set, Click commands or command groups are added to the root command group.

Examples

1. Package structure

package_1
| __init__.py (__doc__ = "")
| … (modules and subpackages)

package_2
| __init__.py (__doc__ = "adm/config")
| … (modules and subpackages)

1. setup.cfg:

[options.entry_points]
cloud_pak_operations_cli_plugins =
    entry_point_1 = package_1
    entry_point_2 = package_2

Running unit tests

Unit tests are based on the unittest package and contained in the tests.test package. Execute the following command to execute all unit tests within your virtual environment:

python -m unittest discover tests.test

Profiling using FunctionTrace (Linux/macOS)

Use FunctionTrace to profile an IBM Cloud Pak Operations CLI command as follows:

• Install Rust and Cargo

• Install the FunctionTrace server:

  cargo install functiontrace-server
  

• Install the Python client in your virtual environment:

  pip3 install functiontrace
  

• Execute the following command to profile an IBM Cloud Pak Operations CLI command:

  python3 -m functiontrace $(which cpo) $COMMAND
  

• After having executed the CLI command, the FunctionTrace server prints the location of the profiling data file:

  [FunctionTrace] Wrote profile data to …
  

• Use Firefox Profiler to analyze the profiling data file.

Correcting copyright headers

Execute the following command to automatically correct copyright headers of source code files:

• Install required packages:

  pip3 install dulwich
  

• Execute the update-copyright-headers command:

  python3 -m scripts.scripts update-copyright-headers $REPO_PATH
  

Testing the release of a new version using semantic versioning

• Create a new branch, commit the code leading to a new release, and tag the commit with a semantic version:

  git tag v$MAJOR.$MINOR.$PATCH
  

• Push the branch and the tag:

  git push --atomic origin $BRANCH_NAME v$MAJOR.$MINOR.$PATCH
  

• Delete the tag:

  git tag --delete v$MAJOR.$MINOR.$PATCH
  

• Delete the remote tag:

  git push --delete origin v$MAJOR.$MINOR.$PATCH
  

After having pushed the branch and the tag, the following actions are performed:

• A Python distribution is built using the tagged version as the package version.
• The Python distribution is published to TestPyPI.

To install a specific IBM Cloud Pak Operations CLI version from TestPyPI, execute the following command:

pip3 install --extra-index-url https://pypi.org/simple --index-url https://test.pypi.org/simple/ cloud-pak-operations-cli==$VERSION

If you are satisfied with the result and would like to publish the Python distribution to PyPI, continue as follows:

• Create a pull request based on the created branch
• Merge the reviewed pull request

Releasing a new version using semantic versioning

• On the master branch, tag the latest commit with a semantic version:

  git tag v$MAJOR.$MINOR.$PATCH
  

• Push the tag:

  git push origin v$MAJOR.$MINOR.$PATCH
  

After having pushed the tag, the following actions are performed:

• A Python distribution is built using the tagged version as the package version.
• The Python distribution is published to PyPI.
• A Docker image containing the installed Python distribution is built and pushed to Quay.
• A GitHub release draft is created, which must be manually published.

References

• Coding Guidelines