Contributing

Thank you for your interest in improving Cisco Catalystwan WAN SDK. Cisco Catalystwan WAN SDK is open-source under the Apache License Version 2.0 and welcomes contributions in the form of bug reports, feature requests, and pull requests.

Cisco Catalystwan WAN SDK is hosted on GitHub.

Support, Questions, and Feature Requests

Feel free to file a bug or feature request on GitHub. If your question is more general or does not fit neatly into one of those categories, please reach out through the available communication channels.

Reporting Issues

File a bug on GitHub. To help us understand the issue, please include as much information as possible, such as:

  • Operating system

  • Python version

  • If possible, a minimal case that can reproduce the issue

Pull Requests

It’s recommended to file a bug before starting work on anything. This allows for discussion with the maintainers and validation of your approach.

  • Follow PEP 8 standards.

  • Update documentation and tests if relevant.

  • Ensure your changes pass Cisco Catalystwan WAN SDK’s tests and lint suites before pushing.

Repository Structure

This repository is organized as a monorepo, containing multiple packages that are managed together. It is structured to include both manually maintained packages and automatically generated components.

Packages

  • Manual Packages: These are located in the ./packages directory. This folder contains packages that are manually developed and maintained. Each package within this directory typically has its own set of source files, configuration, and documentation.

  • Autogenerated Packages: These can be found in the ./versions directory. This section contains components or packages that are automatically generated. The generation process is typically based on predefined specifications or templates and may be updated frequently to reflect changes in those specifications.

This structure helps in maintaining a clear separation between manually edited and automatically generated code, facilitating better management and development workflows within the repository.

Manual Installation of Python Packages

To manually install the necessary Python packages in editable mode, you can use the pip install -e command. This is useful for development purposes, as it allows you to make changes to the package source code and have those changes immediately reflected without the need to reinstall the package. Follow these steps to install the specified packages:

pip install -e ./packages/catalystwan-types \
            -e ./packages/catalystwan-core \
            -e ./versions/catalystwan-v20_15 \
            -e ./versions/catalystwan-v20_16

By following these instructions, you will have the packages installed in an editable manner, allowing for easy development and testing.

Running Tests

Cisco Catalystwan WAN SDK runs its own tests. The best practice is to start with a known-good installation, e.g., from PyPI:

Notice: Required Python version is 3.12

pip install --upgrade nox

To just check for lint errors, run:

nox --session lint

To run against a particular Python version:


nox --session units

To check typing:

nox --session mypy

or for more strict

nox --session pytype

When you send a pull request, the CI will handle running everything, but it is recommended to test as much as possible locally before pushing. You can list all possible tests with:

nox --list-sessions