diff --git a/tools/commit-checker/README.md b/tools/commit-checker/README.md index 4365f9b35db..3acd526def7 100644 --- a/tools/commit-checker/README.md +++ b/tools/commit-checker/README.md @@ -24,7 +24,9 @@ Optional: save your Jira credentials in a `.env` file in this directory: JIRA_USERNAME=hello JIRA_PASSWORD=world -This is required if you want to process sensitive tickets. +This is required if you want to process sensitive tickets. Note: JIRA_PASSWORD needs to be an API Token generated according to the following instructions: + +https://confluence.atlassian.com/cloud/api-tokens-938839638.html ## Usage @@ -39,4 +41,31 @@ Run the tool and save the result into REPORT.md; set fixVersion to the upcoming --rev-range "release-63-1..upstream/maint/maint-64" > REPORT.md -Create a branch and open a pull request so others can view the report easily. +If the maintenance branch hasn't been cut yet, use upstream/master as the tip: + + --rev-range "release-64-2..upstream/master" + +Note 1: These examples assume that your remote named "upstream" points to unicode-org/icu, the source of truth. + +Note 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! + +### Preview the Report + +To preview the report, render the Markdown file in your favorite Markdown preview tool, like grip: + + $ pip3 install grip + $ grip REPORT.md + * Running on http://localhost:6419/ (Press CTRL+C to quit) + +### Sending for Review + +Before sending the report to ICU-TC, do some basic cleanup yourself by adjusting fix versions and resolutions on Jira issues. + +- 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. +- 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. + +It should be possible to clear the first two sections of the report simply by correcting the ticket resolutions and fix versions in Jira. + +When 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. + +Note: REPORT.md is not intended to be merged back into master.