Code Formatting and Linting

Code Formatting and Linting

[Patrick Williams]

[-- Attachment #1: Type: text/plain, Size: 2991 bytes --]

Hello beings who write code!

I've been working on significantly revamping the `format-code`[1] script
from openbmc-build-scripts, which we rely on for CI, to make it so we
can easily leverage a lot more common formatters and linters.  I've also
made it so that you should be able to more easily run this directly
(outside of Docker) if you have the linters installed natively (along
with some useful options and colorized output).

An example of running the tool against sdbusplus and the `--help` output
can be found at [2].

One big change I'd like to highlight is that I'm moving the linters to
an opt-out model by default instead of an opt-in.  In the past we've had
repositories add magic files like `.shellcheck` to indicate that they'd
like a particular linter to run.  The result is that very few
repositories full leverage the linters we have in place.  Instead, we
will enable the linters by default on repositories, and allow
maintainers to add either a global ".linter-ignore" or tool-specific
".<linter>ignore" file to opt-out.  These ignore files follow the
conventions from `.gitignore` files so that you can select specific
files.

I've already pushed code in Gerrit that makes all repositories pass
using this opt-out model for all the linters that we previously had in
place.  Prior to enabling any new linters, I will also send up changes
that make those linters pass on all the repositories.

Curently we have the following linters enabled:
    - gitlint (commit message)
    - codespell (on commit messages only)
    - clang-format (opt-in via .clang-format; C/C++)
    - eslint (JSON)
    - pycodestyle (opt-in via setup.cfg; Python)
    - shellcheck (opt-in via .shellcheck; bash/sh)

After all the code in [3] is merged, we will have the following linters
enabled (opt-out unless specified):
    - gitlint (commit message)
    - codespell (commit message)
    - beautysh (bash/sh/zsh)
    - black (Python)
    - clang-format (opt-in via .clang-format; C/C++)
    - eslint (JSON)
    - flake8 (Python)
    - isort (Python)
    - markdownlint (Markdown)
    - prettier (JSON/Markdown/YAML)
    - shellcheck (bash/sh)

If you have ideas for languages or linters we commonly use that are not
covered, please feel free to reach out to me and we can probably enable
it pretty easily.  

For anyone using vscode or neovim, you can also enable all these linters and
formatters right in your editor and get real-time reports[4] or fixes, which is
really handy (emacs can probably do this too...).  I use neovim and if
anyone wants pointers to my configs, feel free to reach out.

1. https://github.com/openbmc/openbmc-build-scripts/blob/master/scripts/format-code.sh
2. https://gist.github.com/williamspatrick/91b72cb2ed18ae794e91d1f04b78e3d7
3. https://gerrit.openbmc.org/c/openbmc/openbmc-build-scripts/+/59230
4. https://gist.github.com/williamspatrick/1916470b304383d8613fdb86451b7e91
-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Code Formatting and Linting

[Patrick Williams]

[-- Attachment #1: Type: text/plain, Size: 813 bytes --]

On Wed, Dec 07, 2022 at 04:48:18PM -0600, Patrick Williams wrote:

> After all the code in [3] is merged, we will have the following linters
> enabled (opt-out unless specified):
>     - gitlint (commit message)
>     - codespell (commit message)
>     - beautysh (bash/sh/zsh)
>     - black (Python)
>     - clang-format (opt-in via .clang-format; C/C++)
>     - eslint (JSON)
>     - flake8 (Python)
>     - isort (Python)
>     - markdownlint (Markdown)
>     - prettier (JSON/Markdown/YAML)
>     - shellcheck (bash/sh)

Everything except for markdownlint is now enabled in CI.  I'm going to
enable markdownlint in an always-passing mode shortly so that
maintainers can start to get signal on the issues and then we'll see how
soon we can enable that one as well.

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]