Skip to content

issue-keys.md

Latest commit

 

History

History
55 lines (37 loc) · 2.71 KB

issue-keys.md

File metadata and controls

55 lines (37 loc) · 2.71 KB
Raw

Issue keys

An issue key names one issue in an issue tracker. This doc gives the forms of a key, the purpose of the short ref, and the rules that resolve a key to one repo.

Key forms

  • GitHub: owner/repo#N.
  • Jira: PROJ-N.
  • Jira with a site: <site>/browse/PROJ-N.

N is a number with no leading zero. PROJ is in upper case, and it can hold _. The site of a key can have any case.

skills/tasker/SKILL.md gives the same forms to users in its "Issue keys" section. A change to the forms must change both files.

Short refs

The short ref comes from the issue key. It names the worktree folder of the task, and it starts the branch name. A short ref has one of two forms: issue-<N> for a GitHub key, and <PROJ>-<N> for a Jira key, with a - for each _ of the project.

The repo of a key

The resolve gives the one configured repo that owns the key. It runs with no network.

The project of a repo is its issueTracker.project. The project row of the configuration gives the default.

tasker does not guess the provider from the shape of a key. It tries the key against each repo, with the key parser of the provider of that repo. One provider object serves many repos, so the parser takes the project. The resolve uses the key parsers directly, not the provider registry.

A github repo matches when the owner/repo part of the key equals the project. The compare folds only the ASCII letters A to Z to lower case. toLowerCase() is not safe, because the Kelvin sign U+212A lowers to k. With the ASCII fold, a match means that the project has the same ASCII characters as the key. As a result, the stored key of a github repo is always a GitHub key.

A jira repo matches when the project of the key equals the project of the repo, with the same case. The project of the key is the text before the last -. A key with a site also needs the site. It matches only a repo with the same issueTracker.site, with no regard to case. A repo with no site does not match a key with a site.

No file in src/issue-key/ imports from src/issues/, because that import pulls in the registry and the gh code. A boundary test enforces this rule.

The unknown repo check of --repo uses the own keys of the configuration only, so constructor and __proto__ are unknown repo keys.

Stored spelling

The stored GitHub key is <project>#<N>, with the spelling of the configuration. For example, CodeGuru42/Tasker#5 and codeguru42/tasker#5 give one task. The short ref comes from the same number.

The stored Jira key is the bare key PROJ-N, also for a key with a site. tasker stores each key with its repo, and each repo names at most one site, so the bare key names one issue.