diff --git a/docs/configuration/allow_security_updates_on_concurrent_limit.mdx b/docs/configuration/allow_security_updates_on_concurrent_limit.mdx index 629babe..5efde27 100755 --- a/docs/configuration/allow_security_updates_on_concurrent_limit.mdx +++ b/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 diff --git a/docs/configuration/allow_updates_beyond_constraint.mdx b/docs/configuration/allow_updates_beyond_constraint.mdx index 167b4ed..88e4961 100755 --- a/docs/configuration/allow_updates_beyond_constraint.mdx +++ b/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. diff --git a/docs/configuration/always_update_all.mdx b/docs/configuration/always_update_all.mdx index 44df10d..57c9b0e 100755 --- a/docs/configuration/always_update_all.mdx +++ b/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. diff --git a/docs/configuration/assignees.mdx b/docs/configuration/assignees.mdx index 4d51127..ea653e2 100755 --- a/docs/configuration/assignees.mdx +++ b/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. diff --git a/docs/configuration/automerge.mdx b/docs/configuration/automerge.mdx index aa14006..bd61481 100755 --- a/docs/configuration/automerge.mdx +++ b/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 diff --git a/docs/configuration/automerge_method.mdx b/docs/configuration/automerge_method.mdx index 0a94cf1..8baf441 100755 --- a/docs/configuration/automerge_method.mdx +++ b/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 diff --git a/docs/configuration/automerge_method_security.mdx b/docs/configuration/automerge_method_security.mdx index fb3e918..8d98e37 100755 --- a/docs/configuration/automerge_method_security.mdx +++ b/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 diff --git a/docs/configuration/automerge_security.mdx b/docs/configuration/automerge_security.mdx index 5064dee..80f499d 100755 --- a/docs/configuration/automerge_security.mdx +++ b/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. diff --git a/docs/configuration/rules.mdx b/docs/configuration/rules.mdx new file mode 100644 index 0000000..a8b7b05 --- /dev/null +++ b/docs/configuration/rules.mdx @@ -0,0 +1,345 @@ +--- +title: "rules" +date: 2025-01-28T12:00:00+01:00 +anchor: "rules" +weight: +--- + +## Configuration + +
__name__: rules
+
__type__: array
+
__default__: []
+ +```json showLineNumbers +{ + "name": "company/project", + "extra": { + "violinist": { +// highlight-next-line + "rules": [] + } + } +} +``` + +Define package-specific configuration rules that override the default settings. + +> This option is currently in **beta**. This means its options are considered stable (no backwards incompatible changes will be added), but that there are some stability and usability improvements expected. + +## Explanation + +The `rules` option allows you to apply different configuration settings to different groups of packages. This is useful when you want to handle certain packages differently from your default configuration. For example, you might want to apply security-only updates to development tools while allowing all updates for production dependencies. + +Rules are evaluated in order, and when a package matches a rule, the configuration from that rule is merged with your default configuration. + +### Comparison with bundled_packages + +If you want to group packages together in a more flexible pattern than using [bundled_packages](/configuration/bundled_packages), then `rules` is for you. The main differences are: + +- [bundled_packages](/configuration/bundled_packages) will only update its bundled packages if the "parent" package has an update, while rules can update the group if any of the packages has an update. +- Rules make it possible to have different configurations per group. For example, you can automerge one group but not others. +- Rules support pattern matching with wildcards and negation, making them much more flexible. + +## Structure + +Rules is an array of rule objects. Each rule object has the following structure: + +```json showLineNumbers +{ + "rules": [ + { + "name": "Human readable name", + "slug": "machine-readable-slug", + "matchRules": [ + { + "type": "names", + "values": ["vendor/*", "!vendor/excluded-package"] + } + ], + "config": { + "blocklist": [], + "branch_prefix": "deps/", + "security_updates_only": 1 + } + } + ] +} +``` + +### Rule Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | A human-readable name for the rule (for documentation purposes) | +| `slug` | string | A machine-readable identifier for the rule | +| `matchRules` | array | An array of match rule objects that determine which packages this rule applies to | +| `config` | object | Configuration options to apply when a package matches | + +## Match Rules + +Match rules determine which packages a rule applies to. Each match rule has a `type` and associated properties. + +### Type: `names` + +Match packages by name using [fnmatch](https://www.php.net/manual/en/function.fnmatch.php) patterns. + +| Pattern | Description | +|---------|-------------| +| `vendor/*` | Match all packages from a vendor | +| `vendor/package` | Match a specific package | +| `vendor/prefix-*` | Match packages with a specific prefix | +| `!vendor/package` | Exclude a specific package (negative match) | + +When using negative matches (`!`), the package is excluded from the rule even if it matches a positive pattern. This allows you to select a broad group of packages and then exclude specific ones. + +```json showLineNumbers +{ + "matchRules": [ + { + "type": "names", + "values": [ + "drupal/*", + "!drupal/core-recommended", + "!drupal/core-composer-scaffold" + ] + } + ] +} +``` + +This example matches all `drupal/*` packages except `drupal/core-recommended` and `drupal/core-composer-scaffold`. + +## Config Overrides + +Within a rule's `config` object, you can override most configuration options. The configuration from matching rules is merged with your default configuration. + +### Overridable Options + +The following options can be used within rules: + +- [allow_list](/configuration/allow_list) +- [allow_update_indirect_with_direct](/configuration/allow_update_indirect_with_direct) +- [allow_updates_beyond_constraint](/configuration/allow_updates_beyond_constraint) +- [always_allow_direct_dependencies](/configuration/always_allow_direct_dependencies) +- [always_update_all](/configuration/always_update_all) +- [assignees](/configuration/assignees) +- [automerge](/configuration/automerge) +- [automerge_method](/configuration/automerge_method) +- [automerge_method_security](/configuration/automerge_method_security) +- [automerge_security](/configuration/automerge_security) +- [blocklist](/configuration/blocklist) +- [branch_prefix](/configuration/branch_prefix) +- [bundled_packages](/configuration/bundled_packages) +- [check_only_direct_dependencies](/configuration/check_only_direct_dependencies) +- [commit_message_convention](/configuration/commit_message_convention) +- [composer_outdated_flag](/configuration/composer_outdated_flag) +- [default_branch](/configuration/default_branch) +- [default_branch_security](/configuration/default_branch_security) +- [ignore_platform_requirements](/configuration/ignore_platform_requirements) +- [labels](/configuration/labels) +- [labels_security](/configuration/labels_security) +- [one_pull_request_per_package](/configuration/one_pull_request_per_package) +- [run_scripts](/configuration/run_scripts) +- [security_updates_only](/configuration/security_updates_only) +- [update_dev_dependencies](/configuration/update_dev_dependencies) +- [update_with_dependencies](/configuration/update_with_dependencies) + +### Root-level Only Options + +The following options cannot be overridden in rules and only apply at the root configuration level: + +- [number_of_concurrent_updates](/configuration/number_of_concurrent_updates) +- [allow_security_updates_on_concurrent_limit](/configuration/allow_security_updates_on_concurrent_limit) +- [timeframe_disallowed](/configuration/timeframe_disallowed) +- [timezone](/configuration/timezone) + +## Examples + +### Security-only updates for dev dependencies + +Only receive security updates for development tools while allowing all updates for production dependencies: + +```json showLineNumbers +{ + "name": "company/project", + "extra": { + "violinist": { +// highlight-start + "rules": [ + { + "name": "Dev tools - security only", + "slug": "dev-tools-security", + "matchRules": [ + { + "type": "names", + "values": ["phpunit/*", "phpstan/*", "squizlabs/*", "friendsofphp/*"] + } + ], + "config": { + "security_updates_only": 1 + } + } + ] +// highlight-end + } + } +} +``` + +### Bundling Drupal Core packages + +Bundle all Drupal core packages together so they update in a single pull request: + +```json showLineNumbers +{ + "name": "company/drupal-project", + "extra": { + "violinist": { +// highlight-start + "rules": [ + { + "name": "Drupal Core packages", + "slug": "drupal-core", + "matchRules": [ + { + "type": "names", + "values": ["drupal/core-recommended"] + } + ], + "config": { + "bundled_packages": { + "drupal/core-recommended": [ + "drupal/core-composer-scaffold", + "drupal/core-project-message" + ] + } + } + } + ], + "blocklist": [ + "drupal/core-composer-scaffold", + "drupal/core-project-message" + ] +// highlight-end + } + } +} +``` + +### Custom branch prefixes per package group + +Use different branch prefixes for different types of dependencies: + +```json showLineNumbers +{ + "name": "company/project", + "extra": { + "violinist": { +// highlight-start + "rules": [ + { + "name": "Framework updates", + "slug": "framework", + "matchRules": [ + { + "type": "names", + "values": ["symfony/*", "laravel/*"] + } + ], + "config": { + "branch_prefix": "deps/framework/" + } + }, + { + "name": "Testing tools", + "slug": "testing", + "matchRules": [ + { + "type": "names", + "values": ["phpunit/*", "mockery/*", "fakerphp/*"] + } + ], + "config": { + "branch_prefix": "deps/testing/" + } + } + ] +// highlight-end + } + } +} +``` + +### Disable dev dependency updates for Drupal contrib + +Update dev dependencies by default but disable them for Drupal contrib modules: + +```json showLineNumbers +{ + "name": "company/drupal-project", + "extra": { + "violinist": { + "update_dev_dependencies": 1, +// highlight-start + "rules": [ + { + "name": "Drupal Contrib", + "slug": "drupal-contrib", + "matchRules": [ + { + "type": "names", + "values": [ + "drupal/*", + "!drupal/core-*" + ] + } + ], + "config": { + "update_dev_dependencies": 0 + } + } + ] +// highlight-end + } + } +} +``` + +### Automerge minor updates for specific packages + +Automatically merge minor updates for well-tested packages while requiring manual review for others: + +```json showLineNumbers +{ + "name": "company/project", + "extra": { + "violinist": { +// highlight-start + "rules": [ + { + "name": "Trusted packages - automerge", + "slug": "trusted-automerge", + "matchRules": [ + { + "type": "names", + "values": ["psr/*", "symfony/polyfill-*"] + } + ], + "config": { + "automerge": 1, + "composer_outdated_flag": "minor" + } + } + ] +// highlight-end + } + } +} +``` + +## Rule Precedence + +When a package matches multiple rules, the configurations are merged in order. Later rules can override settings from earlier rules. If you have overlapping patterns, place more specific rules after more general ones. + +> **Note:** Root-level configuration is always applied first, then rules are evaluated and merged in the order they appear.