docs(jtk): true up README, CHANGELOG, and integration tests #183
Description
Context
PRs #178, #180, and #182 landed features/fixes that aren't reflected in the docs:
- fix(jtk): prevent wiki markup conversion from mangling hyphens and tildes #178: Wiki markup hyphens/tildes fix
- fix(jtk): include custom fields in search/list JSON output #180:
--fieldsflag +*alldefault for JSON output onissues searchandissues list - fix(jtk): auto-paginate search/list past Jira's 100-result page cap #182: Auto-pagination (
--maxnow means total results, not page size)
Additionally, the jtk fields top-level command group (list, create, delete, restore, contexts, options) has never been documented in the README despite being fully implemented.
Release safety: All changes are .md files only with a docs: commit prefix. Neither path gate (.go only) nor commit gate (feat:/fix: only) will fire.
Changes
1. README.md — issues list section
- Update
--maxdescription:"Page size (number of results per page)"→"Maximum number of results to return" - Add
--fieldsflag row - Add examples for auto-pagination and
--fieldsusage
2. README.md — issues search section
- Update
--maxdescription (same as list) - Add
--fieldsflag row - Add examples for auto-pagination and
--fieldsusage
3. README.md — Add jtk fields command group
Insert a new section after jtk issues field-options. Documents:
| Subcommand | Flags |
|---|---|
fields list |
--custom |
fields create |
--name (req), --type (req), --description |
fields delete <field-id> |
--force |
fields restore <field-id> |
(none) |
fields contexts list <field-id> |
(none) |
fields contexts create <field-id> |
--name (req) |
fields contexts delete <field-id> <context-id> |
--force |
fields options list <field-id> |
(none) |
fields options add <field-id> |
--value (req) |
fields options update <field-id> |
--option (req), --value (req) |
fields options delete <field-id> |
--option (req), --force |
Aliases: field, f
4. CHANGELOG.md — Add entries under [Unreleased]
Added:
--fieldsflag onissues listandissues searchfor explicit field selection (#180)- Auto-pagination for
issues listandissues search—--maxreturns up to N results across pages (#182)
Fixed:
issues searchandissues listwith-o jsonnow return all fields including custom fields by default (#180)- Wiki markup conversion no longer mangles hyphens and tildes (#178)
5. integration-tests.md — New tests for #180 and #182
Add to Section 2 (Issues Read-Only) after existing issues search tests:
Auto-pagination tests
| # | Command | Expected Output |
|---|---|---|
| 1 | jtk issues search --jql "project = $PROJECT" --max 200 -o json | jq '.issues | length' |
Number >= 101 (proves multi-page) |
| 2 | jtk issues search --jql "project = $PROJECT" --max 200 -o json | jq '.pagination' |
total matches count, pageSize <= 100 |
| 3 | jtk issues search --jql "project = $PROJECT" --max 200 |
Table output > 100 rows |
| 4 | jtk issues list -p $PROJECT --max 200 -o json | jq '.issues | length' |
Same multi-page for list |
--fields flag tests
| # | Command | Expected Output |
|---|---|---|
| 1 | jtk issues search --jql "project = $PROJECT" --max 1 -o json | jq '.issues[0].fields | keys' |
Includes customfield_* keys |
| 2 | jtk issues search --jql "project = $PROJECT" --max 1 --fields summary,status -o json | jq '.issues[0].fields | keys' |
Only summary, status |
| 3 | jtk issues list -p $PROJECT --max 1 -o json | jq '.issues[0].fields | keys' |
Same *all default |
| 4 | jtk issues list -p $PROJECT --max 1 --fields summary,customfield_10005 -o json | jq '.issues[0].fields | keys' |
Only requested fields |
Add to Test Execution Checklist for both Basic Auth and Bearer Auth passes.
Files to modify
| File | Change |
|---|---|
tools/jtk/README.md |
Update search/list flags + examples; add fields command group |
tools/jtk/CHANGELOG.md |
Add entries for PRs #178, #180, #182 |
tools/jtk/integration-tests.md |
Add auto-pagination and --fields tests + checklist items |
Verification
git diff --stat— only.mdfiles- Visual review of README against
jtk <cmd> --helpoutput - Commit with
docs:prefix — no release triggered