Checkly Groups Makeover - First Draft of dev docs rewrite (#1264)

* first draft

* Changed formatting

* Minor wording changes

* Wording improvements

* Adjusted wording to be in line with microcopy of app

* fix: add dash to 'round-parallel'

* docs: add group behavior for overridable settings in cli

* feat: add AlertSettings section with configuration details and example usage

* Added CheckGroupsV2 reference

* Refined wording

* Refined wording

* Update site/content/docs/cli/constructs-reference.md

Co-authored-by: María de Antón <[email protected]>

* Update site/content/docs/cli/constructs-reference.md

Co-authored-by: María de Antón <[email protected]>

* Update site/content/docs/cli/constructs-reference.md

Co-authored-by: María de Antón <[email protected]>

* Update site/content/docs/groups/_index.md

Co-authored-by: María de Antón <[email protected]>

* Update site/content/docs/cli/constructs-reference.md

Co-authored-by: María de Antón <[email protected]>

* Updated link and CLI version

* Adjusted warning syntax

---------

Co-authored-by: Paula Mallol <[email protected]>
Co-authored-by: María de Antón <[email protected]>

Author: 3 people

site/content/docs/cli/constructs-reference.md

@@ -382,35 +382,34 @@ TcpAssertionBuilder.responseData().contains('ping')
 "{ source: 'RESPONSE_DATA', regex: '', property: '', comparison: 'CONTAINS', target: 'ping' }"
 ```
 
-## `CheckGroup`
+## `CheckGroupV2`
 
-You can explicitly organize Checks in Check Groups.
-
-This brings the following benefits:
+Use the CheckGroupV2 construct to organize your Checks into groups. This comes with the following benefits:
 
 1. Your Checks are organized in a folder in the Checkly web UI.
 2. You can trigger all Checks in a group from the web UI and via a command line trigger.
 3. You can manage group-level configuration like the runtime, activated & muted-state, tags and alert channels that trickle down to all the Checks in the group.
 
 > [!WARNING]
-> Adding a check to a group means having it _only_ alert through the group's alert channels. Make sure your group has connected alert channels, or you might miss out on important alerts!
+> If you add a check to a group with group-level alert settings ON, the check will only send alerts through the group’s alert channels. Make sure the group has at least one alert channel connected, otherwise you won’t receive any alerts for that check.
 
 > Note: you will notice that managing shared configuration between Checks is very easy just using JS/TS. You might not need Check Groups for that purpose.
 
 #### Adding Checks to a Check Group
 
 You can add a Check to a group in two ways.
 
-1. By passing the `CheckGroup` object for the `group` property of a Check.
+1. By passing the `CheckGroupV2` object for the `group` property of a Check.
 2. For Browser Checks, we allow you to use the `testMatch` glob pattern to include any `.spec.js|ts` file, without having to
    create a `BrowserCheck` construct. This works the same ast the `testMatch` glob at the Project level.
 
 ```ts {title="group.check.ts"}
-import { CheckGroup, ApiCheck, Frequency } from 'checkly/constructs'
+import { CheckGroupV2, ApiCheck, Frequency } from 'checkly/constructs'
 
-const group = new CheckGroup('check-group-1', {
+const group = new CheckGroupV2('check-group-1', {
   name: 'Group',
   activated: true,
+  muted: false,
   frequency: Frequency.EVERY_15M,
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['api-group'],
@@ -431,33 +430,83 @@ new ApiCheck('check-group-api-check-1', {
 })
 ```
 
-- `name`: A friendly name for your Check Group.
+- `name` (required): A friendly name for your Check Group.
+- `activated`: Boolean that determines whether the Checks in the group are running or not. When set to true (default), all activated Checks within the group will run. When set to false, no Checks in the group will run, regardless of whether they are activated or not.
+- `muted`: Boolean that controls alerting behavior for the group. When set to false (default), alerting follows the individual Check’s muted setting. When set to true, no alerts will be sent for any Checks in the group — even if the individual Checks are not muted.
 - `concurrency`: A number indicating the amount of concurrent Checks to run when a group is triggered.
 - `frequency`: How often to run the Checks within the group, i.e. `Frequency.EVERY_15M` for every fifteen minutes.
-- `locations`: An array of location codes where to run the Checks in the group, i.e. `['us-east-1', 'eu-west-1']`.
-- `privateLocations`: An array of [Private Locations](/docs/private-locations/) slugs, i.e. `['datacenter-east-1']`.
-- `alertChannels`: An array of `AlertChannel` objects to which to send alert notifications.
-- `activated`: A boolean value if all the Checks in the group are activated.
-- `muted`: A boolean value if alert notifications from the Checks in the group are muted, i.e. not sent out.
-- `tags`: An array of tags. Group tags trickle down to tags on the individual Checks. i.e. `['product', 'api']`
-- `runtimeId`: The ID of which [runtime](/docs/runtimes/specs/) to use for the Checks in the group.
-- `environmentVariables`: An array of objects defining variables in the group scope, i.e. `[{ key: 'DEBUG', value: 'true', secret: true | locked: true }]`
+- `locations`: An array of one or more [public locations](/docs/monitoring/global-locations) where Checks in this group should run (e.g. `['us-east-1', 'eu-west-1']`). If this or `privateLocations` is set, it overrides the location settings of all Checks in the group.
+- `privateLocations`: An array of one or more [private locations](/docs/private-locations) where Checks in this group should run (e.g. `['datacenter-east-1']`). If this or `locations` is set, it overrides the location settings of all Checks in the group.
+- `alertChannels`: An array of [AlertChannel](#alertchannel) objects to be alerted on when checks in this group fail or recover.
+- `tags`: An array of tags i.e. `['product', 'api']`. Group tags trickle down to tags on the individual Checks.
+- `runtimeId`: The ID of which [runtime](/docs/runtimes/specs/) to use for the Checks in the group. Use this if the checks in this group require a different runtime than your account default.
+- `environmentVariables`: An array of objects defining [environment variables in the group scope](/docs/groups/variables), i.e. `[{ key: 'DEBUG', value: 'true', secret: true | locked: true }]`.
 - `localSetupScript`: Any JS/TS code as a string to run before each API Check in this group.
 - `localTearDownScript`: Any JS/TS code as a string to run after each API Check in this group.
-- `retryStrategy`: A [RetryStrategy](#retrystrategy) object configuring [retries](/docs/alerting-and-retries/) for failed check runs.
-- `apiCheckDefaults`: A set of defaults for API Checks. This should not be needed. Just compose shared defaults using JS/TS.
+- `retryStrategy`: A [RetryStrategy](#retrystrategy) object configuring [retries](/docs/alerting-and-retries/) for failed Check runs. If set, all checks in the group use the group's retry strategy. If not set, individual Check settings are used.
+- `apiCheckDefaults`: A set of [defaults for API Checks](/docs/groups/api-check-defaults/). This should not be needed. Just compose shared defaults using JS/TS.
 - `browserChecks`: A set of defaults for Browser Checks. This should not be needed. Just compose shared defaults using JS/TS.
-- `runParallel`: A boolean value if check should run in parallel (all locations at the same time) or round-robin.
-- `alertEscalationPolicy`:  An [AlertEscalationPolicy](#alertescalationpolicy) object configuring [alert-settings](/docs/alerting-and-retries/) for check runs.
+- `runParallel`: Controls how Checks in the group are executed across locations. When `true`, all Checks run in parallel across all configured locations. When `false`, they run in round-robin mode. If **not set**, each Check uses its own scheduling strategy.
+- `alertEscalationPolicy`: An [AlertEscalationPolicy](#alertescalationpolicy) object defines [alert-settings](/docs/alerting-and-retries/) for Check runs. If **set**, it overrides the alert settings of all checks in the group. If **not set**, each Check uses its own alert configuration.
 
-> When adding checks to a group using `testMatch`, the CLI searches for files using the corresponding [check file](/docs/cli/using-check-test-match/#checkscheckmatch) as a base path.
+> When you use `testMatch` to add Checks to a group, the CLI searches for matching files using the corresponding [Check file](/docs/cli/using-check-test-match/#checkscheckmatch) as a base path.
 
 > Note that you can configure two different `frequency` properties for API and Browser checks in a `CheckGroup` separately.
 > The CLI follows a fallback logic using `Check->CheckGroup->Project` configurations.
 
+## `CheckGroup` (deprecated)
+
+As of CLI release v6.0 the CheckGroup construct is deprecated and will be removed in a future version. We recommend migrating to [CheckGroupV2](#checkgroupv2), which offers more intuitive behavior and better control.
+
+In the deprecated `CheckGroup`, the properties `runParallel`, `locations`, `privateLocations`, `alertEscalationPolicy`, and `retryStrategy` were always treated as overrides. Even when not explicitly set, default values were applied and used to override the Check’s individual settings. With `CheckGroupV2`, no value means no override. If these fields are left undefined, Checks will use their own individual configuration.
+
+Please double-check your group definitions when migrating to make sure your Check behavior stays consistent. For a full overview of what’s changing and what to watch out for, check out our [migration guide](https://feedback.checklyhq.com/changelog/checkly-groups-update-organize-checks-your-way).
+
+## `AlertSettings`
+
+[Alert settings](/docs/alerting-and-retries/alert-settings/#alert-settings) let you to control when and how often you will be notified when a Check starts failing, degrades or recovers.
+
+Here’s what the configuration object looks like:
+
+- `reminders`: Defines how many reminder notifications to send (amount) and the time interval between them in minutes (interval) while an alert is active.
+- `escalationType`: Specifies the escalation strategy. Possible values include `RUN_BASED` (escalate after a number of failed runs) or `TIME_BASED` (escalate after a time threshold).
+- `runBasedEscalation`: Configures run-based escalation. `failedRunThreshold` defines how many failed runs trigger escalation.
+- `timeBasedEscalation`: Configures time-based escalation. `minutesFailingThreshold` defines how long a Check must be failing before escalation.
+- `parallelRunFailureThreshold`: Optional. Enables escalation based on the percentage of parallel runs that fail. Use `enabled` to toggle this, and `percentage` to define the failure threshold.
+
+```ts {title="api.check.ts"}
+import { ApiCheck, RetryStrategyBuilder } from 'checkly/constructs'
+
+new ApiCheck('retrying-check', {
+  name: 'Check With Retries',
+  request: {
+    method: 'GET',
+    url: 'https://danube-web.shop/api/books'
+  }
+  alertSettings: {
+    reminders: {
+      amount: 0,
+      interval: 5
+    },
+    escalationType: "RUN_BASED",
+    runBasedEscalation: {
+      failedRunThreshold: 1
+    },
+    timeBasedEscalation: {
+      minutesFailingThreshold: 5
+    },
+    parallelRunFailureThreshold: {
+      enabled: false,
+      percentage: 10
+    }
+  }
+})
+```
+
 ## `AlertChannel`
 
-Alert channels let you get alert notifications when a Check fails. [Learn more about alerting in our docs](/docs/alerting/)
+Alert channels let you get alert notifications when a Check fails. [Learn more about alerting in our docs](/docs/alerting/).
+
 All alert channels share a set of common properties to define when / how they should alert derived from the abstract class
 `AlertChannel`
 

site/content/docs/groups/_index.md

@@ -13,57 +13,47 @@ aliases:
 
 ---
 
-Groups allow you to organize your checks and centralize settings like base URLs, headers, variables and other properties
-a collection of checks can share. 
+Groups help you organize your checks (e.g. by team or feature) and apply shared configuration such as API defaults, scheduling & location overrides, and other properties.
 
 ![Check group screenshot](/docs/images/groups/group-in-dashboard.png)
 
-Example use cases for groups are organizing your checks around:
+# Creating a check group
 
-- A common URL endpoint
-- A specific team
-- A specific feature in your app
-- A test suite; trigger all checks after a deployment
+By default, newly created check groups behave like folders, with no [group-level configuration](#group-level-configuration) applied. To get started:
 
-> Group-level configurations, such as the runtime, activated & muted state, tags, and alert channels, will override check-level configurations. 
+* **Define a name:** Pick a meaningful name for your group. It helps you and your team identify the group in Checkly and in alerts triggered by failures.
 
-> [!WARNING]
-> Alert settings being controlled at group level means that a check that is part of a group that has no connected alert channels *will not alert*.
-
-## Creating a check group
-
-![Check group editor screenshot](/docs/images/groups/group-editor.png)
+* **Add tags (optional)**: Tags help you relate groups to one another and also determine which checks appear on your [dashboards](/docs/dashboards/).
 
-### Name and tags
-Pick a meaningful name for your group. A meaningful name will not only help you and others identify your group within Checkly, but it will help provide a better alerting experience if checks in this group fall into an alert state. Tags can relate your groups together, they also determine which checks are shown on your [dashboards](/docs/dashboards/).  
+You can populate a group by moving existing checks into it or by creating new checks directly within the group.
 
-### Checks
-Add new or existing checks to this group. If you add an existing check, the group configuration will overwrite certain check configurations, like run locations, retries, and alerting. 
+# Group level configuration
 
-For example, if you create a check that runs in `eu-west-1` but then add it to a group running in `us-east-1`, then the check will run from `us-east-1` only. 
+Groups let you apply shared configuration to standardize how checks behave. Below is a breakdown of each setting and how it affects checks in the group:
 
 ### API checks defaults
-You can set [API check defaults](/docs/groups/api-check-defaults/), including a common base URL, request information, [assertions](/docs/api-checks/assertions/), and [setup & teardown scripts](/docs/api-checks/setup-teardown-scripts/), to help manage API checks.
+You can define [API check defaults](/docs/groups/api-check-defaults/) such as a common base URL, request information, [assertions](/docs/api-checks/assertions/), and [setup & teardown scripts](/docs/api-checks/setup-teardown-scripts/) to manage API checks in your group at scale.
 
 ### Variables
-For configuration information commonly used by checks in this group, create [group environment variables and secrets](/docs/groups/variables/). When checks are scheduled, these will be merged with environment variables at the check and global levels.
+For configuration information commonly used by checks in your group, create [group environment variables and secrets](/docs/groups/variables/). These are merged with variables at the global and check levels when a check runs.
 
-### Scheduling & locations
-Pick from our list of [public](/docs/monitoring/global-locations/) locations or from your [private](/docs/private-locations/) ones. This will override the scheduling strategy (i.e. parallel or round-robin) and location settings for checks in this group. 
+### Scheduling & locations overrides
 
-Checks still run on their own scheduling intervals, but you can specify a default at the group level with the `frequency` property via the [CLI](/docs/cli/constructs-reference/#checkgroup).
+* **Locations:** Select [public](/docs/monitoring/global-locations/) or [private](/docs/private-locations/) locations. This will override the location setting for all checks in your group. For example, if you create a check that runs in `eu-west-1` but add it to a group running in `us-east-1`, the check will run from `us-east-1` only.
 
-### Retries & alerting
+* **Scheduling strategy:** Selecting a [scheduling strategy](/docs/monitoring/global-locations/#scheduling-strategies) will override this setting for all checks in your group. For example, if you create a check that runs in `parallel` but add it to a group running in `round-robin`, the check will run in `round-robin` only.
 
-Select your preferred [retry strategy](/docs/alerting-and-retries/retries/) for failed checks. This will override retry settings for checks in this group.
+* **Frequency:** Each check in your group runs at its own scheduling interval. However, you can specify a default at the group level with the `frequency` property via the [CLI](/docs/cli/constructs-reference/#checkgroup).
 
-You can configure [alert channels](/docs/alerting-and-retries/alert-channels) for checks in this group. If we don’t provide your preferred alert method, use [webhooks](/docs/alerting-and-retries/webhooks/) to configure your alert flow. Like with retries, this will override alert settings for checks in this group.
+### Retries & alerting overrides
+
+* **Retries:** Select your preferred [retry strategy](/docs/alerting-and-retries/retries/) for failed checks. This will override retry settings for all checks in your group. For example, if you create a check that runs with `fixed` retries but add it to a group running with `linear` retries, the check will run with `linear` retries only.
+
+* **Alert settings:** You can configure [alert channels](/docs/alerting-and-retries/alert-channels) for checks in your group. If we don’t provide your preferred alert method, use [webhooks](/docs/alerting-and-retries/webhooks/) to configure your alert flow. Like with retries, this will override alert settings for checks in your group.
 
 > [!WARNING]
 > Make sure to select an alert channel, otherwise checks in this group *will not alert*.
 
-> Note that some alerting channels, like [SMS](/docs/alerting-and-retries/sms-delivery/) and [Phone call](/docs/alerting-and-retries/phone-calls/) are only available on our [Team and Enterprise plans](https://www.checklyhq.com/pricing/#feature-overview)
-
 ### Testing
 
 You can run checks in this group as [E2E tests](/docs/testing) locally or from your CI/CD pipeline to validate your freshly deployed application. Use the Checkly CLI, or configure integrations with Vercel and GitHub.
@@ -72,7 +62,16 @@ You can run checks in this group as [E2E tests](/docs/testing) locally or from y
 
 Checkly manages the [runtime](/docs/runtimes) environment for your JavaScript code in browser checks and setup & teardown scripts. If the checks in this group need a runtime different from your account default, you can set that here.
 
-## How we run grouped checks
+# Adding or removing checks from groups
+
+* **Moving a check into a group:** If the group has [group-level configuration](#group-level-configuration) defined, adding a check may change how it runs. Settings like API defaults, locations & scheduling, or retries & alerting can override or append to the check’s configuration.
+
+* **Removing check from group:** Any [group-level configuration](#group-level-configuration) will no longer apply, and the check will use its own configuration going forward.
+
+> [!WARNING]
+> To prevent issues (e.g. broken references to group variables), the check will be automatically deactivated after being added to or removed from a group. Make sure to review its settings before reactivating.
+
+# How we run grouped checks
 
 It helps to understand how we run the checks in a group, specifically if you're doing more sophisticated checks with shared
 variables, script and alerting channels. Here are the rules: