From c21873baedbf4049f474635be5bf262cc457fdfb Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Mon, 29 Jan 2024 15:51:10 -0500 Subject: [PATCH 1/3] docs: recommend messageId over message for reporting rule violations --- docs/src/extend/custom-rules.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 6c045afb3f5..a37a1102625 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -145,7 +145,8 @@ Additionally, the `context` object has the following methods: The main method you'll use when writing custom rules is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: -* `message`: (`string`) The problem message. +* `message`: (`string`) The problem message (alternative to `messageId`). +* `messageId`: (`string`) The ID of the message (see [messageIds](#messageids)) (recommended alternative to `message`). * `node`: (optional `object`) The AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem. * `loc`: (optional `object`) Specifies the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`. * `start`: An object of the start location. @@ -192,9 +193,11 @@ The node contains all the information necessary to figure out the line and colum #### `messageId`s -Instead of typing out messages in both the `context.report()` call and your tests, you can use `messageId`s instead. +`messageId`s are the recommended alternative to typing out messages in `context.report()` calls because of the following benefits: -This allows you to avoid retyping error messages. It also prevents errors reported in different sections of your rule from having out-of-date messages. +* Rule violation messages can be stored in a central `meta.messages` object for convenient management +* Rule violation messages do not need to be repeated in both the rule file and rule test file +* As a result, the barrier for changing rule violation messages is lower, encouraging more frequent contributions to improve and optimize them for the greatest clarity and usefulness Rule file: From 240e833a11471ee5cbb20681cd8cdb834f3c3af1 Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Tue, 30 Jan 2024 12:48:29 -0500 Subject: [PATCH 2/3] Update docs/src/extend/custom-rules.md Co-authored-by: Nicholas C. Zakas --- docs/src/extend/custom-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index a37a1102625..ebf8348f7d0 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -193,7 +193,7 @@ The node contains all the information necessary to figure out the line and colum #### `messageId`s -`messageId`s are the recommended alternative to typing out messages in `context.report()` calls because of the following benefits: +`messageId`s are the recommended approach to reporting messages in `context.report()` calls because of the following benefits: * Rule violation messages can be stored in a central `meta.messages` object for convenient management * Rule violation messages do not need to be repeated in both the rule file and rule test file From be4d9dbf4c5cb4171ec5bd76b131504398d4eed0 Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Tue, 30 Jan 2024 12:48:36 -0500 Subject: [PATCH 3/3] Update docs/src/extend/custom-rules.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Josh Goldberg ✨ --- docs/src/extend/custom-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index ebf8348f7d0..430264a466a 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -145,8 +145,8 @@ Additionally, the `context` object has the following methods: The main method you'll use when writing custom rules is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: +* `messageId`: (`string`) The ID of the message (see [messageIds](#messageids)) (recommended over `message`). * `message`: (`string`) The problem message (alternative to `messageId`). -* `messageId`: (`string`) The ID of the message (see [messageIds](#messageids)) (recommended alternative to `message`). * `node`: (optional `object`) The AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem. * `loc`: (optional `object`) Specifies the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`. * `start`: An object of the start location.