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

Quick start

Copy the template.yml file from this repository into the root directory of your project's repository as .about.yml. Then refer to the cheat sheet for instructions regarding how to fill in the data.

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

Alternatively, you can add the following to your Rakefile to tie .about.yml validation into your build process (this assumes that Rakefile and .about.yml are both in the top-level project directory):

# Development-only tasks
begin
  require 'about_yml/tasks/check_about_yml'
  task test: :run_about_yml_check
rescue LoadError
end

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.

.about.yml file testing

The run_about_yml_check Rake task provides a relatively simple way to check a project's .about.yml file for errors.

Add the task to your Rakefile

To test whether the .about.yml file for a repository will successfully parse based on the schema, simply include the about_yml gem in your dependencies and then load the task in your Rakefile:

check_yml = Gem::Specification.find_by_name 'about_yml'
load "#{check_yml.gem_dir}/lib/about_yml/tasks/check_about_yml.rake"

If your project already include about_yml, make sure it is using version 0.0.8 or later.

Run the task automatically with Travis

To run the run_about_yml_check task automatically using Travis, simply add the following to your .travis.yml config file (with any preferred notifications):

script: bundle exec rake run_about_yml_check

.about.yml cheat sheet

The following attributes are currently stored in the .about.yml file and are used in one or more of the locations referenced above. Required attributes are marked with an asterisk, and field descriptions and examples follow each attribute. Take a look at Every Kid in a Park or Open Opportunities for living examples of .about.yml in action.

name* - This is a short name of your project that is used as a URL slug on the 18F dashboard.

name: ekip-api

full_name* - This is the display name of your project on the 18F dashboard.

full_name: Every Kid in a Park

description* - What is the problem your project solves? What is the solution? Use the format shown below. The #dashboard team will gladly help you put this together for your project. 

description: |
  In 2015, President Obama formally announced the Every Kid in a Park program, which provides 
  fourth graders and their families with free access to more than 2,000 federally managed sites. 
  18F worked with the Department of the Interior to create the program’s website, which was 
  written at a fourth grade level with the help of fourth graders.

impact* - What is the measurable impact of your project? Use the format shown below. The #dashboard team will gladly help you put this together for your project.

impact: |
  We designed a website that gives fourth graders and their families free access to more than 2,000 
  federally-managed sites.

owner_type* - What kind of team owns the repository? Accepted values: guild, working-group, project

owner_type: project

stage* - What is your project's current status? Accepted values: discovery, alpha, beta, live

stage: live

testable* - Should this repo have automated tests? If so, set to true. Accepted values: true, false

testable: true

licenses* - What are the licences that apply to the project and/or its components? Get the license name from the Software Package Data Exchange (SPDX)

licenses:
  ekip-api:
    name: CC0-1.0
    url: https://github.com/18F/team_api/blob/master/LICENSE.md

partners - Who is the parter for your project? (Use the full name of the partner documented here)

partners:
- U.S. Department of the Interior

contact - The main point of contact(s) for your project, and a mailto: link for that contact.

contact:
- url: mailto:[email protected]
  text: Shashank Khandelwal

team - Who are the team members on your project? For each team member, list a github name, role and an internal identifier. (The project lead role should be lead)

team:
- github: khandelwal
  role: lead
  id: khandelwal

milestones - What are the key milestones you've achieved recently?

milestones:
- "December 2015: Discovery completed"

type - What kind of content is contained in the project repository? Accepted values: app, docs, policy

type: app

parent - Name of the main project repo if this is a sub-repo; name of the working group/guild repo if this is a working group/guild subproject

parent: [GitHub repo name]

links - What are the key links associated with your project?

links:
- url: everykidinapark.gov
  text: Every Kid in a Park

blogTag - What is the 18F blog tag for your project? You can find a list of tags here

blogTag: [18F Blog Tag]

stack - What technologies are used in this project?

stack:
- Django

services - What are the services used to supply project status information?

services:
- name: Coveralls
  category: Build review
  url: https://coveralls.io/github/18F/ekip-api?branch=master
  badge: https://coveralls.io/repos/18F/ekip-api/badge.svg?branch=master&service=github
- name: Quantified Code
  category: Site review
  url: https://www.quantifiedcode.com/app/project/ecb305ac0bfa4e968192621402faface
  badge: https://www.quantifiedcode.com/api/v1/project/ecb305ac0bfa4e968192621402faface/badge.svg

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.