Reporting Issues¶

How to give feedback that helps us fix things.

What to Report¶

Bugs: - Things that don't work - Crashes - Incorrect behavior - Error messages

Usability issues: - Confusing commands - Unclear error messages - Missing documentation - Unexpected behavior

Feature requests: - Things you wanted but couldn't do - Suggestions for improvement

Capture It First with /bug¶

When something looks wrong, type this in the Urchin terminal before you do anything else:

/bug <what went wrong>

For example, /bug message to alex never arrived. The client writes a JSON snapshot to a bugs folder in the Kunuleco data directory and prints the file's path. If you are logged in, it also asks the node to write its own snapshot with the same 8-character id, so the two halves pair up. The node replies with the path of its file.

The client's file holds the client version, OS, connection state, your identity, your friends list with identifiers shortened, and the last 50 terminal lines. Other people's whispers in those lines are replaced with a placeholder. Passwords typed on the commands that take one (PASS, PASSWD, ADDUSER, export-identity, import-identity) are replaced with ******** before the file is written, but anything else you typed is kept. The node's file holds its version, its sessions, presences and friends list, and the last 50 lines of its log.

/bug sends nothing anywhere. Both files stay on your machine until you send them. Read each file first, then attach it to your report.

Over SSH, type bug <what went wrong>. The node writes its snapshot and replies with the path, and there is no client file.

Where the files are:

File	Linux	Windows
Client `bug-client-*.json`	`~/.local/share/kunuleco/bugs/`	`%LOCALAPPDATA%\Kunuleco\bugs\`
Node `bug-server-*.json`	the path the node prints, under its data directory	the path the node prints, under its data directory
Node log `node.log`	`~/.local/share/kunuleco/logs/`	`%LOCALAPPDATA%\Kunuleco\logs\`

On macOS the client's files are under ~/Library/Application Support/Kunuleco/. Use the path each reply prints rather than guessing.

Good Bug Reports¶

A useful bug report includes:

1. Summary¶

One sentence describing the problem.

"Connection fails silently when Veilid route expires"

2. Steps to Reproduce¶

Exact sequence of actions, numbered.

1. Start Urchin and log in
2. create ~presence plaza, then invite plaza -short, and send the code to a peer
3. The peer runs join <code>
4. Wait 10 minutes without activity
5. chat hello
6. Message appears to send but never arrives

3. Expected Behavior¶

What should have happened.

"Message should arrive at peer, or error should indicate connection lost."

4. Actual Behavior¶

What happened.

"Message appears to send successfully, but peer never receives it. No error shown."

5. Environment¶

OS: Ubuntu 22.04
Urchin version: from /about
Node version: from @version
Transport: from ping <name> or transport
Other node's OS/version if relevant

6. Bug Files and Logs¶

Attach the bug-client-*.json and bug-server-*.json files that /bug wrote. If you need more of the node log than the last 50 lines, open node.log and copy the part around the time of the problem.

Bug Report Template¶

## Summary
[One sentence description]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [...]

## Expected Behavior
[What should happen]

## Actual Behavior
[What happens]

## Environment
- OS:
- Urchin version (/about):
- Node version (@version):
- Transport:

## Bug id
[The 8-character id /bug printed; attach both JSON files]

## Additional Context
[Screenshots, related issues, etc.]

Where to Report¶

Email: alpha@kunul.eco

Discord: https://discord.gg/U8xa4mqMNp

Before Submitting¶

Check known issues. See Known Issues
Check for updates. Run /check-updates, because the issue may already be fixed
Read your bug files. Make sure they hold nothing you don't want to share

Feature Requests¶

For feature requests, include:

1. Problem Statement¶

What problem would this solve?

"I can't tell when my peers are online without trying to send them a message."

2. Proposed Solution¶

How you think it could work.

"Add a presence indicator that shows online/offline status."

3. Alternatives Considered¶

What else you tried.

"I tried running friends online often, but that's manual and disruptive."

Usability Feedback¶

For confusing or frustrating experiences:

What were you trying to do?
What confused you?
What would have helped?

Example:

"I tried to delete a room with delete garden, but there is no delete command. After reading the docs I found destroy room garden. A hint pointing to destroy would have helped."

Not Sure If It's a Bug?¶

Report it anyway. We'd rather know about potential issues than miss real bugs.

Say you're not sure in the report.

Response Times¶

Alpha is a small team effort. Expect:

Acknowledgment: 1-3 days
Triage: 1 week
Fix: Depends on severity and complexity

Critical bugs (crashes, data loss) get priority.

Thank You¶

Every report helps. Even "I was confused by X" is valuable. You're helping build something better.