friederbluemle / sprinter.js

Tools for Github issue and milestone consolidation across projects.

Sprinter

Provides some extended utilities for the Github API for operating against multiple Github issue trackers at once.

If you're like me, this library might save you an hour a week. I'm a "scrum master", which sounds silly but is actually a real thing. We have a lot of repos on Github. Most of them have issue trackers. So it takes a long time to update all of them for common recurring tasks like sprint changes. This library takes your Github credentials [2] and gives you easy ways to set up tasks that execute against multiple Github Issue Trackers at once, so you can:

Run the following actions across multiple repos:

• list issues
• list milestones
• create milestones
• close milestones
• update milestones
• create labels

[1] There is no [1].

[2] Should I be using a different authentication method? If so, please file a bug.

Example Usage

Sprinter is used as the backend to report on issues across all the repositories in the Numenta Github Organization on our status board.

Installation

As a library for local scripts

npm install sprinter

Now you can require('sprinter') and use as defined below in the examples.

As a command line tool

npm install -g sprinter

Now you can run sprinter from the command line.

sprinter --help

Displays usage information.

Sprinter CLI Tool: Utilities for operating on issue trackers of several repositories at once.

REQUIREMENTS
Environment variables with the Github username and password for API calls:
	GH_USERNAME=<username>
	GH_PASSWORD=<password>

USAGE
    sprinter <command> <cmd-options> --repos=org/repo,org2/repo2
 or
    sprinter <command> <cmd-options> --repos=./path/to/repo/file

The repo file should have one repo slug on each line. Instead of providing a --repos option, you could
set the $SPRINTER_REPOS environment variable instead.

COMMANDS
printRepos
	Prints the repositories Sprinter is configured to run against.
listIssues [--milestone="milestone name"] [--assignee="github username"]
	Prints all issues. Optionally filters by milestone name.
listMilestones
	Prints all milestones.
createMilestones <title> <due_on>
	Creates new milestone in each repo with given title and due date.
	`due_on` should be a JS-formattable date string like 'Apr 16, 2014'.
closeMilestones <title>
	Closes all milestones matching title across all repos.
updateMilestones <title> <new-title> [due_on]
	Updates all milestones matching title across all repos.

EXAMPLE
sprinter createMilestones "Sprint 43" "April 16, 2014" --repos=rhyolight/highlinker,rhyolight/chesster

WARNING: The CLI is not complete. There are some functions within the library that are not exposed as CLI functions.

CLI Usage

1. Create a file with a list of repositories you want to use sprinter against. It should look something like mine:

   nupic-repos.txt

    numenta/nupic
    numenta/nupic.cerebro
    numenta/nupic.documents
    # You can add comments 
    numenta/nupic.core
    numenta/nupic.fluent
    numenta/nupic.fluent.server
    numenta/nupic-linux64
    numenta/nupic-darwin64
    
    # Whitespace between lines is okay
    
    numenta/pycept
    numenta/nupic.tools
    numenta/nupic.wallboard
    numenta/numenta.org
   

   You can also provide the list of repositories directly with the --repos option:

    $> sprinter listIssues --milestone="Sprint 19" --repos=org1/repo1,org1/repo2
   

   If you don't want to always specify the --repos option, set the same value into the $SPRINTER_REPOS environment variable. If --repos is not given with a CLI command, the $SPRINTER_REPOS value will be used instead.

2. Run sprinter commands with the --repos= option, pointing to the file.

    $> sprinter listIssues --milestone="Sprint 19" --repos=nupic-repos.txt
   

   

3. Run with --help for more commands and options.

Examples Of Using as a Library

Creating the Client

var Sprinter = require('sprinter');

var sprinter = new Sprinter(
    <username>,
    <password>,
    ['org1/repo1', 'org1/repo2', 'org2/repo1']
);

Listing All Issues Across All Repos

sprinter.getIssues(function(err, issues) {
    console.log(issues);
});

Listing All Milestones Across All Repos

Milestones will be grouped by title.

sprinter.getMilestones(function(err, milestones) {
    console.log(milestones);
});

Creating A Milestone Across All Repos

sprinter.createMilestones({
    title: 'Sprint 20',
    due_on: 'Apr 16, 2014'
}, function(err, milestones) {
    console.log(milestones);
});

Updating A Milestone Across All Repos

Provide a milestone title and new milestone properties, and you can update all milestones with that name across every repository.

sprinter.updateMilestones('Milestone name to update', {
    title: 'New milestone name',
    due_on: 'May 5, 2015',
    description: 'New milestone description'
}, function(err, milestones) {
    console.log(milestones);
});

Closing Milestones by Title Across All Repos

Closes all milestones with the title Sprint 18 across all monitored repos.

sprinter.closeMilestones('Sprint 18', function(err, closed) {
    console.log('Closed milestones:');
    console.log(closed);
});

Creating Labels Across All Repos

var labels = [
    {
        name: "cleanup",
        color: "c7def8"
    },
    {
        name: "newbie",
        color: "bfe5bf"
    },
    {
        name: "tests",
        color: "fad8c7"
    }
]

sprinter.createLabels(labels, function (err, labels) {
    console.log(labels);
});