Contribute to the Demisto SDK

Set up your environment, develop and test SDK changes, submit pull requests, and document releases.

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

• Create new commands
• Improve existing implementations
• Fix bugs
• Improve documentation

Demisto SDK contribution prerequisites

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

• An active GitHub account.
• A fork of the demisto-sdk repository.
• The forked repository cloned to your local machine or a GitHub Codespace.
• Python 3 installed. For the supported versions, see pyproject.toml n the repository.
• Poetry installed. If you use Poetry 2.0 or later, also install the poetry-plugin-shell plugin.
• Docker installed.

How to contribute to the Demisto SDK

Before you contribute, you need a local development environment or a GitHub Codespace. After you set up an environment, the development process includes adding or modifying code, adding unit tests, and documenting the changes. When your changes are complete, you can open a pull request to include your changes in the next release of the Demisto SDK.

Set up a Demisto SDK development environment

All commands should be run from the repository root directory.

1. Install all required dependencies.

   poetry install
2. Create a new branch to hold contributed work.

   git checkout -b $BRANCH_NAME
3. Activate the virtual environment.

   poetry shell
4. 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.

Develop Demisto SDK features and bug fixes

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

Demisto SDK project structure

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

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 demisto-sdk -h, run the following command from your virtual environment: python demisto_sdk/__main__.py -h

Each command has its own package under demisto_sdk/commands.

Create a Demisto SDK command

1. Create a package for your command: demisto_sdk/commands/$NEW_COMMAND.
2. Create the click command and arguments in the __main__.py module. For more information, see Basic Concepts - Creating a Command.
3. Create a module in demisto_sdk/commands/$NEW_COMMAND/$NEW_MODULE.py.

   Note

   Modules must return 0 on success or 1 on failure.

Test Demisto SDK changes

There are two types of tests in the Demisto SDK:

• Unit tests: Test individual modules and functions. Place them in the same directory as the code being tested. For example, unit tests for a new command are 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, and expected outputs. For example, the demisto-sdk download command includes flags such as --force and --list-files. Create integration tests for 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 your virtual environment: pytest -v demisto_sdk/commands/$NEW_COMMAND/tests.

To run a specific unit test or integration test, specify the file and test name separated by ::. For example, to run only 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 tests in your IDE. For instructions on setting up pytest test discovery, see Visual Studio Code and PyCharm.

Submit a Demisto SDK pull request

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.

After 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: Verifies that all contributors have signed the Contributor License Agreement (CLA). All contributors must sign the CLA before a pull request can be merged. This agreement ensures that the community is free to use your contributions.

These jobs validate that the pull request meets the project's standards. Review failed jobs and address any issues before requesting a review from the Demisto SDK team. If you have any questions, contact the assigned reviewer.

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

Document Demisto SDK changes

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 to run the sdk-changelog command.

1. Open a second pull request for the changelog entry.
2. 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>

3. 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 compatibility.
      feature	A change that adds a new feature.
      fix	A bug fix.
      internal	A change that adds, modifies, or fixes 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'

4. Validate the YAML file.

   sdk-changelog --validate -n <pr_number>
5. If validation passes, commit the YAML file with your changes.