demisto-sdk are welcome and appreciated.
Some common ways to contribute are:
- Create new commands.
- Improve existing implementation.
- Fix bugs.
- Improve documentation.
Make sure you already have the following requirements:
- An active GitHub account.
- A fork of the
- The forked repository cloned in your local machine or a codespace.
- Have Python 3 and
- Docker installed.
Before contributing, you must set up a development environment. Once that is ready, the development process can begin. The development process includes adding or modifying code, adding unit tests and documenting the changes. Upon completion, a Pull Request should be opened to push those changes into the next release of the SDK.
Run the following commands from the repository root directory:
- Install all required dependencies:
- Create a new branch to hold contributed work:
- Activate the virtual environment:
- Run the following command to see where the new virtual environment is saved in the filesystem:
You should now have a working development environment. Feel free to jump into your favorite IDE and open the repository.
This is the step where you add new features, fix bugs, etc., commit and push them.
To get you started, here's some useful information about the SDK project structure, important modules and how to create new commands.
The package that holds the source code for the commands, utilities and unit tests is
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. So to run the
demisto-sdk -h, run the following command from within your virtual environment:
Each command has its own package under
To create a new command, follow the steps below:
- Create a package for your command in the
- Create the
clickcommand and arguments in the
__main__.pymodule. See Basic Concepts - Creating a Command for more information.
- Create a module in
demisto_sdk/commands/$NEW_COMMAND/$NEW_MODULE.py. Note: Modules are supposed to return
0on success or
We have two types of tests in the 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 live in
- Integration Tests - These test the command execution end-to-end and are located in
demisto_sdk/tests/integration_tests. They will usually include permutations of arguments, inputs, expected outputs, etc. For example, to test the
demisto-sdk downloadcommand, which includes different flags such as
--list-files, we would create integration tests with those variations,
To run the unit tests from within your virtual environment:
To run a specific unit test or integration test, you can specify the file and test name separated by
::. For example, if we want to only run the
CHANGELOG.md. Under the Unreleased section, add a new bullet with the description of the work done.
Once the Pull Request is open, it will be assigned to a member of the Demisto SDK team to review.
In addition, you will see the following GitHub Status Checks running:
ci/circleci: We use CircleCI to run a full build on each commit of your pull request. The build will run our content validation hooks, linting and unit test. We require that the build pass (green build). Follow the
detailslink of the status to see the full build UI of CircleCI.
- guardrails/scan: We use GuardRails 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, we need all contributors to sign a Contributor License Agreement. By signing this agreement, we ensure that the community is free to use your contributions.
These jobs are run in order to validate that the Pull Request meets our standards. Make sure to review failed jobs and address any issues found before requesting a review from the SDK team. If you have any other questions, feel free to reach out to the assigned PR reviewer!
Once the Pull Request is approved and merged, the changes will be available in the next SDK release.