puppetlabs-toy-chest / maintainers Goto Github PK

@MikaelSmith 's commit on 10/28 indicates that a 0.3.0 release was being prepared. Can we cut a new release? Latest on rubygems.org is still 0.2.3, released mid-September, and it's missing some important functionality.

It'd be great to have rake tasks, at least for validate, and maybe create (using the current user's git identity, and github remotes). The former for CI, the latter for convenience.

The report subcommand currently skips repos with < 5 forks. This is done in an attempt to speed up reporting, but it means the report is necessarily incomplete.

This isn't incorrect, but github flags it with red and some editors may add it if not present resulting in an extraneous diff.

Frankly this has been written in some haste, and test coverage has fallen by the wayside. Leaving this as a reminder that I should circle back and add some more tests.

With a specification, content can be generated by other tools, or by hand, and it also makes clear what the gem ought to be producing (including say the indentation level "width", no tabs, etc.).

The specification may want to take into account the line-oriented nature of git and other revision control systems, i.e. it may make sense to require a locale-independent sort order (by key) for map entries.

If the current Ruby pretty-printer doesn't support that, and if an additional dependency would be OK, then the output could be piped through something like jq or Python's built in pretty printer (which has a sort_keys option) on the way out, but only if we think their output is likely to remain sufficiently stable.

And of course if the chosen sort function turns out to be locale sensitive, we may be able to do something like this (I believe mtool.json may specify sort_keys=True):

... | LC_ALL=C python -mtool.json > dest.json

or

... | LC_ALL=C jq --sort-keys ... > dest.json

I can also envision a Ruby-only alternative. Assuming that Ruby always traverses hashes in insertion order (second paragraph here: http://ruby-doc.org/core-2.3.1/Hash.html), and assuming that pretty_generate just traverses maps in that order, then as a final step, we might just recursively copy the data structure, building the copy's hashes by inserting the elements in a well specified order, and then pass that copy to pretty_generate.

After hand-editing a MAINTAINERS file, it'd be nice to confirm it still validates against the schema, so it doesn't trip up any automated github maintainer reporting or future use of the tool to add/remove maintainers.

The MAINTAINERS file gets a file_format value like so:

"file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",

This isn't validated and is purely informational, but I see two potential issues (which you may choose to ignore):

1. The URL doesn't point at the schema, discovering that is left as an exercise for the users. Pointing at https://github.com/puppetlabs/maintainers/blob/master/schema/MAINTAINERS.json (and maybe renaming to schema) might be more useful in my opinion.
2. If we ever did (ha) change the GitHub org name to puppet or something else this metadata would be incorrect. I'm wondering if we want a short link on puppet.com which we can repoint?

The MAINTAINERS file ends up with a version field, which is currently 1.

"version": 1

This is the version of the schema, rather than the version of the file itself. I'm wondering whether that should be explicit, ie. schema_version.