diff --git a/src/content/docs/configuration/conditions.mdx b/src/content/docs/configuration/conditions.mdx index f695673aed..34cb580325 100644 --- a/src/content/docs/configuration/conditions.mdx +++ b/src/content/docs/configuration/conditions.mdx @@ -158,7 +158,7 @@ requirements that GitHub enforces. This operator checks for matching path using [Unix-style pathname - pattern expansion](/configuration/data-types/#globs). + pattern expansion](/configuration/data-types#globs). If the target attribute type is a list, each element of the list is matched against the value and the condition is true if any value matches. @@ -188,26 +188,26 @@ requirements that GitHub enforces. - Lesser Than or Equal + Less Than or Equal `<=` or `≤` - This operator checks for the value to be lesser then or equal to the + This operator checks for the value to be less than or equal to the provided value. It's usually used to compare against the length of a list using the `#` prefix. - Lesser Than + Less Than `<` - This operator checks for the value to be lesser than the provided value. It's + This operator checks for the value to be less than the provided value. It's usually used to compare against the length of a list using the `#` prefix. @@ -261,8 +261,8 @@ To disambiguate, prefix the check name with `@/`: The qualified form is supported on every `check-*` attribute that takes a check name: `check-success`, `check-success-or-neutral`, `check-failure`, -`check-neutral`, `check-skipped`, `check-timed-out`, `check-pending`, and -`check-stale`. +`check-neutral`, `check-skipped`, `check-cancelled`, `check-timed-out`, +`check-pending`, and `check-stale`. The bare form keeps its original meaning and continues to match a check from any app, so existing configurations do not need to change. Prefer the qualified diff --git a/src/content/docs/configuration/data-types.mdx b/src/content/docs/configuration/data-types.mdx index 62dbdb9417..babdf3f49a 100644 --- a/src/content/docs/configuration/data-types.mdx +++ b/src/content/docs/configuration/data-types.mdx @@ -7,13 +7,12 @@ import OptionsTable from '../../../components/Tables/OptionsTable'; import QueueDequeueReasons from '../../../components/Tables/QueueDequeueReasons'; import TemplateVariablesTable from '../../../components/Tables/TemplateVariablesTable'; -When using templates or conditions, data are made of different types. You will -find below the different data types that are available and exposed in Mergify -configuration file. +When using templates or conditions, data comes in different types. The data +types available in the Mergify configuration file are listed below. ## Commit -A commit is an object that embeds several information about a [Git +A commit is an object that embeds information about a [Git commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) @@ -68,7 +67,7 @@ The `**` wildcard enables recursive globbing. A few examples: You can use regular expressions with matching operators in your [conditions](/configuration/conditions). -Mergify leverages [Python regular expressions](https://docs.python.org/3/library/re.html) +Mergify uses [Python regular expressions](https://docs.python.org/3/library/re.html) to match rules. :::note @@ -98,10 +97,10 @@ pull_request_rules: ## Schedule -This format represents a schedule. It can contains only days, only times or +This format represents a schedule. It can contain only days, only times or both and can have a timezone specified with the times (for the list of -available time zones, see [IANA -format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If no +available time zones, see the [IANA +format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). If no timezone is specified, it defaults to UTC. :::caution @@ -198,7 +197,7 @@ XXXX-XX-31T14:00/XXXX-XX-31T19:00[Europe/Paris] ## Relative Timestamp Timestamps can be expressed relative to the current date and time. The format -is `[DD days] [HH hours] [MM minutes] ago` : +is `[DD days] [HH hours] [MM minutes] ago`: - `DD`, the number of days - `HH`, the number of hours @@ -222,8 +221,8 @@ translated to `updated-at >= 2020-06-04T00:00:00`. ## Duration Duration can be expressed as `quantity unit [quantity unit...]` where quantity -is a number (possibly signed); unit is second, minute, hour, day, week, or -abbreviations or plurals of these units; +is a number (possibly signed) and unit is second, minute, hour, or day +(abbreviations and plurals are accepted). ```text 1 day 15 hours 6 minutes 42 seconds @@ -367,7 +366,7 @@ A GitHub login Mergify impersonates to perform an action. You can also use the :::note Jinja2 is deprecated for fields that support [variable - substitution](#variable-substitution) and stops working on 2026-09-30. + substitution](#variable-substitution). ::: The template data type is a regular string that is rendered using the [Jinja2 @@ -376,7 +375,7 @@ template language](https://jinja.palletsprojects.com/templates/). If you don't need any of the power coming with this templating language, you can just use this as a regular string. -However, those templates allow to use any of the [pull request +However, those templates let you use any of the [pull request attributes](/configuration/conditions#attributes-list) in the final string. For example the template string: @@ -391,7 +390,7 @@ will render to: Thank you @jd for your contribution! ``` -when used in your configuration file — considering the pull request author +when used in your configuration file, considering the pull request author login is `jd`. [Jinja2 @@ -441,7 +440,7 @@ Either `none`, `read`, `triage`, `write`, `maintain` or `admin`. ## Queue Dequeue Reason -This describes the reason why a pull request's merge queue checks ended — either +This describes the reason why a pull request's merge queue checks ended: either because the pull request left the queue, or because its checks were interrupted while it stayed in the queue. @@ -465,12 +464,12 @@ To fill the list, the following report modes are available: check - Report the action's result as a GitHub check on the Pull Request. This is the default report mode. + Report the action's result as a GitHub check on the pull request. This is the default report mode. comment - Report the action's result as a comment on the Pull Request + Report the action's result as a comment on the pull request diff --git a/src/content/docs/configuration/file-format.mdx b/src/content/docs/configuration/file-format.mdx index 9a9783c30a..a7adb1d650 100644 --- a/src/content/docs/configuration/file-format.mdx +++ b/src/content/docs/configuration/file-format.mdx @@ -8,9 +8,8 @@ import { Image } from "astro:assets" import configCheckScreenshot from "../../images/configuration/config-check.png" import OptionsTable from '../../../components/Tables/OptionsTable'; -The Mergify configuration file is an essential component of using our platform -effectively. This document will provide a comprehensive overview of the file, -including its name, format, and the data structure schema. +This page documents the Mergify configuration file: its name, its format, and +the data structure schema. ## Configuration File Name @@ -20,21 +19,19 @@ Mergify applies the following rule to find and use its configuration: `.mergify/config.yml` or `.github/mergify.yml` from the repository root directory. -- It reads the file from the default repository branch configured on GitHub — - usually `main`. +- It reads the file from the default repository branch configured on GitHub + (usually `main`). -- It can extends the configuration by another configuration using the keyword - `extends` — see ["extending the configuration - file"](#extending-configuration-files). +- It can extend the configuration with another configuration file using the + `extends` keyword; see [Extending Configuration + Files](/configuration/sharing#extending-configuration-files). ## File Format -The configuration file uses the [YAML](https://yaml.org/) format, which is both -human-readable and machine-parsable. YAML is easy to read and edit, making it a -popular choice for configuration files. +The configuration file uses the [YAML](https://yaml.org/) format. -The file main type is a dictionary and each key of the dictionary configures a -different aspect of Mergify: +The file's main type is a dictionary and each key of the dictionary configures +a different aspect of Mergify: {/* FIXME: add link to a better page than writing your first rule? */} @@ -48,29 +45,31 @@ different aspect of Mergify: - [`queue_rules`](#queue-rules) configures the [Merge Queue](/merge-queue); -- [`merge_queue`](#merge-queue) configures option for the [Merge +- [`merge_queue`](#merge-queue) configures options for the [Merge Queue](/merge-queue); - [`priority_rules`](#priority-rules) configures the [priorities for the Merge Queue](/merge-queue/priority); +- [`scopes`](/merge-queue/scopes) configures Merge Queue scopes; + - [`commands_restrictions`](/commands/restrictions) configures who is able to run commands; -- [`defaults`](#defaults) allows to configure default options for various +- [`defaults`](#defaults) lets you configure default options for various actions; -- [`shared`](#shared) allows to [define any YAML payload that can be used using +- [`shared`](#shared) lets you [define any YAML payload that can be used using YAML anchors](/configuration/sharing#sharing-configuration-sections); -- [`extends`](#extends) allows to [extend the - configuration](/configuration/sharing#extending-configuration-files) +- [`extends`](#extends) lets you [extend the + configuration](/configuration/sharing#extending-configuration-files) file by importing another configuration file. ### Pull Request Rules -The top-level key `pull_request_rules` allows to automate your workflow by -writing rules that execute actions. It must be a list of dictionary with the +The top-level key `pull_request_rules` lets you automate your workflow by +writing rules that execute actions. It must be a list of dictionaries with the following keys: @@ -91,33 +90,33 @@ pull_request_rules: ### Merge Protections -The top-level key `merge_protections` allows to protect your merge by adding a +The top-level key `merge_protections` lets you protect your merge by adding a list of rules that must match before allowing the pull request to be merged. -The top-level key `merge_protections_settings` allows to configure the -behavior of Merge Protections +The top-level key `merge_protections_settings` lets you configure the +behavior of Merge Protections. ### Merge Queue -The top-level key `merge_queue` allows to configure certain aspect of the merge +The top-level key `merge_queue` lets you configure certain aspects of the [merge queue](/merge-queue). ### Queue Rules -The top-level key `queue_rules` allows to define the rules that reign over your +The top-level key `queue_rules` lets you define the rules that reign over your [merge queue](/merge-queue). ### Priority Rules -The top-level key `priority_rules` allows to define the rules that will determine +The top-level key `priority_rules` lets you define the rules that will determine which [priority](/merge-queue/priority) a pull request has when entering your merge queue. @@ -201,21 +200,17 @@ Configuration Files](/configuration/sharing#extending-configuration-files). ## JSON Schema Specification -For those interested in a more detailed and machine-readable description of the -Mergify configuration file format, a [JSON Schema](https://json-schema.org/) -specification is available. This specification can help you understand the -structure of the configuration file and can be used to generate client -libraries, server stubs, or API documentation. +A machine-readable description of the Mergify configuration file format is +available as a [JSON Schema](https://json-schema.org/) specification. You can +use it to validate configuration files or power editor completion. You can find the JSON Schema specification for the Mergify configuration here. ## Validation and Troubleshooting -When working with Mergify's configuration file, it's essential to validate and -troubleshoot any issues that may arise. Ensuring that your configuration file -is error-free and well-structured can help prevent unexpected behavior and -maintain a smooth workflow. +Mergify validates your configuration on every push. This section covers how to +check your configuration file and track down problems. ### Validation @@ -227,9 +222,7 @@ in the "Checks" tab of your pull request. Mergify configuration check If there are any issues with your configuration file, you will receive a -detailed description of the problem and guidance on how to fix it. Be sure to -address any errors or warnings to ensure optimal performance and avoid -potential issues. +detailed description of the problem and guidance on how to fix it. ### Validate Locally With Pre-Commit @@ -266,10 +259,6 @@ file, consider the following troubleshooting steps: guidance on creating and managing your configuration file, as well as understanding the various features and options available to you. -By following these troubleshooting steps, you can effectively identify and -resolve any issues with your Mergify configuration file, ensuring a smooth and -efficient automation process for your repository. - ## Validating with the CLI The [Mergify CLI](/cli/config) can check your configuration file locally before you diff --git a/src/content/docs/configuration/sharing.mdx b/src/content/docs/configuration/sharing.mdx index fb556ad284..9b1137db35 100644 --- a/src/content/docs/configuration/sharing.mdx +++ b/src/content/docs/configuration/sharing.mdx @@ -3,9 +3,9 @@ title: Sharing Configuration description: Learn how to share and reuse configuration pieces in your configuration. --- -In Mergify, you can leverage certain features like YAML anchors and aliases, -the `shared` key, and the `extends` key to reduce redundancy, maintain -consistency, and increase code reusability. +In Mergify, you can use features like YAML anchors and aliases, +the `shared` key, and the `extends` key to reduce redundancy and keep your +configuration consistent. ## YAML Anchors and Aliases @@ -22,7 +22,7 @@ queue_rules: - and: &CheckRuns - check-success = linters - check-success = unit - - check-success = functionnal + - check-success = functional - check-success = e2e - check-success = docker - name: default @@ -60,7 +60,7 @@ reuse configuration rules across multiple repositories, helping maintain consistency and reduce duplication. To extend a configuration file, use the `extends` keyword at the top level of -your configuration file file and specify the repository name from which you +your configuration file and specify the repository name from which you want to include the configuration. ```yaml @@ -92,12 +92,14 @@ pull_request_rules: - Values in the `shared` key will not be merged and shared between local and remote configurations. - - Values in the `defaults` and `commands_restrictions` key will be merged and remote default - values will apply to local configuration, unless a same default value already exist in the - local configuration. + - Values in the `defaults`, `commands_restrictions`, `merge_queue`, and + `merge_protections_settings` keys will be merged and remote default values + will apply to the local configuration, unless the same value already exists + in the local configuration. - Rules in the `pull_request_rules`, `queue_rules`, `priority_rules` or `merge_protections` section will be merged and remote default values will - apply to local configuration. A rule will not be overwritten, by the - extended configuration, if it has the same name in both the extended and - local configuration. ::: + apply to the local configuration. A rule will not be overwritten by the + extended configuration if it has the same name in both the extended and + local configuration. +:::