How to build a manifest file for a release consisting of only three yaml script files?

My team is developing three fairly large YAML scripts that are being published regularly for public use.

I need to create a manifest file as a way of version control for the releases of these scripts.

Most manifest formats (windows apps, assemblies, jar packages, and so on) follow a standard or a template, but I don't think that there's a default implementation for my scenario, where the published object are just YAML scripts.

I'm thinking on creating a new YAML script from scratch, with key: value pairs of metadata about this bundle of scripts.

What I'm thinking is specifying:

name
version number
version date
creator
files on the current version
dependencies

That's pretty much all I have, but that seems empty.

Is there a best approach to build a manifest in this scenario?

Should I consider an alternative way for version controlling these releases?

Solution

You can perfectly well use YAML to make a manifest file, and your can use the bullet items as key-value pairs for a mapping that represents each release.

You should think however about how you put the releases together, because unless you use a sequence there might not be a guaranteed, or useful way to order the releases in the manifest.

In the following I assume you want to follow the usual pattern of having the latest release at the top of the manifest file.

If you decide to use the version date as a key to a root-level mapping:
```
2019-03-14:
  name: new-name
  version: [0, 2, 0]
2019-02-28:
  name: some_name
  version : [0, 1, 0]
```
You'll find that it is non-trivial with most YAML libraries to insert a new key at the beginning of the mapping (one exception to this is my ruamel.yaml library for Python). This form precludes having multiple releases on one day, which might a problem at some future date.
If you decide to use the version number as key:
```
[0, 2, 0]:
  name: new-name
  date: 2019-03-04 
[0, 1, 0]:
  name: some_name
  date : 2019-02-28
```
You might find that some YAML libraries cannot handle these kind of keys. And changing them to strings like 0.2.0 might get you into bigger trouble when the keys are sorted, as soon as some of the numbers start to two digits

Probably the easiest way to get this done is with a root level sequence, that way insertion and ordering is fully controllable on each round-trip where you add a release:

    - name: new-name
      version: [0, 2, 0]
      date: 2019-03-04
    - name: some_name
      version: [0, 1, 0]
      date : 2019-02-28

If your releases are directly under the root level, there is normally not a need to fully load-update-write the release YAML file. Instead you can load the old file as text, then dump the single new entry to file, then append the loaded text to that newly created file.