Contribute to Demisto SDK - Demisto SDK Guide - Cortex

Contributions to the Demisto SDK are welcome. There are multiple ways to contribute:

Create new commands
Improve existing implementation
Fix bugs
Improve documentation

Prerequisites

Before contributing to the Demisto SDK, verify you have the following:

An active GitHub account
A fork of the demisto-sdk repository
The forked repository cloned on your local machine or a GitHub Codespace
Python 3 and poetry installed
Docker installed

How to Contribute

Before you contributing, you need a local development environment or a GitHub Codespace. Once you have an environment, the development process includes adding or modifying code, adding unit tests, and documenting the changes. After your changes are complete, you can open a pull request to push the changes into the next release of the Demisto SDK.

All commands should be run from the repository root directory.

Install all required dependencies.
poetry install
Create a new branch to hold contributed work.
git checkout -b $BRANCH_NAME
Activate the virtual environment.
poetry shell

Check where the new virtual environment is saved in the file system.

poetry env info

The result should display the path, which is helpful when selecting the Python interpreter in Visual Studio Code or PyCharm.

Virtualenv
Python:         3.10.8
Implementation: CPython
Path:           /path/to/pypoetry/virtualenvs/demisto-sdk-zRo7lI35-py3.10
Executable:     /path/to/pypoetry/virtualenvs/demisto-sdk-zRo7lI35-py3.10/bin/python
Valid:          True

You should now have a working development environment. You can use your preferred IDE and open the repository.

Before you begin development, we recommend you first review the following information about the Demisto SDK project structure, important modules, and how to create new commands.

Directory structure

The package that holds the source code for the commands, utilities and unit tests is demisto_sdk.

The main module is located in demisto_sdk/__main__.py and it holds the business logic for initializing the SDK and parsing the commands/arguments. To run the demisto-sdk -h, run the following command from within your virtual environment: python demisto_sdk/__main__.py -h

Each command has its own package under demisto_sdk/commands.

Example of creating a new command

Create a package for your command in the demisto_sdk/commands/$NEW_COMMAND directory.
Create the click command and arguments in the __main__.py module. See Basic Concepts - Creating a Command for more information.
Create a module in demisto_sdk/commands/$NEW_COMMAND/$NEW_MODULE.py.
Note
Modules should return 0 on success or 1 on failure.

Tests

There are two types of tests in the Demisto SDK.

Unit tests - These test individual modules/functions and should be placed in the same directory as the code being tested. For example, unit tests for a new command would be in demisto_sdk/commands/$NEW_COMMAND/tests/$NEW_COMMAND_test.py.
Integration tests - These test the command execution end-to-end and are located in demisto_sdk/tests/integration_tests. They usually include permutations of arguments, inputs, expected outputs, etc. For example, to test the demisto-sdk download command, which includes different flags such as --force and --list-files, we would create integration tests with those variations, demisto_sdk/tests/integration_tests/download_integrations_test.py::test_integration_download_force, demisto_sdk/tests/integration_tests/download_integrations_test.py::test_integration_download_list_files, respectively.

To run unit tests from within your virtual environment: pytest -v demisto_sdk/commands/$NEW_COMMAND/tests.

To run a specific unit test or integration test, you can specify the file and test name separated by ::. For example, if you want to only run the test_integration_download_list_files use: pytest -v demisto_sdk/tests/integration_tests/download_integrations_test.py::test_integration_download_list_files.

You can also run and debug unit tests in your IDE. Follow the instructions on how to set up pytest unit test discovery in Visual Studio Code and PyCharm.

After finishing the development process, push the changes to your SDK fork on GitHub and open a Pull Request from the forked repo to the demisto-sdk master branch.

Once the pull request is open, is is assigned to a member of the Demisto SDK team to review.

In addition, the following GitHub Status Checks run:

ci/circleci - CircleCI is used to run a full build on each commit of your pull request. The build runs our content validation hooks, linting and unit test. We require that the build pass (green build). Follow the details link of the status to see the full build UI of CircleCI.
guardrails/scan - GuardRails is used to review the contributed code and find potential security vulnerabilities.
license/cla - Status check that all contributors have signed our Contributor License Agreement. Before merging any PRs, all contributors must sign a Contributor License Agreement. This agreement ensures that the community is free to use your contributions.

These jobs are run to validate that the pull request meets our standards. Review failed jobs and address any issues found before requesting a review from the Demisto SDK team. If you have any other questions, contact the assigned PR reviewer.

Once the pull request is approved and merged, the changes are available in the next Demisto SDK release.

You cannot edit the CHANGELOG.md file directly. To describe changes made in the pull request, create a YAML file and include a description, type, and pull request number. The pull request must be from master.

Note

poetry must be installed for the command to work.

Open a new pull request.
Run sdk-changelog --init -n <pr_number>.
This command creates a YAML file named after your pull request number, with the following template:
```
changes:
  - description: <str>
    type: <breaking|feature|fix|internal>
pr_number: <int>
```
Edit the YAML file.
1. description - Describe the changes you made in the original pull request.
2. type - Choose one of the following types: breaking, feature, fix, internal.
  Type
  Description
  breaking
  A change that breaks backward compatability.
  feature
  A change that adds a new feature.
  fix
  A bug fix.
  internal
  Adding, changing, or fixing internal components.
Note
If there are multiple changes in the original pull request, you can add documentation with a specific description and type for each change, under the changes key. For example:
```
changes:
- description: Example for description 1.
  type: feature
- description: Example for description 2.
  type: fix
pr_number: '1111'
```
Validate the log file.
sdk-changelog --validate -n <pr number>

Type	Description
breaking	A change that breaks backward compatability.
feature	A change that adds a new feature.
fix	A bug fix.
internal	Adding, changing, or fixing internal components.