> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/demisto-sdk-development-guide/demisto-sdk-guide/contribute-to-demisto-sdk.md). # 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](https://docs.github.com/en/get-started/quickstart/fork-a-repo) 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](https://docs.docker.com/engine/install/) 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) 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. ```programlisting 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](https://click.palletsprojects.com/en/8.1.x/quickstart/#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](https://code.visualstudio.com/docs/python/testing) and [PyCharm](https://www.jetbrains.com/help/pycharm/pytest.html#create-pytest-test).
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](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) 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](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-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](https://www.guardrails.io/) 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](https://github.com/demisto/demisto-sdk/releases/).
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`. {% hint style="info" %} ### Note Poetry must be installed to run the `sdk-changelog` command. {% endhint %} 1. Open a second pull request for the changelog entry. 2. Run `sdk-changelog --init -n `. This command creates a YAML file named after your pull request number, with the following template: ```programlisting changes: - description: type: pr_number: ``` 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 ` 5. If validation passes, commit the YAML file with your changes.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://cortex-docs.paloaltonetworks.com/demisto-sdk-development-guide/demisto-sdk-guide/contribute-to-demisto-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.