Skip to content

Commit

Permalink
add allowed values
Browse files Browse the repository at this point in the history
  • Loading branch information
@shmuel44
shmuel44 committed Feb 29, 2024
1 parent 5cff6f1 commit a338e06
Showing 1 changed file with 40 additions and 27 deletions.
67 changes: 40 additions & 27 deletions docs/packs/packs-format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,18 @@ title: Content Packs Structure

For better separation between Content artifacts from different use cases and Partners we use a directory structure called `Content Packs`. Each `Content Pack` behaves like a mini content repo. It contains all relevant content items within its directory.

For instance a pack for CortexXDR will look as can be seen in the Content Repository
For instance a pack for CortexXDR will look as can be seen in the Content Repository
[Packs/CortexXDR](https://github.com/demisto/content/tree/master/Packs/CortexXDR).

To generate a new pack make sure to use: `demisto-sdk init --pack`. Detailed command instructions are available [here](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/init/README.md).

**Note**: The Content repo is going through a transition phase to move all content into packs. During this phase you will see some Content artifacts are still not maintained within Packs. All new Content should be maintained via Packs.

## Directories

All the directories within the pack are the representation of all the possible entities possible in Content. And the pack will be located in the Content repo under `Packs/<Pack Name>`
```

```text
- Integrations
- Scripts
- Playbooks
Expand All @@ -31,12 +33,14 @@ All the directories within the pack are the representation of all the possible e
```

## Pack files
The pack directory contains numerous configuration files used for metadata and documentation.

Please note that all of the following files will be created using the `demisto-sdk init --pack`, and some of them
The pack directory contains numerous configuration files used for metadata and documentation.

Please note that all of the following files will be created using the `demisto-sdk init --pack`, and some of them
will have to be filled by you. An explanation for each of them will be provided below.

### pack_metadata.json

This file contains all the relevant metadata about the pack.

The following fields are populated in the pack metadata:
Expand All @@ -62,9 +66,8 @@ The following fields are populated in the pack metadata:
| displayedImages | List | (Optional) Images to be displayed in Cortex XSOAR marketplace. Should be kept empty on pack creation, as it is calculated by Cortex XSOAR content infrastructure. |
| githubUser | List | (Optional) List of Github usernames to receive notification in the PR in case pack files were modified. |
| devEmail | List | (Optional) List of emails to receive notification in case contributed pack files were modified. |
| certification | String | (Optional) If the pack is certifed the value of this fields should be "certified" |
| itemPrefix | String | (Optional) String to overwrite pack fields prefix. You can specify an alternative string instead of the default pack name enforced by the validation process.

| certification | String | (Optional) If the pack is certified the value of this fields should be "certified". The allowed values are either "certified" or "verified". |
| itemPrefix | String | (Optional) String to overwrite pack fields prefix. You can specify an alternative string instead of the default pack name enforced by the validation process. |

Pack metadata contents for example:

Expand Down Expand Up @@ -110,6 +113,7 @@ Pack metadata contents for example:
```

A supported partner pack metadata contents for example:

```json
{
"name": "Product name",
Expand All @@ -134,47 +138,53 @@ A supported partner pack metadata contents for example:
}
```


### Content Packs Versioning

Pack versions have the following format MAJOR.MINOR.REVISION:

1. **Revision** when you make backwards compatible bug fixes.
2. **Minor** when you add functionality in a backwards compatible manner.
3. **Major** when you make incompatible API changes or revamping the pack by adding to it a lot of new backwards compatible functionality.


### README.md

The file contains a general explanation for the pack and you are free to add any information relevant for the pack. For more details refer to the [Pack Documentation](../documentation/pack-docs) page.

### .secrets-ignore

This file will be used while running the `demisto-sdk secrets`([explanation](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/secrets/README.md)), we will determine the file and will
use it as an allow list of approved words for your PR.

**Note**: We use `demisto-sdk secrets` as part of our pre-commit hook to check that possible secrets in the PR aren't exposed to a public repository.

### .pack-ignore

1) This file allows ignoring linter errors while lint checking and ignoring tests in the test collection.

To add ignored tests/linter errors in a file, first, add the file name to the **.pack-ignore** in this format
```
[file:integration-to-ignore.yml]
```

On the following line add `ignore=` flag, with one or more comma-separated values:
* `auto-test` - ignore test file in the build test collection.
* `linter code` e.g., IN126 - ignore linter error codes.
```text
[file:integration-to-ignore.yml]
```
On the following line add `ignore=` flag, with one or more comma-separated values:
* `auto-test` - ignore test file in the build test collection.
* `linter code` e.g., IN126 - ignore linter error codes.
2) By default, unit-tests of scripts/integrations are running without a docker network.
In case one of the integrations/scripts inside a pack needs a network during the unit-tests run, this can be done in this format
```
[tests_require_network]
integration-id-1
script-id-1
```
```text
[tests_require_network]
integration-id-1
script-id-1
```
#### Example .pack-ignore
```
```text
[file:playbook-Special-Test-Not-To-Run-Directly.yml]
ignore=auto-test
Expand All @@ -187,6 +197,7 @@ script-id-1
```

### Author_image.png

It's possible to add an author image - a logo of the contributing company, which will be displayed on the marketplace page of the pack, under the "PUBLISHER" section.
The image should be saved in the root directory of the pack (e.g., `content/packs/MyPackName`), be named `Author_image.png`, and have a size of up to 4 KB, at a resolution of 120x50.

Expand All @@ -198,24 +209,26 @@ If the file is missing, the build will fail with the following validation error:
- Issues with unique files in pack: $PACK_NAME
Packs/$PACK_NAME/Author_image.png: [IM109] - Partners must provide a non-empty author image under the path Packs/$PACK_NAME/Author_image.png
```

:::

:::note
If the `Author_image.png` file does not exist, the name of the author will be displayed under the "PUBLISHER" section instead.
:::

### CONTRIBUTORS.json
If you are contributing to an existing pack, you can add a **CONTRIBUTORS.json** file to the root of the pack in the event that one does not already exist. The file should contain a list of strings including your name.

#### Example of a CONTRIBUTORS.json file:
If you are contributing to an existing pack, you can add a **CONTRIBUTORS.json** file to the root of the pack in the event that one does not already exist. The file should contain a list of strings including your name.

#### Example of a CONTRIBUTORS.json file

```json
[
"Jane Doe",
"John Smith"
]
```

#### Once your contribution is merged, pack details will show the following:
#### Once your contribution is merged, pack details will show the following

![image](https://user-images.githubusercontent.com/44666568/176713193-8a0857bf-a5ed-45cd-98e4-3c575752c0ff.png)

0 comments on commit a338e06

Please sign in to comment.