.about.yml
schema and tools
The .about.yml
mechanism allows a project to publish and maintain metadata
that can be easily maintained by project owners, that is visible and
accessible to interested parties, and that can be harvested and processed by
tools and automated systems. It is implemented using the
YAML format.
The 18F Team API is the original, primary consumer of this information, which in turn provides data for:
We hope that every active 18F project, working
group, and
guild will publish
.about.yml
files in their respective repositories. By feeding this
information through the Team API server and into our Hub, Dashboard, and main
web site, cultivation of .about.yml
files will help make our activity more
easily transparent to our teammates, and to anyone outside our team who wishes
to discover what we're working on (and how we work).
Installation
Run gem install about_yml
on the command line. You can also add gem
'about_yml'
to your project's Gemfile
if you use
Bundler and wish to configure the about_yml_validate
program as a pre-commit check.
Usage
Most users will interact with the gem through one of the following command-line programs.
about_yml_generate
This program will generate an empty .about.yml
template with descriptions of
each field. To add a new .about.yml
file to your project where MY-PROJECT
is the path to your local clone of your project's repository:
$ about_yml_generate > MY-PROJECT/.about.yml
about_yml_validate
This program checks one or more .about.yml
files against the .about.yml
schema. To check your project's .about.yml
file:
$ about_yml_validate MY-PROJECT/.about.yml
about_yml_scrape
This program checks for an .about.yml
file in every GitHub repository
belonging to a specified organization, then downloads, validates, and
categorizes all of the discovered files into a single YAML object. You must
have a valid
GitHub API token
to run this command.
$ about_yml_scrape 18F > 18F_about_yml_data.yml
github_org_descriptions
This program doesn't have anything to do with the .about.yml
schema, but is
a small, handy program that also uses the
octokit
gem to access the GitHub API.
It will return a YAML list of names and descriptions for all of the
repositories belonging to an organization.
Public domain
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.