@@ -8,8 +8,10 @@ new tool, it should include:
88- Provide test cases:
99
1010 1 . Create the ` test/linters/<LANGUGAGE> ` directory.
11- 2 . Provide at least one test case with a file that is supposed to pass validation: ` test/linters/<LANGUAGE>/<name-of-tool>-good `
12- 3 . Provide at least one test case with a file that is supposed to fail validation: ` test/linters/<LANGUAGE>/<name-of-tool>-bad `
11+ 2 . Provide at least one test case with a file that is supposed to pass validation,
12+ with the right file extension if needed: ` test/linters/<LANGUAGE>/<name-of-tool>-good `
13+ 3 . Provide at least one test case with a file that is supposed to fail validation,
14+ with the right file extension if needed: ` test/linters/<LANGUAGE>/<name-of-tool>-bad `
1315
1416- Update the test suite to check for installed packages, the commands that your new tool needs in the ` PATH ` , and the expected version command:
1517
@@ -89,28 +91,73 @@ new tool, it should include:
8991
9092- Update the orchestration scripts to run the new tool:
9193
92- - `globals/languages.sh`: add a new item to `LANGUAGES_ARRAY` array. Use the
93- "name" of the language, then a `_`, and finally the name of the linter. Example: `PYTHON_RUFF`
94+ - `lib/globals/languages.sh`: add a new item to `LANGUAGES_ARRAY` array. Use the
95+ "name" of the language, then a `_`, and finally the name of the linter. Example: `PYTHON_RUFF`.
96+ In the context of this document, to avoid repetitions we reference this new
97+ item as `<LANGUAGE_NAME>`.
98+
9499 - Linter configuration:
95- - `globals/linterRules.sh`:
96- - If the new linter accepts a configuration files from the command line, add a new variable
97- with a default filename using the item that you added to the `LANGUAGES_ARRAY` as a prefix,
98- followed by the `CONFIG_FILE` suffix. Example:
99- `PYTHON_RUFF_FILE_NAME="${PYTHON_RUFF_CONFIG_FILE:-.ruff.toml}"`.
100- - If there are arguments that you can only pass using the command line, and you think users
101- might want to customize them, define a new variable using the item that
102- you added to the `LANGUAGES_ARRAY` as a prefix, followed by the
103- `COMMAND_ARGS` suffix. Example:
104- `GITHUB_ACTIONS_COMMAND_ARGS="${GITHUB_ACTIONS_COMMAND_ARGS:-""}"`
105100 - Create a new minimal configuration file in the `TEMPLATES` directory with the same name as the
106101 default configuration filename. Example: `TEMPLATES/.ruff.toml`.
107- - `lib/linter.sh`
108- - `lib/functions/linterCommands.sh`: define a new array to invoke the new linter.
109- - Provide the logic to populate the list of files or directories to examine: `lib/buildFileList.sh`
110- - If necessary, provide elaborate logic to detect if the tool should examine a file or a directory: `lib/detectFiles.sh`
111- - If the tool needs to take into account special cases:
112-
113- - Provide new runtime validation checks in `lib/validation.sh`.
114- - Customize the logic to get the installed version of the tool: `scripts/linterVersions.sh`
115- - Provide custom logic to load configuration files: `lib/linterRules.sh`
116- - Provide custom logic for test cases and to run the tool: `lib/worker.sh`
102+ - `lib/globals/linterRules.sh`:
103+ - If the new linter accepts a configuration files from the command line,
104+ define a new variable:
105+ `<LANGUAGE_NAME>_FILE_NAME="${<LANGUAGE_NAME>_CONFIG_FILE:-"default-config-file-name.conf"}"`
106+ where `default-config-file-name.conf` is the name of the new,
107+ minimal configuration for the linter. Example:
108+ `PYTHON_RUFF_FILE_NAME="${PYTHON_RUFF_CONFIG_FILE:-.ruff.toml}"`.
109+ - If there are arguments that you can only pass using the command line, and you think users
110+ might want to customize them, define a new variable using
111+ `<LANGUAGE_NAME>_COMMAND_ARGS` and add it to the command if the
112+ configuration provides it. Example:
113+
114+ ```bash
115+ <LANGUAGE_NAME>_COMMAND_ARGS="${<LANGUAGE_NAME>_COMMAND_ARGS:-""}"
116+ if [ -n "${<LANGUAGE_NAME>_COMMAND_ARGS:-}" ]; then
117+ export <LANGUAGE_NAME>_COMMAND_ARGS
118+ LINTER_COMMANDS_ARRAY_<LANGUAGE_NAME>+=("${<LANGUAGE_NAME>_COMMAND_ARGS}")
119+ fi
120+ ```
121+
122+ - Define the command to invoke the new linter:
123+
124+ - `lib/functions/linterCommands.sh`: add the command to invoke the linter.
125+ Define a new variable: `LINTER_COMMANDS_ARRAY_<LANGUAGE_NAME>`.
126+ Example:
127+ `LINTER_COMMANDS_ARRAY_GO_MODULES=(golangci-lint run --allow-parallel-runners -c "${GO_LINTER_RULES}")`
128+
129+ If the linter needs to load a configuration file, add the relevant options
130+ and paths to the command you just defined. The path to the configuration
131+ file is automatically initialized by Super-linter using in the
132+ `<LANGUAGE_NAME>_LINTER_RULES` variable, as in the `GO_LINTER_RULES`
133+ example above for the `GO` language.
134+
135+ - `lib/globals/linterCommandsOptions.sh`: add "check only mode" and "fix
136+ linting and formatting issues mode" options if the linter supports it.
137+ Super-linter will automatically add them to the command to run the linter.
138+
139+ - If the linter runs in "fix linting and formatting issues mode" by
140+ default, define a new variable with the options to add to the linter
141+ command to enable "check only mode":
142+ `<LANGUAGE_NAME>_CHECK_ONLY_MODE_OPTIONS=(....)`.
143+ Example: `PYTHON_BLACK_CHECK_ONLY_MODE_OPTIONS=(--diff --check)`
144+
145+ - If the linter runs in "check only mode" by
146+ default, define a new variable with the options to add to the linter
147+ command to enable "fix linting and formatting issues mode":
148+ `<LANGUAGE_NAME>_FIX_MODE_OPTIONS=(...)`.
149+ Example: `ANSIBLE_FIX_MODE_OPTIONS=(--fix)`
150+
151+ - Provide the logic to populate the list of files or directories to examine: `lib/functions/buildFileList.sh`
152+ - If necessary, provide elaborate logic to detect if the tool should examine a file or a directory: `lib/functions/detectFiles.sh`
153+ - If the tool needs to take into account special cases, reach out to the
154+ maintainers by creating a draft pull request and ask relevant questions
155+ there. For example, you might need to provide new logic or customize
156+ the existing one to:
157+
158+ - Validate the runtime environment: `lib/functions/validation.sh`.
159+ - Get the installed version of the linter: `scripts/linterVersions.sh`
160+ - Load configuration files: `lib/functions/linterRules.sh`
161+ - Run the linter: `lib/functions/worker.sh`
162+ - Compose the linter command: `lib/functions/linterCommands.sh`
163+ - Modify the core Super-linter logic: `lib/linter.sh`
0 commit comments