From 7e6ff6690d224d95bc47287b74dac0512603cd6b Mon Sep 17 00:00:00 2001 From: Morgan Patch Date: Fri, 14 Jul 2017 10:58:35 -0700 Subject: [PATCH] readme: Initial write-up The README likely needs some futher cleaning up and some clarification, but this version at least explains how the tool works and how to use it. --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 228d3ce..e09f23e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,61 @@ # issue-sync -A tool for synchronizing issues between GitHub and JIRA + +Issue-sync is a tool for synchronizing GitHub and JIRA issues. It grew +out of a desire to maintain a public GitHub repo while tracking private +issues in a JIRA board; rather than require people to keep up with both +sources, we decided to make *one* the single source of truth. + +## Usage + +To use, first ensure you have a JIRA server with the project you want +to track on it - it can be a cloud account, or self-hosted. Also make +sure you have a user account that can access the project and create +issues on it; it's recommended that you create an account specifically +for the issue-sync tool. + +Add the following custom fields to the project: `GitHub ID`, `GitHub +Number`, `GitHub Labels`, `GitHub Status`, `GitHub Reporter`, and `Last +Issue-Sync Update`. These fields are required and the names must match +exactly. In addition, `GitHub ID` and `GitHub Number` must be number +fields, `Last Issue-Sync Update` must be a date time field, and the +remainder must be text fields. + +Arguments to the program may be passed on the command line or in a +JSON configuration file. For the command line arguments, run `issue-sync +help`. The JSON format is a single, flat object, with the argument long +names as keys. + +Configuration arguments are as follows: + +Name|Value Type|Example Value| Required|Default +----|----------|-------------|---------|------------- +log-level|string|"warn"|false|"info" +github-token|string| |true|null +jira-user|string|"user@jira.example.com"|true|null +jira-pass|string|"theUserPassword123"|true|null +repo-name|string|"coreos/issue-sync"|true|null +jira-uri|string|"https://jira.example.com|true|null +jira-project|string|"SYNC"|true|null +since|string|"2017-07-01T13:45:00-0800"|false|"1970-01-01T00:00:00+0000" + +Note that the `repo-name` must include the owner and repo, that +`jira-uri` is the base URI of the JIRA instance, that `jira-project` is +the project's Key, not its name, and that `since` is in ISO-8601 format. + +If the JIRA instance lives on a subdirectory of the server, that must +be included in the jira-uri. For example, at "https://example.com/jira". + +"since" is the date including and after which the tool will look for +issue updates. + +By default, issue-sync looks for the configuration file at +`$HOME/.issue-sync.json`. To override this location, use the `--config` +option on the command line. + +If both a configuration file and command line arguments are provided, +the command line arguments override the configuration file. + +After a successful run, the current configuration, with command line +arguments overwritten, is saved to the configuration file (either the +one provided, or `$HOME/.issue-sync.json`); the "since" date is updated +to the current date when the tool is run, as well. \ No newline at end of file