From 06acd04bba967e1b0fad4d84875dc4dc7b4bff70 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 22 Dec 2020 17:48:38 -0800 Subject: [PATCH 1/6] Improve explanations in Library Manager-related rule messages arduino-lint uses --library-manager=submit configuration by default when linting standalone libraries. Violations of some of the rules are warnings even when not in a Library Manager mode. For these reasons, library authors may be exposed to these messages when they are not obviously applicable based on the previous text. --- internal/rule/ruleconfiguration/ruleconfiguration.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index 05a654533..17f91ff02 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -129,7 +129,7 @@ var configurations = []Type{ ID: "LS005", Brief: "symlink", Description: "", - MessageTemplate: "Symlink(s) found at {{.}}. These block acceptance to the Arduino Library Manager index.", + MessageTemplate: "Symlink(s) found at {{.}}. Symlinks cause difficulties for Windows users. These block acceptance to the Arduino Library Manager index.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -144,8 +144,8 @@ var configurations = []Type{ Subcategory: "miscellaneous", ID: "LS006", Brief: ".development file", - Description: "", - MessageTemplate: ".development flag file found. Presence of this file blocks addition to the Library Manager index.", + Description: "See: https://arduino.github.io/arduino-cli/latest/library-specification/#development-flag-file", + MessageTemplate: ".development flag file found. This file allows users to accidentally modify examples. Presence of this file blocks addition to the Library Manager index.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -513,7 +513,7 @@ var configurations = []Type{ ID: "LP017", Brief: "duplicate name", Description: "This requirement only applies to the library.properties name value. There is no requirement to change the repository or header file names.", - MessageTemplate: "Library name {{.}} is in use by a library in the Library Manager index. Each library must have a unique name value.", + MessageTemplate: "Library name {{.}} is in use by a library in the Library Manager index. Each library must have a unique name value. If library is already in the index, use the \"--library-manager update\" flag.", DisableModes: []rulemode.Type{rulemode.LibraryManagerIndexed}, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, From 8f8606003c4b0851f4f7ddaf888f0cb621f76f01 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 22 Dec 2020 17:59:55 -0800 Subject: [PATCH 2/6] Use consistent capitalization of first letter of rule message Not sure whether upper or lower case is better (because the message is prefixed with the rule level text), but certainly it should be consistent across all messages. --- .../ruleconfiguration/ruleconfiguration.go | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index 17f91ff02..effd10d08 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -353,7 +353,7 @@ var configurations = []Type{ ID: "LP007", Brief: "missing name field", Description: "", - MessageTemplate: "missing name field in library.properties", + MessageTemplate: "Missing name field in library.properties", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -417,7 +417,7 @@ var configurations = []Type{ ID: "LP011", Brief: "disallowed characters", Description: "", - MessageTemplate: "disallowed characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Disallowed characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -545,7 +545,7 @@ var configurations = []Type{ ID: "LP019", Brief: "missing version field", Description: "", - MessageTemplate: "missing version field in library.properties", + MessageTemplate: "Missing version field in library.properties", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -609,7 +609,7 @@ var configurations = []Type{ ID: "LP023", Brief: "missing author field", Description: "", - MessageTemplate: "missing required author field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing required author field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -641,7 +641,7 @@ var configurations = []Type{ ID: "LP025", Brief: "missing maintainer field", Description: "", - MessageTemplate: "missing required maintainer field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing required maintainer field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -737,7 +737,7 @@ var configurations = []Type{ ID: "LP031", Brief: "missing sentence field", Description: "", - MessageTemplate: "missing required sentence field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing required sentence field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -785,7 +785,7 @@ var configurations = []Type{ ID: "LP034", Brief: "missing paragraph field", Description: "", - MessageTemplate: "missing required paragraph field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing required paragraph field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -833,7 +833,7 @@ var configurations = []Type{ ID: "LP037", Brief: "missing category field", Description: `This can cause a warning and results in the default "Uncategorized" category being used.`, - MessageTemplate: "missing category field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing category field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -849,7 +849,7 @@ var configurations = []Type{ ID: "LP038", Brief: "invalid category value", Description: `This can cause a warning and results in the default "Uncategorized" category being used.`, - MessageTemplate: "invalid category field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Invalid category field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -881,7 +881,7 @@ var configurations = []Type{ ID: "LP040", Brief: "missing url field", Description: "", - MessageTemplate: "missing required url field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing required url field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -911,7 +911,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "url field", ID: "LP042", - Brief: "Dead URL", + Brief: "dead URL", Description: "", MessageTemplate: "Unable to load the library.properties url field: {{.}}", DisableModes: nil, @@ -929,7 +929,7 @@ var configurations = []Type{ ID: "LP043", Brief: "missing architectures field", Description: "Defaults to *, but it's better to explicitly define architectures.", - MessageTemplate: "missing architectures field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing architectures field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -993,7 +993,7 @@ var configurations = []Type{ ID: "LP047", Brief: "disallowed characters", Description: "", - MessageTemplate: "disallowed characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Disallowed characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1025,7 +1025,7 @@ var configurations = []Type{ ID: "LP049", Brief: "invalid value", Description: "", - MessageTemplate: "invalid dot_a_linkage field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Invalid dot_a_linkage field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1089,7 +1089,7 @@ var configurations = []Type{ ID: "LP053", Brief: "invalid value", Description: "", - MessageTemplate: "invalid precompiled field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Invalid precompiled field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1455,7 +1455,7 @@ var configurations = []Type{ Category: "configuration files", Subcategory: "boards.txt", ID: "PF002", - Brief: "Invalid boards.txt", + Brief: "invalid boards.txt", Description: "", MessageTemplate: "boards.txt has an invalid format: {{.}}", DisableModes: nil, From d4c5e9cade8741b948150465a2cdc14e7d01f44e Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 22 Dec 2020 19:20:01 -0800 Subject: [PATCH 3/6] Make rule brief text more suitable for standalone display Previously, the briefs were intended to be used in the context of the other rule metadata. In order to allow the `brief text to be used by itself as a short explanation of rules, it is necessary to modify some of the wording. --- .../ruleconfiguration/ruleconfiguration.go | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index effd10d08..9d02fc17b 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -63,7 +63,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "general", ID: "LS001", - Brief: "invalid", + Brief: "invalid library", Description: "", MessageTemplate: "Path does not contain a valid Arduino library. See: https://arduino.github.io/arduino-cli/latest/library-specification", DisableModes: nil, @@ -95,7 +95,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "root folder", ID: "LS003", - Brief: "disallowed characters in folder name", + Brief: "prohibited characters in folder name", Description: "This will be problematic for people doing manual installation of the library.", MessageTemplate: "Prohibited characters in folder name: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", DisableModes: nil, @@ -191,7 +191,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "source code", ID: "LS009", - Brief: "incorrect src folder case", + Brief: "src folder case", Description: "", MessageTemplate: "Incorrect src folder case: {{.}}. This will cause the library to not be recognized on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", DisableModes: nil, @@ -207,7 +207,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "source code", ID: "LS010", - Brief: "recursive with utility folder", + Brief: "recursive w/ utility folder", Description: "", MessageTemplate: `Utility folder found in "1.5" format library. Compilation of this folder is only supported on "1.0" format libraries. See: https://arduino.github.io/arduino-cli/latest/library-specification/#source-code`, DisableModes: nil, @@ -239,7 +239,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "extras folder", ID: "LS012", - Brief: "incorrect extras folder name case", + Brief: "extras folder name case", Description: "", MessageTemplate: "Incorrect extras folder name case: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#extra-documentation", DisableModes: nil, @@ -255,7 +255,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "general", ID: "LP001", - Brief: "missing", + Brief: "missing library.properties", Description: `Although not required for 1.0 format libraries (AKA "legacy") not in Library Manager, metadata is useful, so it is recommended.`, MessageTemplate: "Library has no library.properties metadata file. This file provides useful information and is required for admission to the Library Manager index. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata", DisableModes: nil, @@ -287,7 +287,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "general", ID: "LP003", - Brief: "incorrect library.properties file name case", + Brief: "library.properties file name case", Description: `This causes "1.5" format (AKA "recursive layout") libraries to not be recognized on filename case-sensitive operating systems.`, MessageTemplate: "Incorrect library.properties file name case: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata", DisableModes: nil, @@ -303,7 +303,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "general", ID: "LP004", - Brief: "redundant", + Brief: "redundant library.properties", Description: "", MessageTemplate: "Redundant library.properties file found at {{.}}. Only the file in the root of the library is used. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata", DisableModes: nil, @@ -319,7 +319,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "general", ID: "LP005", - Brief: "invalid format", + Brief: "library.properties format", Description: "", MessageTemplate: "library.properties has an invalid format: {{.}}", DisableModes: nil, @@ -335,7 +335,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "general", ID: "LP006", - Brief: "misspelled field", + Brief: "misspelled library.properties field", Description: "", MessageTemplate: "Potentially misspelled library.properties field name detected. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -351,7 +351,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP007", - Brief: "missing name field", + Brief: "missing name", Description: "", MessageTemplate: "Missing name field in library.properties", DisableModes: nil, @@ -415,7 +415,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP011", - Brief: "disallowed characters", + Brief: "prohibited characters in name", Description: "", MessageTemplate: "Disallowed characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -431,7 +431,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP012", - Brief: `starts with "Arduino"`, + Brief: `name starts with "Arduino"`, Description: `Case insensitive. 3rd party libraries added to Library Manager index prior to the enactment of this rule are "grandfathered".`, MessageTemplate: `Library name {{.}} starts with "Arduino". These names are reserved for official libraries.`, DisableModes: []rulemode.Type{rulemode.Official}, @@ -447,7 +447,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP013", - Brief: "missing official prefix", + Brief: "name missing official prefix", Description: "", MessageTemplate: `Library name {{.}} is missing the "Arduino_" prefix. All new official library names must use this prefix.`, DisableModes: []rulemode.Type{rulemode.Default}, @@ -463,7 +463,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP014", - Brief: `contains "Arduino"`, + Brief: `name contains "Arduino"`, Description: "Case insensitive", MessageTemplate: `Library name {{.}} contains "Arduino". This is superfluous.`, DisableModes: []rulemode.Type{rulemode.Official}, @@ -479,7 +479,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP015", - Brief: "contains spaces", + Brief: "name contains spaces", Description: "Best practices is for the name value, installation folder, and primary header filename to all match, but this is not possible with names containing spaces.", MessageTemplate: "library.properties name {{.}} contains spaces. Although supported, best practices is to not use spaces.", DisableModes: nil, @@ -495,7 +495,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP016", - Brief: `contains "library"`, + Brief: `name contains "library"`, Description: "Case insensitive", MessageTemplate: `Library name {{.}} contains "library". This is superfluous.`, DisableModes: nil, @@ -559,7 +559,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "version field", ID: "LP020", - Brief: "invalid", + Brief: "invalid version", Description: `Must be compliant with "relaxed semver".`, MessageTemplate: "library.properties version value {{.}} is invalid. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -575,7 +575,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "version field", ID: "LP021", - Brief: "non-semver", + Brief: "non-semver version", Description: "", MessageTemplate: "library.properties version value {{.}} is not compliant with the semver specification. See https://semver.org/", DisableModes: nil, @@ -671,7 +671,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "maintainer field", ID: "LP027", - Brief: `starts with "Arduino"`, + Brief: `maintainer starts with "Arduino"`, Description: "Case insensitive.", MessageTemplate: `library.properties maintainer value {{.}} starts with "Arduino". 3rd party libraries are not maintained by Arduino.`, DisableModes: []rulemode.Type{rulemode.Official}, @@ -687,7 +687,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "email field", ID: "LP028", - Brief: `"email" field used as alias for "maintainer"`, + Brief: `"email" used as alias for "maintainer"`, Description: "This was in an early draft of the beta 1.5 library specification.", MessageTemplate: `library.properties "email" field used as alias for "maintainer". This is deprecated.`, DisableModes: nil, @@ -719,7 +719,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "email field", ID: "LP030", - Brief: `starts with "Arduino"`, + Brief: `email starts with "Arduino"`, Description: "Case insensitive.", MessageTemplate: `library.properties email value {{.}} starts with "Arduino". 3rd party libraries are not maintained by Arduino.`, DisableModes: []rulemode.Type{rulemode.Official}, @@ -975,7 +975,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "architectures field", ID: "LP046", - Brief: "miscased architecture", + Brief: "architecture case", Description: "", MessageTemplate: "Incorrect case of library.properties architectures field item(s): {{.}}. Architectures are case sensitive. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -991,7 +991,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "depends field", ID: "LP047", - Brief: "disallowed characters", + Brief: "prohibited characters in depends", Description: "", MessageTemplate: "Disallowed characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -1007,7 +1007,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "depends field", ID: "LP048", - Brief: "Dependency not in index", + Brief: "depends not in index", Description: "", MessageTemplate: "library.properties depends field item(s) {{.}} not found in the Library Manager index.", DisableModes: nil, @@ -1023,7 +1023,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "dot_a_linkage field", ID: "LP049", - Brief: "invalid value", + Brief: "invalid dot_a_linkage value", Description: "", MessageTemplate: "Invalid dot_a_linkage field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -1039,7 +1039,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "dot_a_linkage field", ID: "LP050", - Brief: `"true" with "1.5" library format`, + Brief: `dot_a_linkage=true with "1.0" library format`, Description: `dot_a_linkage feature is only supported for the "1.5" or "recursive" library format.`, MessageTemplate: `library.properties dot_a_linkage field enabled but library is not in "1.5" format. See: https://arduino.github.io/arduino-cli/latest/library-specification/#source-code`, DisableModes: nil, @@ -1071,7 +1071,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "includes field", ID: "LP052", - Brief: "includes file not in library", + Brief: "includes not in library", Description: `People often think this is the way to define their library's dependencies, which breaks the "Sketch > Include Library" feature for that library.`, MessageTemplate: "library.properties includes field item(s) {{.}} not found in library.", DisableModes: nil, @@ -1087,7 +1087,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "precompiled field", ID: "LP053", - Brief: "invalid value", + Brief: "invalid precompiled value", Description: "", MessageTemplate: "Invalid precompiled field value {{.}} in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, @@ -1103,7 +1103,7 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "precompiled field", ID: "LP054", - Brief: "precompiled with flat layout", + Brief: "precompiled with \"1.0\" format", Description: `precompiled feature is only supported for the "1.5" or "recursive" library format.`, MessageTemplate: `library.properties precompiled field value {{.}}, is not supported with "1.0" format. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format`, DisableModes: nil, @@ -1135,7 +1135,7 @@ var configurations = []Type{ Category: "code", Subcategory: "miscellaneous", ID: "LC001", - Brief: "incorrect Arduino.h case", + Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", DisableModes: nil, @@ -1231,7 +1231,7 @@ var configurations = []Type{ Category: "documentation", Subcategory: "examples", ID: "LD006", - Brief: "incorrect examples folder name case", + Brief: "examples folder name case", Description: "", MessageTemplate: "Incorrect examples folder name case: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-examples", DisableModes: nil, @@ -1263,7 +1263,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "file name", ID: "SS002", - Brief: "disallowed characters in file name", + Brief: "prohibited filename characters", Description: "", MessageTemplate: "Prohibited characters in file name(s): {{.}}. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#sketch-root-folder", DisableModes: nil, @@ -1311,7 +1311,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "miscellaneous", ID: "SS005", - Brief: "incorrect src folder case", + Brief: "src folder case", Description: "", MessageTemplate: "Incorrect src folder case: {{.}}. This will cause the source files under it to not be compiled on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#src-subfolder", DisableModes: nil, @@ -1327,7 +1327,7 @@ var configurations = []Type{ Category: "code", Subcategory: "miscellaneous", ID: "SC001", - Brief: "incorrect Arduino.h case", + Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", DisableModes: nil, @@ -1375,7 +1375,7 @@ var configurations = []Type{ Category: "sketch.json", Subcategory: "general", ID: "SM001", - Brief: "invalid sketch.json JSON format", + Brief: "sketch.json JSON format", Description: "", MessageTemplate: "sketch.json is not a valid JSON document. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata", DisableModes: nil, @@ -1391,7 +1391,7 @@ var configurations = []Type{ Category: "sketch.json", Subcategory: "general", ID: "SM002", - Brief: "invalid sketch.json data format", + Brief: "sketch.json data format", Description: "", MessageTemplate: "sketch.json has an invalid data format: {{.}}. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata", DisableModes: nil, @@ -1439,7 +1439,7 @@ var configurations = []Type{ Category: "configuration files", Subcategory: "boards.txt", ID: "PF001", - Brief: "missing", + Brief: "boards.txt missing", Description: "", MessageTemplate: "Required boards.txt is missing. Expected at: {{.}}", DisableModes: nil, @@ -1471,7 +1471,7 @@ var configurations = []Type{ Category: "code", Subcategory: "miscellaneous", ID: "PC001", - Brief: "incorrect Arduino.h case", + Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", DisableModes: nil, @@ -1487,7 +1487,7 @@ var configurations = []Type{ Category: "data", Subcategory: "general", ID: "ID001", - Brief: "Invalid JSON format", + Brief: "JSON format", Description: "", MessageTemplate: "Invalid JSON format.", DisableModes: nil, @@ -1503,7 +1503,7 @@ var configurations = []Type{ Category: "data", Subcategory: "general", ID: "ID002", - Brief: "Invalid format", + Brief: "data format", Description: "", MessageTemplate: "Invalid package index format: {{.}}", DisableModes: nil, From 5526f51ccd053e85cddef1328f6816c1eda99a60 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 22 Dec 2020 19:22:45 -0800 Subject: [PATCH 4/6] Improve wording of rule messages --- .../ruleconfiguration/ruleconfiguration.go | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index 9d02fc17b..c126dffd1 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -129,7 +129,7 @@ var configurations = []Type{ ID: "LS005", Brief: "symlink", Description: "", - MessageTemplate: "Symlink(s) found at {{.}}. Symlinks cause difficulties for Windows users. These block acceptance to the Arduino Library Manager index.", + MessageTemplate: "Symlink(s) found at {{.}}. Symlinks cause difficulties for Windows users. These block addition to the Arduino Library Manager index.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -161,7 +161,7 @@ var configurations = []Type{ ID: "LS007", Brief: ".exe file", Description: "", - MessageTemplate: ".exe file(s) found: {{.}}. Presence of these files blocks inclusion in Library Manager index.", + MessageTemplate: ".exe file(s) found: {{.}}. Presence of these files blocks addition to the Library Manager index.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -193,7 +193,7 @@ var configurations = []Type{ ID: "LS009", Brief: "src folder case", Description: "", - MessageTemplate: "Incorrect src folder case: {{.}}. This will cause the library to not be recognized on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", + MessageTemplate: "Incorrect src folder name case: {{.}}. This will cause the library to not be recognized on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -207,7 +207,7 @@ var configurations = []Type{ Category: "structure", Subcategory: "source code", ID: "LS010", - Brief: "recursive w/ utility folder", + Brief: "recursive with utility folder", Description: "", MessageTemplate: `Utility folder found in "1.5" format library. Compilation of this folder is only supported on "1.0" format libraries. See: https://arduino.github.io/arduino-cli/latest/library-specification/#source-code`, DisableModes: nil, @@ -256,7 +256,7 @@ var configurations = []Type{ Subcategory: "general", ID: "LP001", Brief: "missing library.properties", - Description: `Although not required for 1.0 format libraries (AKA "legacy") not in Library Manager, metadata is useful, so it is recommended.`, + Description: `Although not required for 1.0 format libraries (AKA "legacy") not in Library Manager, metadata is useful, hence recommended.`, MessageTemplate: "Library has no library.properties metadata file. This file provides useful information and is required for admission to the Library Manager index. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -320,7 +320,7 @@ var configurations = []Type{ Subcategory: "general", ID: "LP005", Brief: "library.properties format", - Description: "", + Description: "See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", MessageTemplate: "library.properties has an invalid format: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -353,7 +353,7 @@ var configurations = []Type{ ID: "LP007", Brief: "missing name", Description: "", - MessageTemplate: "Missing name field in library.properties", + MessageTemplate: "Missing name field in library.properties. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -401,7 +401,7 @@ var configurations = []Type{ ID: "LP010", Brief: "name > recommended length", Description: "", - MessageTemplate: "library.properties name value {{.}} is longer than recommended max length.", + MessageTemplate: "library.properties name value {{.}} is longer than the recommended length of 16 characters.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -417,7 +417,7 @@ var configurations = []Type{ ID: "LP011", Brief: "prohibited characters in name", Description: "", - MessageTemplate: "Disallowed characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Prohibited characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -432,7 +432,7 @@ var configurations = []Type{ Subcategory: "name field", ID: "LP012", Brief: `name starts with "Arduino"`, - Description: `Case insensitive. 3rd party libraries added to Library Manager index prior to the enactment of this rule are "grandfathered".`, + Description: `Case insensitive. Only 3rd party libraries added to the Library Manager index prior to the enactment of this rule are allowed to have this name prefix.`, MessageTemplate: `Library name {{.}} starts with "Arduino". These names are reserved for official libraries.`, DisableModes: []rulemode.Type{rulemode.Official}, EnableModes: []rulemode.Type{rulemode.Default}, @@ -513,7 +513,7 @@ var configurations = []Type{ ID: "LP017", Brief: "duplicate name", Description: "This requirement only applies to the library.properties name value. There is no requirement to change the repository or header file names.", - MessageTemplate: "Library name {{.}} is in use by a library in the Library Manager index. Each library must have a unique name value. If library is already in the index, use the \"--library-manager update\" flag.", + MessageTemplate: "Library name {{.}} is in use by a library in the Library Manager index. Each library must have a unique name value. If your library is already in the index, use the \"--library-manager update\" flag.", DisableModes: []rulemode.Type{rulemode.LibraryManagerIndexed}, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -609,7 +609,7 @@ var configurations = []Type{ ID: "LP023", Brief: "missing author field", Description: "", - MessageTemplate: "Missing required author field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing author field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -641,7 +641,7 @@ var configurations = []Type{ ID: "LP025", Brief: "missing maintainer field", Description: "", - MessageTemplate: "Missing required maintainer field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing maintainer field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -688,7 +688,7 @@ var configurations = []Type{ Subcategory: "email field", ID: "LP028", Brief: `"email" used as alias for "maintainer"`, - Description: "This was in an early draft of the beta 1.5 library specification.", + Description: "This was only in an early draft of the beta 1.5 library specification.", MessageTemplate: `library.properties "email" field used as alias for "maintainer". This is deprecated.`, DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -737,7 +737,7 @@ var configurations = []Type{ ID: "LP031", Brief: "missing sentence field", Description: "", - MessageTemplate: "Missing required sentence field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing sentence field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -785,7 +785,7 @@ var configurations = []Type{ ID: "LP034", Brief: "missing paragraph field", Description: "", - MessageTemplate: "Missing required paragraph field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing paragraph field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -865,7 +865,7 @@ var configurations = []Type{ ID: "LP039", Brief: `"Uncategorized" category value`, Description: "There is no good reason for using this non-specification compliant category value.", - MessageTemplate: `Use of "Uncategorized" category value in library.properties. Please use one of the supported categories listed at https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format`, + MessageTemplate: `Use of "Uncategorized" category value in library.properties. Please use one of the allowed categories: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format`, DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -881,7 +881,7 @@ var configurations = []Type{ ID: "LP040", Brief: "missing url field", Description: "", - MessageTemplate: "Missing required url field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Missing url field in library.properties. See https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -993,7 +993,7 @@ var configurations = []Type{ ID: "LP047", Brief: "prohibited characters in depends", Description: "", - MessageTemplate: "Disallowed characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Prohibited characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1008,7 +1008,7 @@ var configurations = []Type{ Subcategory: "depends field", ID: "LP048", Brief: "depends not in index", - Description: "", + Description: "This field should be used to define the dependencies available from Library Manager. Library names are case-sensitive.", MessageTemplate: "library.properties depends field item(s) {{.}} not found in the Library Manager index.", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -1137,7 +1137,7 @@ var configurations = []Type{ ID: "LC001", Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", - MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", + MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1329,7 +1329,7 @@ var configurations = []Type{ ID: "SC001", Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", - MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", + MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1409,7 +1409,7 @@ var configurations = []Type{ ID: "PD001", Brief: "no readme", Description: "", - MessageTemplate: "No readme found. Please document your library. See: https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-readmes", + MessageTemplate: "No readme found. Please document your boards platform. See: https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-readmes", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1473,7 +1473,7 @@ var configurations = []Type{ ID: "PC001", Brief: "Arduino.h case", Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", - MessageTemplate: "Incorrect of Arduino.h filename case detected in #include directive: {{.}}", + MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, From c0e4e92dd167afba37bb44d4ee361dae2d9a7628 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 23 Dec 2020 15:52:28 -0800 Subject: [PATCH 5/6] Use optional plurality in prohibited character rule messages The rule covers one or more prohibited characters, so use of a hard singular/plural in the rule message might lead to confusion. At the same time, the alternative (s) uses more characters, so is less well suited to the rule brief. The compromise is to use the singular "prohibited character" in the brief text, and the flexible "prohibited character(s)" in the less length-constrained rule message, which will always be displayed if the rule is violated. --- .../rule/ruleconfiguration/ruleconfiguration.go | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index c126dffd1..90d1940fb 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -95,9 +95,9 @@ var configurations = []Type{ Category: "structure", Subcategory: "root folder", ID: "LS003", - Brief: "prohibited characters in folder name", + Brief: "prohibited character in folder name", Description: "This will be problematic for people doing manual installation of the library.", - MessageTemplate: "Prohibited characters in folder name: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", + MessageTemplate: "Prohibited character(s) in folder name: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -415,9 +415,9 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "name field", ID: "LP011", - Brief: "prohibited characters in name", + Brief: "prohibited character in name", Description: "", - MessageTemplate: "Prohibited characters in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Prohibited character(s) in library.properties name value: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -991,9 +991,9 @@ var configurations = []Type{ Category: "library.properties", Subcategory: "depends field", ID: "LP047", - Brief: "prohibited characters in depends", + Brief: "prohibited character in depends", Description: "", - MessageTemplate: "Prohibited characters in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", + MessageTemplate: "Prohibited character(s) in library.properties depends field {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1263,9 +1263,9 @@ var configurations = []Type{ Category: "structure", Subcategory: "file name", ID: "SS002", - Brief: "prohibited filename characters", + Brief: "prohibited character in filename", Description: "", - MessageTemplate: "Prohibited characters in file name(s): {{.}}. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#sketch-root-folder", + MessageTemplate: "Prohibited character(s) in file name(s): {{.}}. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#sketch-root-folder", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, From a42cd8c92d40b302c5bd91388edd1d664fedf642 Mon Sep 17 00:00:00 2001 From: per1234 Date: Thu, 24 Dec 2020 03:19:24 -0800 Subject: [PATCH 6/6] Use more common phrase for filename case-sensitive OS It turns out that "filename case-sensitive operating system" is not a common phrase, so maybe not clear, and without an exact definition to be found from a search. --- internal/rule/ruleconfiguration/ruleconfiguration.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/internal/rule/ruleconfiguration/ruleconfiguration.go b/internal/rule/ruleconfiguration/ruleconfiguration.go index 90d1940fb..73c67c0c5 100644 --- a/internal/rule/ruleconfiguration/ruleconfiguration.go +++ b/internal/rule/ruleconfiguration/ruleconfiguration.go @@ -193,7 +193,7 @@ var configurations = []Type{ ID: "LS009", Brief: "src folder case", Description: "", - MessageTemplate: "Incorrect src folder name case: {{.}}. This will cause the library to not be recognized on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", + MessageTemplate: "Incorrect src folder name case: {{.}}. This will cause the library to not be recognized on case-sensitive file systems. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-root-folder", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -288,7 +288,7 @@ var configurations = []Type{ Subcategory: "general", ID: "LP003", Brief: "library.properties file name case", - Description: `This causes "1.5" format (AKA "recursive layout") libraries to not be recognized on filename case-sensitive operating systems.`, + Description: `This causes "1.5" format (AKA "recursive layout") libraries to not be recognized on case-sensitive file systems.`, MessageTemplate: "Incorrect library.properties file name case: {{.}}. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -1136,7 +1136,7 @@ var configurations = []Type{ Subcategory: "miscellaneous", ID: "LC001", Brief: "Arduino.h case", - Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", + Description: "This causes compilation failure on case-sensitive file systems.", MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -1313,7 +1313,7 @@ var configurations = []Type{ ID: "SS005", Brief: "src folder case", Description: "", - MessageTemplate: "Incorrect src folder case: {{.}}. This will cause the source files under it to not be compiled on case-sensitive operating systems. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#src-subfolder", + MessageTemplate: "Incorrect src folder case: {{.}}. This will cause the source files under it to not be compiled on case-sensitive file systems. See: https://arduino.github.io/arduino-cli/latest/sketch-specification/#src-subfolder", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, InfoModes: nil, @@ -1328,7 +1328,7 @@ var configurations = []Type{ Subcategory: "miscellaneous", ID: "SC001", Brief: "Arduino.h case", - Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", + Description: "This causes compilation failure on filename case-sensitive file systems.", MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default}, @@ -1472,7 +1472,7 @@ var configurations = []Type{ Subcategory: "miscellaneous", ID: "PC001", Brief: "Arduino.h case", - Description: "This causes compilation failure on filename case-sensitive OS (e.g., Linux).", + Description: "This causes compilation failure on filename case-sensitive file systems.", MessageTemplate: "Incorrect Arduino.h filename case in #include directive: {{.}}", DisableModes: nil, EnableModes: []rulemode.Type{rulemode.Default},