Add example of metadata.json file that is referenced by metadata2gha

[bschonec]

Generating Github Actions outputs shows output of parsing a metadata.json file but the puppet_metadata projects doesn't include a metatadata.json file that was used to generate said output.

It'd be nice to have a metadata.json or metadata.json.EXAMPLE included in the project to be able to reproduce the output provided in the README.md.

[ekohl]

When I wrote the documentation I thought the structure would be way more important than the actual data. So I showed how it's generated and then made the output readable.

Since then the output has changed because of GitHub internals. Yesterday I was thinking about writing a description of what it would do. So describe the operating systems it found and whether it will (or won't run tests on them). Perhaps that's more useful than this.

[bschonec]

When I wrote the documentation I thought the structure would be way more important than the actual data. So I showed how it's generated and then made the output readable.

Since then the output has changed because of GitHub internals. Yesterday I was thinking about writing a description of what it would do. So describe the operating systems it found and whether it will (or won't run tests on them). Perhaps that's more useful than this.

It would be most useful if the documentation described what OSes will and won't run. I was surprised to find out that

bundle exec metadata2gha --use-fqdn

did not output anything for Fedora when I added the following to my metadata.json

    {   
      "operatingsystem": "Fedora",
      "operatingsystemrelease": [
        "38"
      ]   
    },  

Based on #106, I'm learning that some OSes don't run but again, as an amateur, it's been a difficult experience trying to learn the 'whys' and 'why nots' of how this entire process behaves.

[ekohl]

I was surprised to find out that

bundle exec metadata2gha --use-fqdn

did not output anything for Fedora when I added the following to my metadata.json

That surprises me, because the whole idea is that you pass in a metadata and it parses that. That's the whole concept of the gem: abstractions on top of your metadata.json. The metadata2gha command extracts useful information to generate variables to run GitHub Actions.

What was your expectation that it was operating on?

[bschonec]

Here's the metadata.json that I used. It's highly likely that I'm doing something wrong...hence the/my need for an example metadata.json file to be added.

I understand that the $operatingsystemrelease of Fedora isn't valid, but no value of $operatingsystemrelease seems to work.

[bschonec]

What was your expectation that it was operating on?

My completely amateur/noob expectation was that any value for $operatingsystem would be considered valid and that value be parsed and output for each $operatingsystemrelease value as well. Obviously now, I was incorrect in that assumption. Somewhere (and possibly still related to #106) there is code that filters out Fedora and other 'non-supported' OSes. I've not found documentation yet that gives a list of supported OSes. Again, probably this is in the code but the info should be documented somewhere.

[ekohl]

Here's the metadata.json that I used. It's highly likely that I'm doing something wrong...hence the/my need for an example metadata.json file to be added.

There is no known working build for Fedora 8.

My completely amateur/noob expectation was that any value for $operatingsystem would be considered valid and that value be parsed and output for each $operatingsystemrelease value as well. Obviously now, I was incorrect in that assumption. Somewhere (and possibly still related to #106) there is code that filters out Fedora and other 'non-supported' OSes. I've not found documentation yet that gives a list of supported OSes. Again, probably this is in the code but the info should be documented somewhere.

Correct: it only outputs combinations that we know we can test on. That's a core design principle. You take metadata.json and extract combinations we can run CI on.

So we first have to distinguish unit tests and acceptance tests.

For the unit tests this gem doesn't look at the operating systems. Instead it assumes you solve that yourself, either by doing it manually or relying on https://github.com/voxpupuli/rspec-puppet-facts.

Then for acceptance tests we we on beaker. If we can test depends on several factors.

It needs an OS image to work with. In GHA we now rely on containers and beaker.rb generates input for beaker-hostgenerator to generate the Beaker configuration. Note we can also work with other hypervisors and locally I tell beaker-hostgenerator to work with libvirt instead. It's just that in GHA we only have access to Docker, so that's why we're tied to containers.

Then it needs the availability of a Puppet build. We mostly rely on official builds for operating systems, encoded in aio.rb. For some we've added distro Puppet package support and both https://github.com/voxpupuli/puppet_metadata/pull/104 & https://github.com/voxpupuli/puppet_metadata/pull/102 expand that to fill the gap of missing official Puppet packages.

And combining all of the above into a configuration that can be used in GHA is what github_actions.rb does. We the have gha-puppet that uses this configuration to dynamically drive the matrices.

The end result is that you can add an OS to metadata.json to add support for it and it should be tested if the above conditions are met.