Add docs on rules

docs/configuration/allow_security_updates_on_concurrent_limit.mdx

@@ -24,6 +24,7 @@ title: "allow_security_updates_on_concurrent_limit"
 
 Indicates if you want to allow security updates when the concurrent limit is reached, in addition to your open merge requests.
 
+> **Note:** This option is **root project only** and cannot be used within [rules](/configuration/rules). It modifies the global `number_of_concurrent_updates` behavior.
 
 ## Explanation
 

docs/configuration/allow_updates_beyond_constraint.mdx

@@ -25,6 +25,8 @@ weight:
 
 Indicate whether or not we can try to update a package even if it is beyond the range specified in composer.json. Defaults to 1 (true).
 
+> **Note:** This option can be used within [rules](/configuration/rules) to allow constraint-breaking updates for some package groups while preventing them for others.
+
 ## Explanation
 
 Strictly speaking, if your composer.json specifies that you want to have the package `vendor/package` in the version range `~1.0.0`, then composer will install all version in the range 1.0.x, but refuse to update it to 1.1.0. Some times this is what you want. But many times, a new version at 1.1.0 will include new features and be backwards compatible. So maybe you actually might want to start using that version instead? This is what the option for allowing to update beyond your version constraint does.

docs/configuration/always_update_all.mdx

@@ -25,6 +25,8 @@ weight:
 
 Indicate if you always want violinist to update all packages (simply the command `composer update` with no arguments) every time it runs.
 
+> **Note:** This option is **root project only** and cannot be used within [rules](/configuration/rules). This update strategy is incompatible with package-specific rules since it updates all packages together.
+
 ## Explanation
 
 This is probably most useful if you have not so many dependencies, or if you are replacing a manual workflow that involves running `composer update` on a regular basis. If you are using this option, only one pull request will be created by violinist, and it will contain the updates that would happen if you were running `composer update`. So this option updates all of your dependencies, all of the time.

docs/configuration/assignees.mdx

@@ -27,6 +27,8 @@ weight:
 
 An array of assignees that this project will use as the default assignee for new pull requests.
 
+> **Note:** This option can be used within [rules](/configuration/rules) to assign different package groups to different team members or teams.
+
 >Note! The value of this option depends on your VCS provider. For github this will be an array of usernames. For gitlab the array should consist of user IDs. You can find your user id by visiting [https://gitlab.com/api/v4/users?username=YOUR_USERNAME](https://gitlab.com/api/v4/users?username=YOUR_USERNAME) where YOUR_USERNAME is your gitlab username. (reference: [https://forum.gitlab.com/t/where-is-my-user-id-in-gitlab-com/7912](https://forum.gitlab.com/t/where-is-my-user-id-in-gitlab-com/7912))
 >
 >If you are using self hosted gitlab, change the domain accordingly.

docs/configuration/automerge.mdx

@@ -25,6 +25,8 @@ weight:
 
 Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled.
 
+> **Note:** This option can be used within [rules](/configuration/rules) to enable automerge for specific package groups while keeping it disabled for others.
+
 > Note! This option currently does not work with Bitbucket.
 
 ## Explanation

docs/configuration/automerge_method.mdx

@@ -23,6 +23,8 @@ title: "automerge_method"
 
 Indicates which merge method should be used when using [automerge](/configuration/automerge).
 
+> **Note:** This option can be used within [rules](/configuration/rules) to set different merge methods for different package groups.
+
 > Note! This option currently does not work with Bitbucket.
 
 ## Explanation

docs/configuration/automerge_method_security.mdx

@@ -23,6 +23,8 @@ title: "automerge_method_security"
 
 Indicates which merge method should be used when using [automerge](/configuration/automerge). But in contrast to the [automerge_method](/configuration/automerge_method) option, this will allow you to have a separate method for security updates.
 
+> **Note:** This option can be used within [rules](/configuration/rules) to set different security merge methods for different package groups.
+
 > Note! This option currently does not work with Bitbucket.
 
 ## Explanation

docs/configuration/automerge_security.mdx

@@ -25,6 +25,8 @@ weight:
 
 Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled when the update is a security update.
 
+> **Note:** This option can be used within [rules](/configuration/rules) to enable security automerge for specific package groups.
+
 > Note! This option currently does not work with Bitbucket.
 
 > Note! This option only overrides the automerge option if the update is a security update. If `automerge_security` is set to `0`, but `automerge` is set to `1`, then automerge will be enabled.

docs/configuration/rules/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "rules",
+  "position": 1
+}

docs/configuration/rules/config.md

