.fmf formatting

[martinhoyer]

Identify is a python file identification library. It is being used by pre-commit.
I would like to add .fmf to the list of extensions there, but have a couple of questions:

• @psss fmf is your baby, can you see any issues with adding it?
• fmf being based on yaml and being parsed by ruamel.yaml - wouldn't it make sense to add yaml? i.e.:

 EXTENSIONS = {
+    'fmf': {'text', 'fmf', 'yaml'},

as opposed to just

+    'fmf': {'text', 'fmf'},

Adding it would mean any pre-commit hooks that are being run against yaml files would also run against .fmf files without explicitly configuring it (which might sometimes not even be possible ...yamlfix 👀)

fyi .fmf directory is correctly identified.

$ identify-cli .fmf
["directory"]
$ identify-cli plans/iscsi/tier0.fmf 
["file", "fmf", "non-executable", "text", "yaml"]

I'm not sure where else is identify lib being used, but in pre-commit, this would allow running checks against .fmf files much easier by being able to use types and types_or filters.
Also, it would allow to make tmt/.pre-commit-hooks.yaml a bit cleaner.

[psss]

Thanks for the idea. Sounds good to me. Yes, fmf files will alwas have to be yaml, so I guess it makes sense to identify them as such. And if this makes it easier for pre-commit to recognize them, the better!

[martinhoyer]

oh well, nevermind pre-commit/identify#395
There are indeed other uses for .fmf extension. Found this for example: https://github.com/Tonsil/flipper-music-files

As for formatting, linting .fmf files, I've settled with yamlfix:
pre-commit-config.yaml:

  - repo: https://github.com/lyz-code/yamlfix/
    rev: 1.11.0
    hooks:
      - id: yamlfix
        types:
          - text
        files: \.fmf$

pyproject.toml:

[tool.yamlfix]
explicit_start = "false"
line_length = 100
preserve_quotes = "true"
sequence_style = "block_style" 

which leaves yaml/yml files alone and only checks/formats .fmf files.

@psss does it make sense to have some tmt-recommended formatting standard, or is it "anything yaml parsable is good"? :)

[happz]

+1 for avoiding formatting. Validation sounds like a useful addition, I'd leave the formatting to project owners - they can employ their own yamlformatwhatever & custom rules.

[psss]

Ack, let's go with yaml validation for now.

[martinhoyer]

I'd leave the formatting to project owners

Sure, but it is still nice to have a reference formatting. For example for people like me it's quite confusing when there are inconsistencies, regardless whether the ruamel says the syntax is valid or not.
I mean, even fmf files in tmt repo are not consistently formatted :)

In the end, it might make things ever so slightly harder for newcomers that just want to use tmt, not learn yaml.

FYI, looking at the yaml spec, what should actually be used for the multi-line text blocks is >. So in the example above, it would be:

summary: >
    Support for multiple configurations
description: >
    All steps support multiple configurations. In this way it is
    possible for example to discover tests from multiple repos.
    The 'execute' steps supports only a single configuration.

(though I would not use it for single lines, like 'summary' personally)

[happz]

I'd leave the formatting to project owners

Sure, but it is still nice to have a reference formatting. For example for people like me it's quite confusing when there are inconsistencies, regardless whether the ruamel says the syntax is valid or not. I mean, even fmf files in tmt repo are not consistently formatted :)

I agree, it's nice & important to have files in a project formatted in a consistent way. I'm not so sure about giving it a fancy label like "reference formatting" though - I always felt this is very project- and team-specific, some teams rule with an iron fist & use nothing but 2 spaces for YAML indentation, while other teams swear by 4 spaces, and at least one of these groups would immediately break the rules of our reference formatting. I for one see no benefit in such an offering :) I'm all for keeping tmt repo formatted consistently, absolutely, including examples in docs and docstrings if at all possible, but I for one wouldn't bother recommending it to others in such an official-ish way.

In the end, it might make things ever so slightly harder for newcomers that just want to use tmt, not learn yaml.

I believe the consistent formatting in repo would be a good example, worth following, making things much easier for others to adopt. I'd even say it might be enough to help newcomers, without labeling it with a "recommended formatting" or "best practices" stamp.

FYI, looking at the yaml spec, what should actually be used for the multi-line text blocks is >. So in the example above, it would be:

summary: >
    Support for multiple configurations
description: >
    All steps support multiple configurations. In this way it is
    possible for example to discover tests from multiple repos.
    The 'execute' steps supports only a single configuration.

(though I would not use it for single lines, like 'summary' personally)

The description I would consider a question for validation to resolve, as picking the right multiline form in YAML can be tricky. summary would be formatting in my books, I wouldn't use a multiline string for this either, but some teams might. As long as it'd be consistent in the repo, I'd be fine with pretty much anything. Well, except Black :)

[martinhoyer]

@happz

I'm not so sure about giving it a fancy label like "reference formatting" though

I'd even say it might be enough to help newcomers, without labeling it with a "recommended formatting" or "best practices" stamp.

Indeed. When I wrote "reference", I meant what's in the existing documentation, examples dir. Together with yamlfix config in pyproject.toml, which wouldn't need to be "advertised" as such.