CONTRIBUTING.md

How to contribute

We're really glad you want to help.

Here are some important resources:

• Want to add something from yourself? Make a PR - remember to follow code guidelines.

  Contributors from CiscoDevNet organization:

  To make a PR - pull the repository, create branch for your changes, make said changes and make the pull request. Now just wait for the review and feedback from our developers.

  Contributors outside CiscoDevNet organization

  To make a PR - fork our repository, make your changes and make the pull request. Now just wait for the review and feedback from our developers.
• Feel free to review existing PRs, any suggestion is welcome.
• Want to help but you don't have any new ideas for improvement or feature? Take any issue and fix it.
• Bugs? Report it here - remember to provide as much information as you can.
• Need some additional feature? Let us know here

Testing

Test newly implemented features on Cisco SD-WAN, ideally on different versions. If you don't have access to any SD-WAN you can use Cisco provided sandboxes.

• Building package for tests
  To make a .whl file run

  poetry build
  

  Then in /catalystwan/dist/ directory there is a .whl file named catalystwan-<version>-py3-none-any.whl, which can be installed by running

  pip install catalystwan-<version>-py3-none-any.whl
  

Submitting changes

Make clear PR description and include doc strings in your code to make it easily understandable.

Always write a clear log message for your commits.

Enviroment setup

1. Download Python3.8 or higher.

2. Download repository

   git clone https://github.com/cisco-open/cisco-catalyst-wan-sdk.git
   

3. Install and configure poetry (v1.3.1 or higher) https://python-poetry.org/docs/#installation

   On linux/mac this usually means:

   curl -sSL https://install.python-poetry.org | python3 -
   poetry config virtualenvs.in-project true
   

4. Install dependecies

   poetry install
   

5. Activate pre-commit

   pre-commit install
   

Environment Variables

• catalystwan_devel when set: loggers will be configured according to ./logging.conf and urllib3.exceptions.InsecureRequestWarning will be suppressed

• catalystwan_auth_trace when set: authentication requests will not be anonymized in logs

• catalystwan_export_endpoints when set: endpoints-md pre-commit step will generate ENDPOINTS.md file in addition to perform definition checks. This should be set only when creating version bump commit with new release tag.

Code guidelines

Start reading our code, and you'll get the hang of it.

• Make sure you run pre-commit on your code before submitting it, it will make sure you follow rules we use:
  • line length below 120
  • double quotes
  • isort
  • black
  • mypy
  • flake8
• Use clear naming and add description with examples.
• Use Google Style Python Docstring.
• Add unit tests to your code.

Introducing new API

API Endpoints:

catalystwan APIs should make requests only through API Endpoints layer. This layer defines:

• http method
• endpoint url
• payload data-model (subtyping pydantic.BaseModel and others)
• return type (subtyping pydantic.BaseModel and others)
• allowed views (session types)
• supported versions

Example:

# to keep example brief we define models and endpoints in single file - however it is suggested to use separate files
from pydantic import BaseModel, Field
from typing import List
from catalystwan.endpoints import APIEndpoints, delete, versions, view
from catalystwan.utils.session_type import ProviderView

class TenantBulkDeleteRequest(BaseModel):
    password: str
    tenant_id_list: List[str] = Field(alias="tenantIdList")

class TenantTaskId(BaseModel):
    id: str

class TenantManagement(APIEndpoints):

    @versions(">=20.4")
    @view({ProviderView})
    @delete("/tenant/bulk/async")
    def delete_tenant_async_bulk(self, payload: TenantBulkDeleteRequest) -> TenantTaskId:
        ...

Please note that when using @request decorator method must have no body. Request will be built automatically and return value based on defined type will be provided.

API endpoints definitions can be found in: catalystwan/endpoints directory.

The organization of items should follow OpenAPI spec: https://developer.cisco.com/docs/sdwan/#!sd-wan-vmanage-v20-9

For example with given tag Configuration - Feature Profile (SDWAN) items should be placed in:

• catalystwan/endpoints/configuration/feature_profile/sdwan/... for APIEndpoints sub-classes
• catalystwan/models/configuration/feature_profile/sdwan/... for pydantic models defining payload, return type and possibly query params.

Auto generated python methods names can be found in: https://ghe-msite.cisco.com/sbasan/openapi-generator-vmanage

Dedicated pre-commit step will automatically check corectness and add documentation for endpoints with @request (or @get, @post, @put, @delete) decorator.

Custom payload types are allowed (eg. for sending various types of files) please check example: SoftwarePackageUploadPayload

1. Check that endpoints you want to utilize in your API already defined in catalystwan/endpoints.
2. If endpoint not present, create new file with endpoint including data-model and methods with @request, @view and @versions decorators when needed.
3. Implement higher level API in catalystwan/api using created endpoints.

Thanks,
catalystwan team