Add issue service

IMPORTANT Since version 2.0.0, all the API is promise-based.

Issue services are located in lib/issue-service.

Implement a new issue service

Fork and create a new module lib/issue-service/<your-service>, based on doc/issue-service/sample.js

You should take a look at lib/issue-service/github.js for inspiration (particularly user interaction using Inquirer for OAuth authentication).

Once you're happy with your implementation, create a new Pull Request and let's all party!

Service API

Your module must expose the following API (last 2 methods must be synchronous):

• meta is an optional descriptive object with following properties:
  • desc (optional) your service short description
  • repo (optional) expected format of the "repo" option for this service
  • conf (optional) list of configuration options that your service relies on (best for credentials storage)
• connect(configuration)
  • configuration contains user configuration
  • returns promise of an API client
• allIssues(client, repo)
  • client your API client (got from connect)
  • repo user's "repo" option (same for all other methods)
  • returns promise of Issues
• findIssueByTitle(client, repo, title)
  • returns promise of found Issue
• createIssue(client, repo, title, body, labels)
  • body is the text of the issue, in Github-flavored Markdown format
  • labels is an array of String, they should be created if necessary (*)
  • returns promise of created Issue
• commentIssue(client, repo, id, comment)
  • id is issue's identifier
  • comment is comment's texte, in Github-flavored Markdown format
  • returns promise of created Comment
• tagIssue(repo, id, label)
  • id is issue's identifier
  • label is the tag name that should be added to issue's labels, this method should not replace but add a new label to the list
  • returns promise of updated Issue
• (optional) validateConfig(conf)
  • called just before connect to validate options
  • conf is the global options object
  • returns promise of valid configuration
• guessRepoFromUrl(url)
  • url the git remote url
  • returns value (or promise of value) for "repo" option, or falsey otherwise
• getFileUrl(client, repo, path, sha, line)
  • path is project relative path to file
  • sha is the commitish to which we want to generate link (*)
  • line is the target line number (*)
  • returns the most precise URL available to source file

(*) obviously only if your service supports this feature

Data model

• Issue
  • type: String = "issue"
  • number: Number
  • url: String
  • title: String
  • labels: Array of String
• Comment
  • type: String = "comment"
  • issue: Number
  • url: String

Additional configuration

You may need to store data in user configuration, as it's done with Github service for OAuth token and API access.

• Prefix your option with service identifier
• Document your options in doc/cli/help.config.txt
• Declare your options in your service's meta.conf: they will automatically added as non-extra and globals
• For more fine-grained control you'll have to declare your options in lib/config.js:
  • Default values in module.exports.defaults
  • Add to module.exports.globals if they should be global
  • Add to module.exports.booleans the flag-options

Test your service

Enable it in a sample repository:

github-todos config service <your-service>

Then create commits, and simulate push:

DRY_RUN=1 DEBUG=* git push

Don't forget to check it generates nice user-friendly documentation in github-todos list-services, edit your meta to tweak it.