> 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/how-to-contribute.md). # How to Contribute 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](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the demisto-sdk repository * The forked repository cloned on your local machine or a GitHub Codespace * Python 3 and poetry installed * [Docker](https://docs.docker.com/engine/install/) 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to push the changes into the next release of the Demisto SDK.
Set up the 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.
Add new features or bug fixes 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 1. Create a package for your command in the `demisto_sdk/commands/$NEW_COMMAND` directory. 2. Create the `click` command and arguments in the `__main__.py` module. See [Basic Concepts - Creating a Command](https://click.palletsprojects.com/en/8.1.x/quickstart/#basic-concepts-creating-a-command) for more information. 3. 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](https://code.visualstudio.com/docs/python/testing) and [PyCharm](https://www.jetbrains.com/help/pycharm/pytest.html#create-pytest-test).
Open 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. 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](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 - 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](https://github.com/demisto/demisto-sdk/releases/).
Document your 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 for the command to work. {% endhint %} 1. Open a new pull request. 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 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'
4. Validate the log file. `sdk-changelog --validate -n `
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/demisto-sdk-development-guide/demisto-sdk-guide/contribute-to-demisto-sdk/how-to-contribute.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.