Additions for Snowtype 0.7.0 (#956)

* Additions for Snowtype 0.7.0 * Snowtype: Add Data Product Id usage section
snowplow · Jul 11, 2024 · bdbb4e6 · bdbb4e6
1 parent df979ce
commit bdbb4e6
Show file tree

Hide file tree

Showing 8 changed files with 120 additions and 11 deletions.
diff --git a/docs/collecting-data/code-generation/client-side-validation/index.md b/docs/collecting-data/code-generation/client-side-validation/index.md
@@ -13,7 +13,7 @@ Using Snowtype you can get notified, at runtime, about schema validation errors
 To opt-in to client-side validation you should include the `--validations` flag when you are generating your code.
 
 ```sh
-npx snowtype generate --validations
+npx @snowplow/snowtype generate --validations
 ```
 
 For validations to work, you will also need to install `ajv@8`, `ajv-formats@2` and `ajv-draft-04@1`.

diff --git a/docs/collecting-data/code-generation/commands/index.md b/docs/collecting-data/code-generation/commands/index.md
@@ -30,13 +30,15 @@ Generates tracking code based on configuration on the configuration file. Can ge
 **Options**
  -  `-is, --instructions` Generate event specification instructions.
  -  `-va, --validations` Add runtime validation on events. _Currently available for the Browser tracker_.
+ -  `--disallowDevSchemas` Disallow generation of code using schemas deployed on DEV environment. _Sending events using schemas deployed on DEV, will result in failed events in production pipelines._ (default: false)
 
 ### `snowtype update`
 
 Checks for latest version updates in Data Structures and Event Specifications.
 
 **Options**
  -  `-y, --yes` Updates all to latest version without prompting. (default: false)
+ -  `-m, --maximumBump` The maximum SchemaVer update to show an available update notification for. Possible values are 'patch', 'minor', 'major' and will work as expected regular SemVer bumps. (default: 'major')
 
 ### `snowtype patch`
 

diff --git a/docs/collecting-data/code-generation/getting-started/index.md b/docs/collecting-data/code-generation/getting-started/index.md
@@ -3,17 +3,80 @@ title: "Getting started with the Snowtype CLI"
 sidebar_position: 1
 ---
 
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
 ## Introduction to the Snowtype CLI
 
 Snowtype is a command-line interface that assists developers in implementing custom Snowplow tracking faster, more accurately and more intuitively. Since Snowplow events are always bound to a schema to ensure data quality, we can use this feature to enable type-checking, provide inline documentation and reduce time writing custom code. All that integrated into **your development workflow**.
 
+## Prerequsites
+
+To use Snowtype, you must have [Node.js](https://nodejs.org/en/) (>=@18) installed.
+
 ## Installation
 
-The Snowtype CLI is distributed through `npm` and soon `brew`. You can choose either one depending on your needs. 
+Navigate to your project and install Snowtype using your favorite package manager:
+
+<Tabs groupId="package-manager">
+  <TabItem value="npm" label="npm" default>
+
+```bash
+npm install --save-dev @snowplow/snowtype
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add --dev @snowplow/snowtype
+```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add --save-dev @snowplow/snowtype 
+```
+
+  </TabItem>
+</Tabs>
+
+## Executing commands
+
+Installing Snowtype will also create a local executable `snowtype` which you can use with `npx`, `yarn` or `pnpm` directly when on your project's directory.
+
+<Tabs groupId="example-commands">
+  <TabItem value="npm" label="npm" default>
+
+```bash
+npx @snowplow/snowtype init
+# Same as
+npx snowtype init
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn @snowplow/snowtype init
+# Same as
+yarn snowtype init
+```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
 
-```sh
-npm install @snowplow/snowtype --save-dev
+```bash
+pnpm @snowplow/snowtype init
+# Same as
+pnpm snowtype init 
 ```
 
-_We will show example commands using `npm` but it should work the same with either system._
+  </TabItem>
+</Tabs>
+
+_We will show example commands using `npm/npx` but it should work the same with any other package manager._
 
diff --git a/docs/collecting-data/code-generation/using-the-cli/images/dp-id.png b/docs/collecting-data/code-generation/using-the-cli/images/dp-id.png
diff --git a/docs/collecting-data/code-generation/using-the-cli/images/dp-track.png b/docs/collecting-data/code-generation/using-the-cli/images/dp-track.png
diff --git a/docs/collecting-data/code-generation/using-the-cli/images/es-id.png b/docs/collecting-data/code-generation/using-the-cli/images/es-id.png
diff --git a/docs/collecting-data/code-generation/using-the-cli/images/ts-id.png b/docs/collecting-data/code-generation/using-the-cli/images/ts-id.png
diff --git a/docs/collecting-data/code-generation/using-the-cli/index.md b/docs/collecting-data/code-generation/using-the-cli/index.md
@@ -37,7 +37,7 @@ From there, the ways for the CLI to recognize the key are either through the glo
   <TabItem value="cli" label="CLI parameter" default>
 
   ```bash
-  npx snowtype generate --apiKey MY-API-KEY
+  npx @snowplow/snowtype generate --apiKey MY-API-KEY
   ```
 
   </TabItem>
@@ -51,7 +51,7 @@ For the Snowtype CLI to work properly, it requires a [configuration file](../sno
 
 ```bash
 # Start prompting for configuration inputs
-npx snowtype init
+npx @snowplow/snowtype init
 ```
 
 The input required for the initialization to work, it the following:
@@ -70,7 +70,7 @@ The CLI will generate tracking code using a valid Snowtype configuration file wi
 
 ```bash
 # Code will be generated to the outpath configuration
-npx snowtype generate
+npx @snowplow/snowtype generate
 ```
 
 The code generated by the CLI is not minified and contains inline documentation for methods, classes and types. If needed you can modify it in any way it suits your project.
@@ -288,11 +288,21 @@ trackWebPage<Product | WebPage>(t, {
 
 </Tabs>
 
+### Data Products
+
+To generate code for the whole set of Event Specifications of a Data Product, either manually or through the `snowtype patch` command, you will need the ID of the Data Product. You can do this either by clicking on the `Implement tracking` button on the Data Products main page to get the command directly:
+
+![data product track](images/dp-track.png)
+
+Or retrieve the ID from the URL bar and then add it on the `dataProductIds` array:
+
+![data product id](images/dp-id.png)
+
 ### Event Specifications
 
-To add an Event Specification to the code generation, either manually or through the `snowtype patch` command, you would need the ID of the event specification. You can find the Event Specification ID in the main page of the event specification as shown below:
+To add an Event Specification to the code generation, either manually or through the `snowtype patch` command, you would need the ID of the Event Specification. You can find the Event Specification ID in the main page of the Event Specification as shown below:
 
-![event specification id](images/ts-id.png)
+![event specification id](images/es-id.png)
 
 Then you should add this ID to your configuration file `eventSpecificationIds` array.
 
@@ -331,11 +341,45 @@ It is important that the tracking code is up-to-date with latest versions of Dat
 This works with the `snowtype update` command.
 
 ```bash
-npx snowtype update
+npx @snowplow/snowtype update
 ```
 
 The above command will output a _diff_ showing the available version updates, similar to what you can see below:
 
 ![patch command version diff](images/patch-diff.png)
 
 In that case, you can select to update to latest versions and regenerate the tracking code. To automatically update and regenerate the tracking code reflecting the latest updates, you can use the `--yes` flag.
+
+### Adjust the level of update notifications
+
+For possible Data Structure updates, you can set the maximum level of update you want to be notified about using the `--maximumBump` flag. This value provides the maximum bump to be notified about and update to if available. This value defaults to 'major' meaning the update command will notify you for all updates up to and including major type of updates to the schema model.
+
+An example showcasing the flag's behavior: 
+
+```js
+// Data Structure version added to the snowtype config is 1-0-0.
+{
+  // Other options...
+  dataStructures: ["iglu:com.acme_company/page_unload/jsonschema/1-0-0"]
+}
+```
+
+This Data Structure has other deployed versions such as `1-0-1`, `1-1-0` and `2-0-0`. The `update` command will show available updates as follows:
+
+```sh
+npx @snowplow/snowtype update --maximumBump=major
+# Will prompt an update to 2-0-0 or any other available update.
+
+npx @snowplow/snowtype update --maximumBump=minor
+# Will prompt an update to 1-1-0 or 1-0-1 if the only available update.
+
+npx @snowplow/snowtype update --maximumBump=patch
+# Will prompt an update to 1-0-1 if available or any other patch type update.
+```
+
+## Disallow generating code using schemas not deployed on production environment.
+
+While developing or testing, it might be useful to use [Snowplow Mini](../../../pipeline-components-and-applications/snowplow-mini/) to validate against your new schemas in your development environment.
+In this and any other case you are developing a schema and eventually publishing the tracking to production, you need to make sure all the schemas you are using are deployed to the production environment for the pipeline to use. Failing to do that will result in failed events.
+
+Snowtype by default will print a warning when code is generated using schemas only published to development environment. To make sure that there are no schemas not yet deployed to production, you can use the `--disallowDevSchemas` flag when using the `generate` command. Using this flag will make sure each generation attempt will fail, indicating the schemas that are not yet deployed to the production environment.