227 lines
6.7 KiB
Markdown
227 lines
6.7 KiB
Markdown
# Issue tracker: Gitea
|
|
|
|
Issues and specs for this repository live in Gitea Issues.
|
|
|
|
- Server: https://gitea.agavagroup.com
|
|
- Repository: tararar/Aleksandr-test
|
|
- Git remote: origin
|
|
- CLI: existing tea 0.15.1
|
|
- Login: agavagroup
|
|
|
|
Use tea for issue operations. Do not substitute GitHub gh commands
|
|
or GitLab glab commands.
|
|
|
|
## PowerShell session
|
|
|
|
If tea is unavailable in PATH, use the verified executable directly.
|
|
The existing login configuration is located under the following
|
|
XDG_CONFIG_HOME:
|
|
|
|
```powershell
|
|
$env:XDG_CONFIG_HOME = 'C:\Users\tarar\AppData\Local'
|
|
$tea = 'C:\Users\tarar\AppData\Local\Programs\tea\tea.exe'
|
|
```
|
|
|
|
These are process-local settings. Do not change persistent environment
|
|
variables or login configuration as part of issue operations.
|
|
|
|
Use the existing login. Never print, copy into project files, or pass
|
|
the API token as a command-line argument. Do not enable debug logging.
|
|
|
|
## Conventions
|
|
|
|
The commands below use the PowerShell variable $tea defined above.
|
|
Replace placeholders with actual values.
|
|
|
|
### Read an issue
|
|
|
|
```powershell
|
|
& $tea issues --login agavagroup --repo tararar/Aleksandr-test --comments <number>
|
|
```
|
|
|
|
### Read comments
|
|
|
|
```powershell
|
|
& $tea comments list --login agavagroup --repo tararar/Aleksandr-test --output json --limit 100 --page 1 <number>
|
|
```
|
|
|
|
### List issues
|
|
|
|
```powershell
|
|
& $tea issues list --login agavagroup --repo tararar/Aleksandr-test --state open --kind issues --output json --fields index,state,author,url,title,body,created,updated,assignees,labels --limit 100 --page 1
|
|
```
|
|
|
|
Use --labels "needs-triage" to filter by a label.
|
|
|
|
List commands are paginated. Read subsequent pages until an empty page
|
|
is returned when complete results are required.
|
|
|
|
### Create an issue
|
|
|
|
```powershell
|
|
& $tea issues create --login agavagroup --repo tararar/Aleksandr-test --title "<title>" --description "<body>"
|
|
```
|
|
|
|
Add --labels "<label1>,<label2>" when labels are required.
|
|
|
|
### Edit an issue body
|
|
|
|
```powershell
|
|
& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --description "<complete updated body>" <number>
|
|
```
|
|
|
|
Read the current body first. Preserve unrelated content and discussion.
|
|
The description argument replaces the body.
|
|
|
|
### Add a comment
|
|
|
|
```powershell
|
|
& $tea comments add --login agavagroup --repo tararar/Aleksandr-test --description "<body>" <number>
|
|
```
|
|
|
|
### Apply or remove labels
|
|
|
|
```powershell
|
|
& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --add-labels "<label>" <number>
|
|
& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --remove-labels "<label>" <number>
|
|
```
|
|
|
|
Use separate operations for addition and removal: tea gives
|
|
--add-labels precedence over --remove-labels.
|
|
|
|
During triage, preserve unrelated labels and ensure the final result has
|
|
exactly one category label and one state label. If existing state labels
|
|
conflict, ask the maintainer before changing them.
|
|
|
|
### Assign an issue
|
|
|
|
```powershell
|
|
& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --add-assignees "<username>" <number>
|
|
```
|
|
|
|
Use a verified Gitea username. Do not assume that the login alias
|
|
agavagroup is a username or that @me is supported.
|
|
|
|
### Close or reopen an issue
|
|
|
|
```powershell
|
|
& $tea issues close --login agavagroup --repo tararar/Aleksandr-test <number>
|
|
& $tea issues reopen --login agavagroup --repo tararar/Aleksandr-test <number>
|
|
```
|
|
|
|
When closing with an explanation, post the comment first and close
|
|
the issue only after the comment succeeds.
|
|
|
|
### List or create labels
|
|
|
|
```powershell
|
|
& $tea labels list --login agavagroup --repo tararar/Aleksandr-test --output json --limit 100 --page 1
|
|
& $tea labels create --login agavagroup --repo tararar/Aleksandr-test --name "<name>" --color "<hex color>" --description "<description>"
|
|
```
|
|
|
|
Check existing labels before creating any. Use agreed colors and
|
|
descriptions; do not create duplicates.
|
|
|
|
### Multiline text
|
|
|
|
Use a PowerShell single-quoted here-string or read an approved UTF-8
|
|
body file into a variable, then pass that variable to --description.
|
|
|
|
Do not use Bash heredoc syntax in PowerShell. Do not evaluate issue text
|
|
as shell code.
|
|
|
|
## Pull requests as a triage surface
|
|
|
|
PRs as a request surface: no.
|
|
|
|
Do not include pull requests in automatic triage discovery.
|
|
If the maintainer explicitly requests work on a pull request, inspect
|
|
the installed tea help and establish the necessary workflow first.
|
|
|
|
## When a skill says "publish to the issue tracker"
|
|
|
|
Create a Gitea issue using the conventions above.
|
|
|
|
## When a skill says "fetch the relevant ticket"
|
|
|
|
Read the Gitea issue and its comments.
|
|
|
|
## Wayfinding operations
|
|
|
|
Use issue bodies and links to represent the map and its relationships.
|
|
This workflow does not rely on unverified native sub-issue or dependency
|
|
features of the server.
|
|
|
|
### Map
|
|
|
|
The map is one issue carrying the wayfinder:map label and the sections
|
|
required by the installed wayfinder skill: Notes, Decisions-so-far, Fog,
|
|
and its ordered ticket list.
|
|
|
|
### Child ticket
|
|
|
|
Create one issue per decision ticket.
|
|
|
|
Put `Part of #<map-number>` near the top of the body.
|
|
Add a link to the child issue in the map's ordered task list.
|
|
|
|
Use one of the type labels:
|
|
|
|
- wayfinder:research
|
|
- wayfinder:prototype
|
|
- wayfinder:grilling
|
|
- wayfinder:task
|
|
|
|
Check for these labels and create missing ones only when authorized
|
|
Wayfinder work requires them.
|
|
|
|
### Blocking
|
|
|
|
Put `Blocked by: #<number>, #<number>` near the top of the child body.
|
|
Omit this line when there are no blockers.
|
|
|
|
A ticket is unblocked only when all listed blocker issues are closed.
|
|
Read blocker state from Gitea; do not infer it from stale map text.
|
|
|
|
### Frontier
|
|
|
|
Read the map's ordered ticket list and inspect its children.
|
|
|
|
A frontier candidate must be:
|
|
|
|
- open;
|
|
- unblocked;
|
|
- unassigned.
|
|
|
|
Choose the first eligible ticket in map order.
|
|
|
|
### Claim
|
|
|
|
Assign the ticket to the verified driving developer's username before
|
|
starting work. This is the first write of a ticket-working session.
|
|
|
|
Re-read the ticket immediately before claiming it. This workflow does
|
|
not provide an atomic claim; if a competing assignment is observed,
|
|
stop and resolve ownership with the maintainer.
|
|
|
|
### Resolve
|
|
|
|
1. Post the answer as a comment.
|
|
2. Close the child issue after the comment succeeds.
|
|
3. Update its task-list entry in the map.
|
|
4. Append a concise decision and a link to the answer in Decisions-so-far.
|
|
|
|
Preserve the rest of the map body.
|
|
|
|
In human-facing output, refer to maps and tickets by their titles,
|
|
with links, rather than bare issue numbers.
|
|
|
|
## API capability boundary
|
|
|
|
tea 0.15.1 provides an authenticated api command. Prefer the verified
|
|
issue commands above.
|
|
|
|
Before using an additional API endpoint, verify its method, path,
|
|
request shape, and availability against the target server's API
|
|
documentation. Do not assume GitHub API endpoints work on Gitea.
|