puppetlabs / maintainers Goto Github PK

View Code? Open in Web Editor NEW

4.0 112.0 5.0 49 KB

A gem for maintaining MAINTAINERS files

License: Other

Ruby 99.30% Shell 0.70%

maintainers's Introduction

Maintainers

This is a gem for maintaining MAINTAINERS files.

Installation

    $ gem install maintainers

Usage

Some use cases:

Create an empty MAINTAINERS file

The only top-level configurable you might want to specify is the issues url.

maintainers create --issues https://github.com/gracehopper/newthing/issues

At this point you might drop some comments in the resultant MAINTAINERS file.

Add or remove a maintainer from a MAINTAINERS file

Add users identified by github id, optionally specifying name, email address, and a comment.

maintainers add --github gracehopper --email grace@usnavy.gov --name "Grace Hopper"
maintainers add --github gracehopper --email grace@usnavy.gov --name "Grace Hopper" --comment "Maintains ENIAC"

Remove user by specifying the github id:

maintainers remove --github gracehopper

List maintainers from a MAINTAINERS file

Emit a list of maintainers:

maintainers list

Produce a summary report of maintainers within the puppetlabs org

maintainers report

Validate the MAINTAINERS file

Run this from the root of your project.

maintainers validate

Getting a github token

Some commands (for now, just report) will make use of a github token if one is specified in an environment variable GITHUB_TOKEN.

To use this, you will need to generate a suitable github token like so:

Logged in at github.com, click on your avatar (upper right), then select 'Settings'
In the left-hand nav scroll down to 'Personal Access Tokens' and select that
Then select 'Generate new token'
Give the token a description, then be sure to select the 'repo' permissions as in the image below
Then click 'Generate Token' down below, and copy the resultant token to wherever you specify the GITHUB_TOKEN environment variable
Profit!

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/puppetlabs/maintainers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

maintainers's People

Contributors

Stargazers

Watchers

Forkers

davids adreyer theshanx admincgi isabella232

maintainers's Issues

Have rake tasks

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.

Add a validate subcommand

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.

Consider formally specifying the output format

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

... | 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.

Issue to hold images for readme

Cut a new release?

@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.

Potential confusion with version

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.

File format hint URL issues

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):

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.
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?