@@ -0,0 +1,288 @@
+---
+title: "config"
+---
+
+## Configuration
+
+<div className="config-wrapper"><div className="config">__name__: config</div>
+<div className="config">__type__: object</div>
+<div className="config">__required__: no</div></div>
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "rules": [
+        {
+          "name": "Symfony packages",
+          "slug": "symfony-group",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": ["symfony/*"]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "automerge": 1
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+An optional configuration object that overrides the base Violinist configuration for packages matching this rule.
+
+## Explanation
+
+The `config` property allows you to specify different configuration settings for different groups of packages. Any Violinist configuration option can be set here, and it will override the base configuration (or default values) for packages that match the rule.
+
+This is particularly useful for:
+
+- Automerging certain packages but not others
+- Applying different labels or assignees to different package groups
+- Setting different update strategies for different package types
+- Directing updates to different branches based on package importance
+
+## Available Configuration Options
+
+Any configuration option that can be set at the root level can also be set in a rule's config. Some commonly used options include:
+
+### Update Behavior
+- `automerge` - Enable/disable automerge for matching packages
+- `automerge_security` - Enable/disable automerge for security updates
+- `automerge_method` - Set merge method (merge, rebase, squash)
+- `automerge_method_security` - Set merge method for security updates
+- `composer_outdated_flag` - Update level (major, minor, patch)
+- `update_dev_dependencies` - Include/exclude dev dependencies
+- `security_updates_only` - Only update security vulnerabilities
+
+### Pull Request Settings
+- `labels` - Array of labels to add to pull requests
+- `labels_security` - Array of labels for security update pull requests
+- `assignees` - Array of usernames to assign to pull requests
+- `default_branch` - Target branch for pull requests
+- `default_branch_security` - Target branch for security update pull requests
+- `one_pull_request_per_package` - Create separate PRs per package
+
+### Filtering
+- `allow_list` - Explicitly allow specific packages
+- `blocklist` - Block specific packages
+- `check_only_direct_dependencies` - Only check direct dependencies
+
+### Scheduling
+- `timeframe_disallowed` - Time window to avoid creating updates
+- `timezone` - Timezone for scheduling
+
+### Other Options
+- `branch_prefix` - Prefix for created branches
+- `commit_message_convention` - Commit message format
+- `bundled_packages` - Package bundling configuration
+
+For a complete list of all configuration options, see the configuration documentation.
+
+## Examples
+
+### Example 1: Automerge with Labels
+
+Automerge Symfony packages and add specific labels:
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "rules": [
+        {
+          "name": "Symfony packages",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": ["symfony/*"]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "automerge": 1,
+            "labels": ["symfony", "dependencies", "automerge"]
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+### Example 2: Different Branches for Different Packages
+
+Send core package updates to a staging branch:
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "rules": [
+        {
+          "name": "Core Framework Packages",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": ["laravel/framework", "symfony/symfony"]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "default_branch": "staging",
+            "assignees": ["tech-lead"]
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+### Example 3: Patch-only Updates for Production
+
+Only apply patch-level updates to Magento packages and automerge security fixes:
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "rules": [
+        {
+          "name": "Magento Core",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": ["magento/*"]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "composer_outdated_flag": "patch",
+            "automerge_security": 1,
+            "labels": ["magento", "production"]
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+### Example 4: Dev Dependencies Handling
+
+Automerge dev dependencies but not production ones:
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "automerge": 0,
+      "rules": [
+        {
+          "name": "Testing and Development Tools",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": [
+                "phpunit/*",
+                "phpstan/*",
+                "laravel/telescope"
+              ]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "automerge": 1,
+            "labels": ["dev-dependencies"]
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+### Example 5: Security Updates to Separate Branch
+
+Direct all security updates for critical packages to a security branch:
+
+```json showLineNumbers
+{
+  "name": "company/project",
+  "extra": {
+    "violinist": {
+      "rules": [
+        {
+          "name": "Critical Security Packages",
+          "matchRules": [
+            {
+              "type": "names",
+              "values": [
+                "guzzlehttp/*",
+                "symfony/security-*",
+                "firebase/*"
+              ]
+            }
+          ],
+          // highlight-start
+          "config": {
+            "default_branch_security": "security-patches",
+            "automerge_security": 1,
+            "labels_security": ["security", "high-priority"],
+            "assignees": ["security-team"]
+          }
+          // highlight-end
+        }
+      ]
+    }
+  }
+}
+```
+
+## Configuration Merging
+
+When multiple rules match the same package, their configurations are merged. Later rules in the array will override settings from earlier rules if there are conflicts.
+
+For example:
+
+```json showLineNumbers
+{
+  "rules": [
+    {
+      "name": "All Laravel Packages",
+      "matchRules": [{"type": "names", "values": ["laravel/*"]}],
+      "config": {
+        "labels": ["laravel"],
+        "automerge": 0
+      }
+    },
+    {
+      "name": "Laravel Development Packages",
+      "matchRules": [{"type": "names", "values": ["laravel/telescope", "laravel/horizon"]}],
+      "config": {
+        "labels": ["laravel-dev"],
+        "automerge": 1
+      }
+    }
+  ]
+}
+```
+
+In this example, `laravel/telescope` will match both rules. The final configuration will be:
+- `labels`: `["laravel-dev"]` (overridden by second rule)
+- `automerge`: `1` (overridden by second rule)