Skip to content

Commit

Permalink
Update Changelog Instructions/GitHub Actions (#1519)
Browse files Browse the repository at this point in the history 
* update changelog instructions

update pr checks to gh

* Update sdk.md

---------

Co-authored-by: Tamar Schanfeld <[email protected]>
  • Loading branch information
@kgal-pan @tschanfeld
kgal-pan and tschanfeld authored Mar 25, 2024
1 parent c404bd6 commit 310055b
Showing 1 changed file with 37 additions and 24 deletions.
61 changes: 37 additions & 24 deletions docs/contributing/sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,19 +19,19 @@ Some common ways to contribute are:

### Prerequesites

Make sure you already have the following requirements:
Verify you have the following requirements:

* An active GitHub account.
* A [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the [`demisto-sdk`](https://github.com/demisto/demisto-sdk) repository.
* The forked repository cloned in your local machine or a codespace.
* Have Python 3 and [`poetry`](https://python-poetry.org/docs/#installation) installed.
* Python 3 and [`poetry`](https://python-poetry.org/docs/#installation) installed.
* [Docker](https://docs.docker.com/engine/install/) installed.

## How to Contribute

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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) should be opened to push those changes into the next release of the SDK.
Before contributing, you must set up a development environment. The development process includes adding or modifying code, adding unit tests and documenting the changes. Upon completion, 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) should be opened to push your changes into the next release of the Demisto SDK.

### 1. Set Up Development Environment
### 1. Set Up a Development Environment

Run the following commands from the repository root directory:

Expand Down Expand Up @@ -66,15 +66,16 @@ Executable: /path/to/pypoetry/virtualenvs/demisto-sdk-zRo7lI35-py3.10/bin/py
Valid: True
```

This output will be helpful when selecting the Python interpreter in [Visual Studio Code](https://code.visualstudio.com/docs/python/environments) and [PyCharm](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html#add-existing-interpreter).
This output will be useful when selecting the Python interpreter in [Visual Studio Code](https://code.visualstudio.com/docs/python/environments) and [PyCharm](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html#add-existing-interpreter).

You should now have a working development environment. Feel free to jump into your favorite IDE and open the repository.
You should now have a working development environment. Open your IDE and then open the repository.

### 2. Add Work
### 2. Add Your Proposed Changes

This is the step where you add new features, fix bugs, etc., commit and push them.
Add new features, fix bugs, etc., commit and push them.

To get you started, here's some useful information about the Demisto SDK project structure, important modules and how to create new commands.

To get you started, here's some useful information about the 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`.
Expand All @@ -94,46 +95,58 @@ To create a new command, follow the steps below:
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 are supposed to return `0` on success or `1` on failure.
**Note:** Modules should return `0` on success or `1` on failure.


#### Tests

We have two types of tests in the SDK:
There are 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 `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 will 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.
* **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 should 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`, 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 the unit tests from within your virtual environment:

```bash
❯ 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 we want to only run the `test_integration_download_list_files` test:
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` test:
```bash
❯ 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 the 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).
You can also run and debug unit tests in the IDE. Follow the instructions 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).

### 3. 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`](https://github.com/demisto/demisto-sdk) `master` branch.

After opening the pull request, run the following command to generate a changelog entry:

```bash
poetry run sdk-changelog --init
```

### 3. Add Release Notes
This will create a YML in the `.changelog` directory with the PR number (e.g. `.changelog/123.yml`). Open the file with a text editor and fill out the `changes.description` and `changes.type` fields.

Open `CHANGELOG.md`. Under the **Unreleased** section, add a new bullet with the description of the work done.
The possible values for `changes.type` are:

### 4. Open Pull Request
* `breaking`
* `feature`
* `fix`
* `internal`

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`](https://github.com/demisto/demisto-sdk) `master` branch.
### 4. Pull Request Review

Once the Pull Request is open, it will be assigned to a member of the Demisto SDK team to review.
Once the pull request is open, it is assigned to a member of the Demisto SDK team to review.

In addition, you will see the following [GitHub Status Checks](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) running:

* `ci/circleci` : We use [CircleCI](https://circleci.com/gh/demisto/demisto-sdk) 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 `details` link of the status to see the full build UI of CircleCI.
* **CI - On Push** : We use GitHub Actions to run a full build on each commit of your pull request. The build runs our validation hooks, linting and unit tests. We require that the build pass (green build). Follow the *details* link of the check to see the full log.
* **guardrails/scan**: We use [GuardRails](https://www.guardrails.io/) 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.
* **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. By signing this agreement, you enable the community 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!
These jobs are run in order to validate that the pull request meets our standards. Review failed jobs and address any issues found before requesting a review from the SDK team. If you have any questions, 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](https://github.com/demisto/demisto-sdk/releases/).
Once the pull request is approved and merged, the changes are available in the next [SDK release](https://github.com/demisto/demisto-sdk/releases/).

0 comments on commit 310055b

Please sign in to comment.