README.md
1<!---
2Copyright (C) 2018 and later: Unicode, Inc. and others.
3License & terms of use: http://www.unicode.org/copyright.html
4-->
5
6# Commit Checker Tool
7
8This tool checks the ICU Git repository against the ICU Jira issue tracker to ensure that the two are consistent with one another.
9
10Author: Shane Carr
11
12## Installation
13
14Install `pipenv` globally:
15
16 $ sudo pip3 install pipenv
17
18Install this project's dependencies locally:
19
20 $ pipenv install
21
22Optional: save your Jira credentials in a `.env` file in this directory:
23
24 JIRA_USERNAME=hello@example.com
25 JIRA_PASSWORD=world
26
27This is required if you want to process sensitive tickets. Note: JIRA_PASSWORD needs to be an API Token generated according to the following instructions:
28
29https://confluence.atlassian.com/cloud/api-tokens-938839638.html
30
31## Usage
32
33Make sure you have updated your repository:
34
35 $ git fetch --tags upstream
36
37Run the tool and save the result into REPORT.md; set fixVersion to the upcoming ICU version, and take the revision range between the previous release and the tip for the upcoming release:
38
39 $ pipenv run python3 check.py \
40 --jira-query "project=ICU AND fixVersion=64.1" \
41 --rev-range "release-63-1..upstream/maint/maint-64"
42 > REPORT.md
43
44If the maintenance branch hasn't been cut yet, use upstream/master as the tip:
45
46 --rev-range "release-64-2..upstream/master"
47
48Note 1: These examples assume that your remote named "upstream" points to unicode-org/icu, the source of truth.
49
50Note 2: Please change the previous-release tag (release-63-1, release-64-2, etc) to the correct version at the time you run the tool!
51
52### Preview the Report
53
54To preview the report, render the Markdown file in your favorite Markdown preview tool, like grip:
55
56 $ pip3 install grip
57 $ grip REPORT.md
58 * Running on http://localhost:6419/ (Press CTRL+C to quit)
59
60### Sending for Review
61
62Before sending the report to ICU-TC, do some basic cleanup yourself by adjusting fix versions and resolutions on Jira issues.
63
64- Tickets with commits should be closed as Fixed, and fixed tickets without commits should be closed as Fixed by Other Ticket. These tickets should have a fix version.
65- Tickets closed for any other reason, such as Duplicate, should not have a fix version. Semantically, duplicate tickets inherit the fix version from the ticket to which they are duplicated.
66
67It should be possible to clear the first two sections of the report simply by correcting the ticket resolutions and fix versions in Jira.
68
69When ready, create a branch and push to your fork so others can view the report easily. Team members should close issues they own that are correctly fixed. Re-generate the report periodically until it comes back clean.
70
71Note: REPORT.md is not intended to be merged back into master.
72