1# proto-file: warn/docs/docs.proto
2# proto-message: Warnings
3# After modifying this file, run `bazel build //warn/docs:warnings_docs && cp bazel-bin/warn/docs/WARNINGS.md .`
4
5warnings: {
6 name: "attr-cfg"
7 header: "`cfg = \"data\"` for attr definitions has no effect"
8 description:
9 "The [Configuration](https://docs.bazel.build/versions/master/skylark/rules.html#configurations)\n"
10 "`cfg = \"data\"` is deprecated and has no effect. Consider removing it.\n"
11 "The [Configuration](https://docs.bazel.build/versions/master/skylark/rules.html#configurations)\n"
12 "`cfg = \"host\"` is deprecated. Consider replacing it with `cfg = \"exec\"`."
13 bazel_flag: "--incompatible_disallow_data_transition"
14 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/6153"
15 autofix: true
16}
17
18warnings: {
19 name: "attr-license"
20 header: "`attr.license()` is deprecated and shouldn't be used"
21 description: "The `attr.license()` method is almost never used and being deprecated."
22 bazel_flag: "--incompatible_no_attr_license"
23 autofix: false
24}
25
26warnings: {
27 name: "attr-licenses"
28 header: "Do not use `licenses` as an attribute name."
29 description: "Using licenses as an attribute name may cause unexpected behavior."
30 autofix: false
31}
32
33warnings: {
34 name: "attr-applicable_licenses"
35 header: "Do not use `applicable_licenses` as an attribute name."
36 description: "Using `applicable_licenses` as an attribute name may cause unexpected behavior. Its use may be prohibited in future Bazel releases."
37 autofix: false
38}
39
40warnings: {
41 name: "attr-package-metadata"
42 header: "Do not use `package_metadata` as an attribute name."
43 description: "Using `package_metadata` as an attribute name may cause unexpected behavior. Its use may be prohibited in future Bazel releases."
44 autofix: false
45}
46
47warnings: {
48 name: "attr-non-empty"
49 header: "`non_empty` attribute for attr definitions is deprecated"
50 description:
51 "The `non_empty` [attribute](https://docs.bazel.build/versions/master/skylark/lib/attr.html)\n"
52 "for attr definitions is deprecated, please use `allow_empty` with an opposite value instead."
53 bazel_flag: "--incompatible_disable_deprecated_attr_params"
54 autofix: true
55}
56
57warnings: {
58 name: "attr-output-default"
59 header: "The `default` parameter for `attr.output()`is deprecated"
60 description:
61 "The `default` parameter of `attr.output()` is bug-prone, as two targets of the same rule would be\n"
62 "unable to exist in the same package under default behavior. Use Starlark macros to specify defaults\n"
63 "for these attributes instead."
64 bazel_flag: "--incompatible_no_output_attr_default"
65 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/7950"
66 autofix: false
67}
68
69warnings: {
70 name: "attr-single-file"
71 header: "`single_file` is deprecated"
72 description:
73 "The `single_file` [attribute](https://docs.bazel.build/versions/master/skylark/lib/attr.html)\n"
74 "is deprecated, please use `allow_single_file` instead."
75 bazel_flag: "--incompatible_disable_deprecated_attr_params"
76 autofix: true
77}
78
79warnings: {
80 name: "build-args-kwargs"
81 header: "`*args` and `**kwargs` are not allowed in BUILD files"
82 description:
83 "Having `*args` or `**kwargs` makes BUILD files hard to read and manipulate. The list of\n"
84 "arguments should be explicit."
85 bazel_flag: "--incompatible_no_kwargs_in_build_files"
86 autofix: false
87}
88warnings: {
89 name: "bzl-visibility"
90 header: "Module shouldn't be used directly"
91 description:
92 "If a directory `foo` contains a subdirectory `internal` or `private`, only files located under `foo`\n"
93 "can access it.\n\n"
94 "For example, `dir/rules_mockascript/private/foo.bzl` can be loaded from\n"
95 "`dir/rules_mockascript/private/bar.bzl` or `dir/rules_mockascript/sub/public.bzl`,\n"
96 "but not from `dir/other_rule/file.bzl`."
97 autofix: false
98}
99
100warnings: {
101 name: "confusing-name"
102 header: "Never use `l`, `I`, or `O` as names"
103 description: "The names `l`, `I`, or `O` can be easily confused with `I`, `l`, or `0` correspondingly."
104 autofix: false
105}
106
107warnings: {
108 name: "constant-glob"
109 header: "Glob pattern has no wildcard ('*')"
110 description:
111 "[Glob function](https://docs.bazel.build/versions/master/be/functions.html#glob)\n"
112 "is used to get a list of files from the depot. The patterns (the first argument)\n"
113 "typically include a wildcard (* character). A pattern without a wildcard is\n"
114 "often useless and sometimes harmful.\n\n"
115 "To fix the warning, move the string out of the glob:\n\n"
116 "```diff\n"
117 "- glob([\"*.cc\", \"test.cpp\"])\n"
118 "+ glob([\"*.cc\"]) + [\"test.cpp\"]\n"
119 "```\n\n"
120 "**There’s one important difference**: before the change, Bazel would silently\n"
121 "ignore test.cpp if file is missing; after the change, Bazel will throw an error\n"
122 "if file is missing.\n\n"
123 "If `test.cpp` doesn’t exist, the fix becomes:\n\n"
124 "```diff\n"
125 "- glob([\"*.cc\", \"test.cpp\"])\n"
126 "+ glob([\"*.cc\"])\n"
127 "```\n\n"
128 "which improves maintenance and readability.\n\n"
129 "If no pattern has a wildcard, just remove the glob. It will also improve build\n"
130 "performance (glob can be relatively slow):\n\n"
131 "```diff\n"
132 "- glob([\"test.cpp\"])\n"
133 "+ [\"test.cpp\"]\n"
134 "```"
135}
136
137warnings: {
138 name: "ctx-actions"
139 header: "`ctx.{action_name}` is deprecated"
140 description:
141 "The following [actions](https://docs.bazel.build/versions/master/skylark/lib/actions.html)\n"
142 "are deprecated, please use the new API:\n\n"
143 " * [`ctx.new_file`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#new_file) → [`ctx.actions.declare_file`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#declare_file)\n"
144 " * `ctx.experimental_new_directory` → [`ctx.actions.declare_directory`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#declare_directory)\n"
145 " * [`ctx.file_action`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#file_action) → [`ctx.actions.write`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#write)\n"
146 " * [`ctx.action(command = \"...\")`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#action) → [`ctx.actions.run_shell`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#run_shell)\n"
147 " * [`ctx.action(executable = \"...\")`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#action) → [`ctx.actions.run`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#run)\n"
148 " * [`ctx.empty_action`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#empty_action) → [`ctx.actions.do_nothing`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#do_nothing)\n"
149 " * [`ctx.template_action`](https://docs.bazel.build/versions/master/skylark/lib/ctx.html#template_action) → [`ctx.actions.expand_template`](https://docs.bazel.build/versions/master/skylark/lib/actions.html#expand_template)"
150 bazel_flag: "--incompatible_new_actions_api"
151 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5825"
152 autofix: true
153}
154
155warnings: {
156 name: "ctx-args"
157 header: "`ctx.actions.args().add()` for multiple arguments is deprecated"
158 description:
159 "It's deprecated to use the [`add`](https://docs.bazel.build/versions/master/skylark/lib/Args.html#add)\n"
160 "method of `ctx.actions.args()` to add a list (or a depset) of variables. Please use either\n"
161 "[`add_all`](https://docs.bazel.build/versions/master/skylark/lib/Args.html#add_all) or\n"
162 "[`add_joined`](https://docs.bazel.build/versions/master/skylark/lib/Args.html#add_joined),\n"
163 "depending on the desired behavior."
164 bazel_flag: "--incompatible_disallow_old_style_args_add"
165 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5822"
166 autofix: true
167}
168
169warnings: {
170 name: "deprecated-function"
171 header: "The function is deprecated"
172 description:
173 "The function defined in another .bzl file has a docstring stating that it's deprecated, i.e. it\n"
174 "contains a `Deprecated:` section. The convention for function docstrings is described by\n"
175 "the [`function-docstring`](#function-docstring) warning."
176}
177
178warnings: {
179 name: "depset-items"
180 header: "Depset's \"items\" parameter is deprecated"
181 description:
182 "The `items` parameter for [`depset`](https://docs.bazel.build/versions/master/skylark/lib/globals.html#depset)\n"
183 "is deprecated. In its old form it's either a list of direct elements to be\n"
184 "added (use the `direct` or unnamed first parameter instead) or a depset that\n"
185 "becomes a transitive element of the new depset (use the `transitive` parameter\n"
186 "instead)."
187 bazel_flag: "--incompatible_disable_depset_items"
188 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/9017"
189}
190
191warnings: {
192 name: "depset-iteration"
193 header: "Depset iteration is deprecated"
194 description:
195 "Depsets are complex structures, iterations over them and lookups require flattening them to\n"
196 "a list which may be a heavy operation. To make it more obvious it's now required to call\n"
197 "the `.to_list()` method on them in order to be able to iterate their items:\n\n"
198 "```python\n"
199 "deps = depset()\n"
200 "[x.path for x in deps] # deprecated\n"
201 "[x.path for x in deps.to_list()] # recommended\n"
202 "```"
203 bazel_flag: "--incompatible_depset_is_not_iterable"
204 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5816"
205 autofix: true
206}
207
208warnings: {
209 name: "depset-union"
210 header: "Depsets should be joined using the depset constructor"
211 description:
212 "The following ways to merge two depsets are deprecated:\n\n"
213 "```python\n"
214 "depset1 + depset2\n"
215 "depset1 | depset2\n"
216 "depset1.union(depset2)\n"
217 "```\n\n"
218 "Please use the [depset](https://docs.bazel.build/versions/master/skylark/lib/depset.html) constructor\n"
219 "instead:\n\n"
220 "```python\n"
221 "depset(transitive = [depset1, depset2])\n"
222 "```\n\n"
223 "When fixing this issue, make sure you\n"
224 "[understand depsets](https://docs.bazel.build/versions/master/skylark/depsets.html)\n"
225 "and try to\n"
226 "[reduce the number of calls to depset](https://docs.bazel.build/versions/master/skylark/performance.html#reduce-the-number-of-calls-to-depset)."
227 bazel_flag: "--incompatible_depset_union"
228 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5817"
229}
230
231warnings: {
232 name: "dict-concatenation"
233 header: "Dictionary concatenation is deprecated"
234 description:
235 "The `+` operator to concatenate dicts is deprecated. The operator used to create a new dict and\n"
236 "copy the data to it. There are several ways to avoid it, for example, instead of `d = d1 + d2 + d3`\n"
237 "you can use one of the following:\n\n"
238 " * Use [Skylib](https://github.com/bazelbuild/bazel-skylib):\n\n"
239 "```python\n"
240 "load(\"@bazel_skylib//lib:dicts.bzl\", \"dicts\")\n\n"
241 "d = dicts.add(d1, d2, d3)\n"
242 "```\n\n"
243 " * The same if you don't want to use Skylib:\n\n"
244 "```python\n"
245 "d = dict(d1.items() + d2.items() + d3.items())\n"
246 "```\n\n"
247 " * The same in several steps:\n\n"
248 "```python\n"
249 "d = dict(d1) # If you don't want `d1` to be mutated\n"
250 "d.update(d2)\n"
251 "d.update(d3)\n"
252 "```"
253 bazel_flag: "--incompatible_disallow_dict_plus"
254 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/6461"
255}
256
257warnings: {
258 name: "dict-method-named-arg"
259 header: "Dict methods do not have a named argument `default`"
260 description:
261 "Dict methods `get`, `pop` and `setdefault` do not accept a named argument\n"
262 "called `default`. Due to a bug, Bazel currently accepts that named argument.\n"
263 "It is better to use a positional argument instead:\n\n"
264 "```diff\n"
265 "- mydict.get(5, default = 0)\n"
266 "+ mydict.get(5, 0)\n"
267 "```"
268}
269
270warnings: {
271 name: "duplicated-name"
272 header: "A rule with name `foo` was already found on line"
273 description:
274 "Each label in Bazel has a unique name, and Bazel doesn’t allow two rules to have\n"
275 "the same name. With macros, this may be accepted by Bazel (if each macro\n"
276 "generates different rules):\n\n"
277 "```python\n"
278 "my_first_macro(name = \"foo\")\n"
279 "my_other_macro(name = \"foo\")\n"
280 "```\n\n"
281 "Although the build may work, this code can be very confusing. It can confuse\n"
282 "users reading a BUILD file (if they look for the rule “foo”, they may read see\n"
283 "only one of the macros). It will also confuse tools that edit BUILD files.\n\n"
284 "To fix the issue just change the name attribute of one rule/macro."
285}
286
287warnings: {
288 name: "filetype"
289 header: "The `FileType` function is deprecated"
290 description:
291 "The function `FileType` is deprecated. Instead of using it as an argument to the\n"
292 "[`rule` function](https://docs.bazel.build/versions/master/skylark/lib/globals.html#rule)\n"
293 "just use a list of strings."
294 bazel_flag: "--incompatible_disallow_filetype"
295 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5831"
296}
297
298warnings: {
299 name: "function-docstring"
300 name: "function-docstring-header"
301 name: "function-docstring-args"
302 name: "function-docstring-return"
303 header: "Function docstring"
304 description:
305 "Public functions should have docstrings describing functions and their signatures.\n"
306 "A docstring is a string literal (not a comment) which should be the first statement\n"
307 "of a function (it may follow comment lines). Function docstrings are expected to be\n"
308 "formatted in the following way:\n\n"
309 "```python\n"
310 "\"\"\"One-line summary: must be followed and may be preceded by a blank line.\n"
311 "\n"
312 "Optional additional description like this.\n"
313 "\n"
314 "If it's a function docstring and the function has more than one argument, the docstring has\n"
315 "to document these parameters as follows:\n"
316 "\n"
317 "Args:\n"
318 " parameter1: description of the first parameter. Each parameter line\n"
319 " should be indented by one, preferably two, spaces (as here).\n"
320 " parameter2: description of the second\n"
321 " parameter that spans two lines. Each additional line should have a\n"
322 " hanging indentation of at least one, preferably two, additional spaces (as here).\n"
323 " another_parameter (unused, mutable): a parameter may be followed\n"
324 " by additional attributes in parentheses\n"
325 "\n"
326 "Returns:\n"
327 " Description of the return value.\n"
328 " Should be indented by at least one, preferably two spaces (as here)\n"
329 " Can span multiple lines.\n"
330 "\n"
331 "Deprecated:\n"
332 " Optional, description of why the function is deprecated and what should be used instead.\n"
333 "\"\"\"\n"
334 "```\n\n"
335 "Docstrings are required for all public functions with at least 5 statements. If a docstring exists\n"
336 "it should start with a one-line summary line followed by an empty line. If a docstring is required\n"
337 "or it describes some arguments, it should describe all of them. If a docstring is required and\n"
338 "the function returns a value, it should be described."
339}
340
341warnings: {
342 name: "git-repository"
343 header: "Function `git_repository` is not global anymore"
344 description:
345 "Native `git_repository` and `new_git_repository` functions are removed.\n"
346 "Please use the Starlark version instead:\n\n"
347 "```python\n"
348 "load(\"@bazel_tools//tools/build_defs/repo:git.bzl\", \"git_repository\")\n"
349 "```"
350 bazel_flag: "--incompatible_remove_native_git_repository"
351 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/6569"
352 autofix: true
353}
354
355warnings: {
356 name: "http-archive"
357 header: "Function `http_archive` is not global anymore"
358 description:
359 "Native `http_archive` function is removed.\n"
360 "Please use the Starlark version instead:\n\n"
361 "```python\n"
362 "load(\"@bazel_tools//tools/build_defs/repo:http.bzl\", \"http_archive\")\n"
363 "```"
364 bazel_flag: "--incompatible_remove_native_http_archive"
365 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/6570"
366 autofix: true
367}
368
369warnings: {
370 name: "integer-division"
371 header: "The `/` operator for integer division is deprecated"
372 description:
373 "The `/` operator is deprecated in favor of `//`, please use the latter for\n"
374 "integer division:\n\n"
375 "```python\n"
376 "a = b // c\n"
377 "d //= e\n"
378 "```"
379 bazel_flag: "--incompatible_disallow_slash_operator"
380 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5823"
381 autofix: true
382}
383
384warnings: {
385 name: "keyword-positional-params"
386 header: "Keyword parameter should be positional"
387 description:
388 "Some parameters for builtin functions in Starlark are keyword for legacy reasons;\n"
389 "their names are not meaningful (e.g. `x`). Making them positional-only will improve\n"
390 "the readability."
391 autofix: true
392}
393
394warnings: {
395 name: "list-append"
396 header: "Prefer using `.append()` to adding a single element list"
397 description: "Transforming `x += [expr]` to `x.append(expr)` avoids a list allocation."
398 autofix: true
399}
400
401warnings: {
402 name: "load"
403 header: "Loaded symbol is unused"
404 description:
405 "### Background\n\n"
406 "[load](https://docs.bazel.build/versions/master/skylark/concepts.html#loading-an-extension)\n"
407 "is used to import definitions in a BUILD file. If the definition is not used in\n"
408 "the file, the load can be safely removed. If a symbol is loaded two times, you\n"
409 "will get a warning on the second occurrence.\n\n"
410 "### How to fix it\n\n"
411 "Delete the line. When load is used to import multiple symbols, you can remove\n"
412 "the unused symbols from the list. To fix your BUILD files automatically, try\n"
413 "this command:\n\n"
414 "```bash\n"
415 "$ buildozer 'fix unusedLoads' path/to/BUILD\n"
416 "```\n\n"
417 "If you want to keep the load, you can disable the warning by adding a comment\n"
418 "`# @unused`."
419 autofix: true
420}
421
422warnings: {
423 name: "load-on-top"
424 header: "Load statements should be at the top of the file"
425 description:
426 "Obsolete; the warning has been implemented in the formatter and the fix "
427 "is now automatically applied to all files except `WORKSPACE` files "
428 "(unless suppressed).\n\n"
429 "Load statements should be first statements (with the exception of `WORKSPACE` files),\n"
430 "they can follow only comments and docstrings."
431 bazel_flag: "--incompatible_bzl_disallow_load_after_statement"
432 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5815"
433 autofix: true
434}
435
436warnings: {
437 name: "module-docstring"
438 header: "The file has no module docstring"
439 description:
440 "`.bzl` files should have docstrings on top of them. A docstring is a string literal\n"
441 "(not a comment) which should be the first statement of the file (it may follow\n"
442 "comment lines). For example:\n\n"
443 "```python\n"
444 "\"\"\"\n"
445 "This module contains build rules for my project.\n"
446 "\"\"\"\n"
447 "\n"
448 "...\n"
449 "```"
450}
451
452warnings: {
453 name: "name-conventions"
454 header: "Name conventions"
455 description:
456 "By convention, all variables should be lower_snake_case, constant should be\n"
457 "UPPER_SNAKE_CASE, and providers should be UpperCamelCase ending with `Info`."
458}
459
460warnings: {
461 name: "native-android"
462 header: "All Android build rules should be loaded from Starlark"
463 description:
464 "The Android build rules should be loaded from Starlark.\n\n"
465 "Update: the plans for disabling native rules\n"
466 "[have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ),\n"
467 "at the moment it's not required to load Starlark rules."
468 bazel_flag: "--incompatible_disable_native_android_rules"
469 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/8391"
470 autofix: true
471}
472
473warnings: {
474 name: "native-build"
475 header: "The `native` module shouldn't be used in BUILD files"
476 description:
477 "There's no need in using `native.` in BUILD files, its members are available\n"
478 "as global symbols there."
479 autofix: true
480}
481
482warnings: {
483 name: "native-cc"
484 header: "All C++ build rules should be loaded from Starlark"
485 description:
486 "The CC build rules should be loaded from Starlark.\n\n"
487 "Update: the plans for disabling native rules\n"
488 "[have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ),\n"
489 "at the moment it's not required to load Starlark rules."
490 bazel_flag: "--incompatible_load_cc_rules_from_bzl"
491 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/8743"
492 autofix: true
493}
494
495warnings: {
496 name: "native-java"
497 header: "All Java build rules should be loaded from Starlark"
498 description:
499 "The Java build rules should be loaded from Starlark.\n\n"
500 "Update: the plans for disabling native rules\n"
501 "[have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ),\n"
502 "at the moment it's not required to load Starlark rules."
503 bazel_flag: "--incompatible_load_java_rules_from_bzl"
504 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/8746"
505 autofix: true
506}
507
508warnings: {
509 name: "native-package"
510 header: "`native.package()` shouldn't be used in .bzl files"
511 description:
512 "It's discouraged and will be disallowed to use `native.package()` in .bzl files.\n"
513 "It can silently modify the semantics of a BUILD file and makes it hard to maintain."
514}
515
516warnings: {
517 name: "native-proto"
518 header: "All Proto build rules and symbols should be loaded from Starlark"
519 description:
520 "The Proto build rules should be loaded from Starlark.\n\n"
521 "Update: the plans for disabling native rules\n"
522 "[have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ),\n"
523 "at the moment it's not required to load Starlark rules."
524 bazel_flag: "--incompatible_load_proto_rules_from_bzl"
525 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/8922"
526 autofix: true
527}
528
529warnings: {
530 name: "native-py"
531 header: "All Python build rules should be loaded from Starlark"
532 description:
533 "The Python build rules should be loaded from Starlark.\n\n"
534 "Update: the plans for disabling native rules\n"
535 "[have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ),\n"
536 "at the moment it's not required to load Starlark rules."
537 bazel_flag: "--incompatible_load_python_rules_from_bzl"
538 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/9006"
539 autofix: true
540}
541
542warnings: {
543 name: "no-effect"
544 header: "Expression result is not used"
545 description: "The statement has no effect. Consider removing it or storing its result in a variable."
546}
547
548warnings: {
549 name: "out-of-order-load"
550 header: "Load statements should be ordered by their labels"
551 description:
552 "Obsolete; the warning has been implemented in the formatter and the fix "
553 "is now automatically applied to all files (unless suppressed).\n\n"
554 "Load statements should be ordered by their first argument - extension file label.\n"
555 "This makes it easier to developers to locate loads of interest and reduces chances\n"
556 "for conflicts when performing large-scale automated refactoring.\n\n"
557 "When applying automated fixes, it's highly recommended to also use\n"
558 "[`load-on-top`](#load-on-top) fixes, since otherwise the relative order\n"
559 "of a symbol load and its usage can change resulting in runtime error."
560 autofix: true
561}
562
563warnings: {
564 name: "output-group"
565 header: "`ctx.attr.dep.output_group` is deprecated"
566 description:
567 "The `output_group` field of a target is deprecated in favor of the\n"
568 "[`OutputGroupInfo` provider](https://docs.bazel.build/versions/master/skylark/lib/OutputGroupInfo.html)."
569 bazel_flag: "--incompatible_no_target_output_group"
570 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/7949"
571 autofix: true
572}
573
574warnings: {
575 name: "overly-nested-depset"
576 header: "The depset is potentially overly nested"
577 description:
578 "If a depset is iteratively chained in a for loop, e.g. the following pattern is used:\n\n"
579 "```python\n"
580 "for ...:\n"
581 " x = depset(..., transitive = [..., x, ...])\n"
582 "```\n\n"
583 "this can result in an overly nested depset with a long chain of transitive elements. Such patterns\n"
584 "can lead to performance problems, consider refactoring the code to create a flat list of transitive\n"
585 "elements and call the depset constructor just once:\n\n"
586 "```python\n"
587 "transitive = []\n"
588 "\n"
589 "for ...:\n"
590 " transitive += ...\n"
591 "\n"
592 "x = depset(..., transitive = transitive)\n"
593 "```\n\n"
594 "Or in simple cases you can use list comprehensions instead:\n\n"
595 "```python\n"
596 "x = depset(..., transitive = [y.deps for y in ...])\n"
597 "```\n\n"
598 "For more information, read Bazel documentation about\n"
599 "[depsets](https://docs.bazel.build/versions/master/skylark/depsets.html)\n"
600 "and\n"
601 "[reducing the number of calls to depset](https://docs.bazel.build/versions/master/skylark/performance.html#reduce-the-number-of-calls-to-depset)."
602}
603
604warnings: {
605 name: "package-name"
606 header: "Global variable `PACKAGE_NAME` is deprecated"
607 description:
608 "The global variable `PACKAGE_NAME` is deprecated, please use\n"
609 "[`native.package_name()`](https://docs.bazel.build/versions/master/skylark/lib/native.html#package_name)\n"
610 "instead."
611 bazel_flag: "--incompatible_package_name_is_a_function"
612 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5827"
613 autofix: true
614}
615
616warnings: {
617 name: "package-on-top"
618 header: "Package declaration should be at the top of the file"
619 description:
620 "Here is a typical structure of a BUILD file:\n\n"
621 " * `load()` statements\n"
622 " * `package()`\n"
623 " * calls to rules, macros\n\n"
624 "Instantiating a rule and setting the package defaults later can be very\n"
625 "confusing, and has been a source of bugs (tools and humans sometimes believe\n"
626 "package applies to everything in a BUILD file). This might become an error in\n"
627 "the future.\n\n"
628 "### What can be used before package()?\n\n"
629 "The linter allows the following to be before `package()`:\n\n"
630 " * comments\n"
631 " * `load()`\n"
632 " * variable declarations\n"
633 " * `package_group()`\n"
634 " * `licenses()`"
635}
636
637warnings: {
638 name: "positional-args"
639 header: "Keyword arguments should be used over positional arguments"
640 description:
641 "All top level calls (except for some built-ins) should use keyword args over\n"
642 "positional arguments. Positional arguments can cause subtle errors if the order\n"
643 "is switched or if an argument is removed. Keyword args also greatly improve\n"
644 "readability.\n\n"
645 "```diff\n"
646 "- my_macro(\"foo\", \"bar\")\n"
647 "+ my_macro(name = \"foo\", env = \"bar\")\n"
648 "```\n\n"
649 "The linter allows the following functions to be called with positional arguments:\n\n"
650 " * `load()`\n"
651 " * `vardef()`\n"
652 " * `export_files()`\n"
653 " * `licenses()`\n"
654 " * `print()`"
655}
656
657warnings: {
658 name: "print"
659 header: "`print()` is a debug function and shouldn't be submitted"
660 description:
661 "Using the `print()` function for warnings is discouraged: they are often spammy and\n"
662 "non actionable, the people who see the warning are usually not the people who can\n"
663 "fix the code to make the warning disappear, and the actual maintainers of the code\n"
664 "may never see the warning."
665}
666
667warnings: {
668 name: "provider-params"
669 header: "Calls to `provider` should specify a list of fields and a documentation"
670 description:
671 "Calls to `provider` should specify a documentation string and a list of fields:\n\n"
672 "```python\n"
673 "ServerAddressInfo = provider(\n"
674 " \"The address of an HTTP server. Fields are host (string) and port (int).\",\n"
675 " fields = [\"host\", \"port\"]\n"
676 ")\n"
677 "```\n\n"
678 "Fields should also be documented when needed:\n\n"
679 "```python\n"
680 "ServerAddressInfo = provider(\n"
681 " \"The address of an HTTP server.\",\n"
682 " fields = {\n"
683 " \"host\": \"string, e.g. 'example.com'\",\n"
684 " \"port\": \"int, a TCP port number\",\n"
685 " }\n"
686 ")\n"
687 "```\n\n"
688 "Note that specifying a list of fields is a breaking change. It is an error if a\n"
689 "call to the provider uses undeclared fields. If you cannot declare the list of\n"
690 "fields, you may explicitly set it to None (and explain why in a comment).\n\n"
691 "```python\n"
692 "AllInfo = provider(\"This provider accepts any field.\", fields = None)\n"
693 "\n"
694 "NoneInfo = provider(\"This provider cannot have fields.\", fields = [])\n"
695 "```\n\n"
696 "See the [documentation for providers](https://docs.bazel.build/versions/master/skylark/lib/globals.html#provider)."
697}
698
699warnings: {
700 name: "redefined-variable"
701 header: "Variable has already been defined"
702 description:
703 "### Background\n\n"
704 "In .bzl files, redefining a global variable is already forbidden. This helps\n"
705 "both humans and tools reason about the code. For consistency, we want to bring\n"
706 "this restriction also to BUILD files.\n\n"
707 "### How to fix it\n\n"
708 "Rename one of the variables.\n\n"
709 "Note that the content of lists and dictionaries can still be modified. We will\n"
710 "forbid reassignment, but not every side-effect."
711}
712
713warnings: {
714 name: "repository-name"
715 header: "Global variable `REPOSITORY_NAME` is deprecated"
716 description:
717 "The global variable `REPOSITORY_NAME` is deprecated, please use\n"
718 "[`native.repository_name()`](https://docs.bazel.build/versions/master/skylark/lib/native.html#repository_name)\n"
719 "instead."
720 bazel_flag: "--incompatible_package_name_is_a_function"
721 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5827"
722 autofix: true
723}
724
725warnings: {
726 name: "return-value"
727 header: "Some but not all execution paths of a function return a value"
728 description:
729 "Some but not all execution paths of a function return a value. Either there's\n"
730 "an explicit empty `return` statement, or an implicit return in the end of a\n"
731 "function. If it is intentional, make it explicit using `return None`. If you\n"
732 "know certain parts of the code cannot be reached, add the statement\n"
733 "`fail(\"unreachable\")` to them."
734}
735
736warnings: {
737 name: "rule-impl-return"
738 header: "Avoid using the legacy provider syntax"
739 description:
740 "Returning structs from rule implementation functions is\n"
741 "[deprecated](https://docs.bazel.build/versions/master/skylark/rules.html#migrating-from-legacy-providers),\n"
742 "consider using\n"
743 "[providers](https://docs.bazel.build/versions/master/skylark/rules.html#providers)\n"
744 "or lists of providers instead."
745}
746
747warnings: {
748 name: "same-origin-load"
749 header: "Same label is used for multiple loads"
750 description:
751 "Obsolete; the warning has been implemented in the formatter and the fix "
752 "is now automatically applied to all files except `WORKSPACE` files "
753 "(unless suppressed).\n\n"
754 "### Background\n\n"
755 "[load](https://docs.bazel.build/versions/master/skylark/concepts.html#loading-an-extension)\n"
756 "is used to import definitions in a BUILD file. If the same label is used for loading\n"
757 "symbols more the ones, all such loads can be merged into a single one.\n\n"
758 "### How to fix it\n\n"
759 "Merge all loads into a single one. For example,\n\n"
760 "```python\n"
761 "load(\":f.bzl\", \"s1\")\n"
762 "load(\":f.bzl\", \"s2\")\n"
763 "```\n\n"
764 "can be written more compactly as\n\n"
765 "```python\n"
766 "load(\":f.bzl\", \"s1\", \"s2\")\n"
767 "```"
768 autofix: true
769}
770
771warnings: {
772 name: "skylark-comment"
773 name: "skylark-docstring"
774 header: "\"Skylark\" is an outdated name of the language, please use \"starlark\" instead"
775 description:
776 "The configuration language for Bazel is called \"Starlark\" now, the name \"Skylark\" is\n"
777 "outdated and shouldn't be used."
778 autofix: true
779}
780
781warnings: {
782 name: "string-iteration"
783 header: "String iteration is deprecated"
784 description:
785 "Iteration over strings often leads to confusion with iteration over a sequence of strings,\n"
786 "therefore strings won't be recognized as sequences of 1-element strings (like in Python).\n"
787 "Use string indexing and `len` instead:\n\n"
788 "```python\n"
789 "my_string = \"hello world\"\n"
790 "for i in range(len(my_string)):\n"
791 " char = my_string[i]\n"
792 " # do something with char\n"
793 "```"
794 bazel_flag: "--incompatible_string_is_not_iterable"
795 bazel_flag_link: "https://github.com/bazelbuild/bazel/issues/5830"
796}
797
798warnings: {
799 name: "uninitialized"
800 header: "Variable may not have been initialized"
801 description:
802 "The local value can be not initialized at the time of execution. It may happen if it's\n"
803 "initialized in one of the if-else clauses but not in all of them, or in a for-loop which\n"
804 "can potentially be empty."
805}
806
807warnings: {
808 name: "unnamed-macro"
809 header: "The macro should have a keyword argument called \"name\""
810 description:
811 "By convention all macro functions should have a keyword argument called `name`\n"
812 "(even if they don't use it). This is important for tooling and automation.\n\n"
813 "A macro is a function that calls a rule (either directly or indirectly by calling other\n"
814 "macros).\n\n"
815 "If this function is a helper function that's not supposed to be used outside of its file,\n"
816 "please make it private (rename it so that the name starts with `_`), this will\n"
817 "prevent loading the function from BUILD files and suppress the warning."
818}
819
820warnings: {
821 name: "unreachable"
822 header: "The statement is unreachable"
823 description:
824 "The statement is unreachable because it follows a `return`, `break`, `continue`,\n"
825 "or `fail()` statement."
826}
827
828warnings: {
829 name: "unsorted-dict-items"
830 header: "Dictionary items should be ordered by their keys"
831 description:
832 "Dictionary items should be sorted lexicographically by their keys. This makes\n"
833 "it easier to find the item of interest and reduces chances of conflicts when\n"
834 "performing large-scale automated refactoring.\n\n"
835 "The order is affected by `NamePriority` dictionary passed using `-tables` or\n"
836 "`-add_tables` flags.\n\n"
837 "If you want to preserve the original dictionary items order, you can disable\n"
838 "the warning by adding a comment `# @unsorted-dict-items` to the dictionary\n"
839 "expression or any of its enclosing expressions (binary, if etc). For example,\n\n"
840 "```python\n"
841 "# @unsorted-dict-items\n"
842 "d = {\n"
843 " \"b\": \"bvalue\",\n"
844 " \"a\": \"avalue\",\n"
845 "}\n"
846 "```\n\n"
847 "will not be reported as an issue because the assignment operation that uses\n"
848 "the dictionary with unsorted items has a comment disabling this warning."
849 autofix: true
850}
851
852warnings: {
853 name: "unused-variable"
854 header: "Variable is unused"
855 description:
856 "This happens when a variable or function is set but not used in the file, e.g.\n\n"
857 "```python\n"
858 "x = [1, 2]\n"
859 "```\n\n"
860 "The line can often be safely removed.\n\n"
861 "If you want to keep the variable, you can disable the warning by adding a\n"
862 "comment `# @unused`.\n\n"
863 "```python\n"
864 "x = [1, 2] # @unused\n"
865 "\n"
866 "# @unused\n"
867 "def f(\n"
868 " x,\n"
869 " y, # @unused\n"
870 "):\n"
871 " pass\n"
872 "```\n\n"
873 "If an unused variable is used for partially unpacking tuples, just prefix\n"
874 "its name with an underscore to suppress the warning:\n\n"
875 "```python\n"
876 "x, _y = foo()\n"
877 "for _, (a, _b) in iterable:\n"
878 " print(a + x)\n"
879 "```\n\n"
880 "The same applies for function arguments that are not used by design:\n\n"
881 "```python\n"
882 "def foo(a, _b, *_args):\n"
883 " return bar(a)\n"
884 "```\n\n"
885 "If a tuple is unpacked not in a for-loop and all variables are unused,\n"
886 "it'll still trigger a warning, even if all variables are underscored:\n\n"
887 "```python\n"
888 "_a, _b = pair\n"
889 "_unused = 3\n"
890 "```"
891}
View as plain text