Reporting Issues and Requesting Features

On this page

• Before You File
• 1. Update Wire
• 2. Check Open Issues
• 3. Reproduce It
• 4. Try the Obvious Fix
• How to File a Good Ticket
• Bug Reports
• Feature Requests
• What Makes a Ticket Actionable
• What Happens After You File
• Triage Process
• What You Can Expect
• What We Ask of You
• Filing from the Command Line
• If You Don't Use GitHub
• GitHub Issue Templates
• Verifying Deployments (GitHub Pages)

Wire is opinionated software. When something goes wrong, Wire should tell you clearly. When you hit a problem Wire does not catch, that is a bug worth reporting. This guide explains how to file good tickets and what happens after you do.

Before You File

1. Update Wire

Wire ships fixes continuously. Before filing, update to the latest build:

python -m wire.chief update

This reinstalls Wire from the hosted wheel. (It runs pip install --force-reinstall --no-cache-dir against https://wire.wise-relations.com/dist/wire-0.0.0-py3-none-any.whl for you.)

There is no version number to check. The wheel filename is permanently wire-0.0.0 so the install URL never changes, which means import wire; wire.__version__ always prints 0.0.0 and tells you nothing about how fresh your build is. What matters is the install date: Wire warns you at the start of any command when your install is more than a week old, and update pulls the latest. If the issue disappears after updating, it was already fixed.

2. Check Open Issues

Browse existing issues before creating a new one. Your problem may already be tracked, and adding context to an existing ticket is more useful than a duplicate.

gh issue list --state open

If you find a related issue, comment on it with your site name and what you see. Even if the symptoms differ, the root cause may be the same.

3. Reproduce It

Try the exact command again. If it fails consistently, it is a real bug. If it only happened once, it may be stale bytecode, a network glitch, or a file lock.

If it only happened once, try the command again before filing.

4. Try the Obvious Fix

Some common causes are not bugs:

• "Command not found": Are you in the site directory (where wire.yml lives)? Check your setup in the configuration guide.
• "No API key": Is .env present with ANTHROPIC_API_KEY? Or have you run claude login for CLI-first mode?
• "No GSC data": Have you run python -m wire.chief data at least once? New sites have no Search Console history yet. The workflow guide explains when data becomes available.
• "Build refused": Read the error message. Wire refuses loud with a reason and usually tells you exactly what to fix.

How to File a Good Ticket

Bug Reports

A good bug report has five things:

1. Which site. Your domain or repo path. Without this, we cannot read your config, check your database state, or reproduce the issue. Example: helm-nagel.com.

2. What command you ran. The exact CLI command with all flags. Example: python -m wire.chief audit --lang de --topic branchen.

3. What happened. Paste the full terminal output. Wire errors are designed to be self-explanatory. If the error message is confusing, that is also a bug.

4. What you expected. One sentence is enough. Example: "Expected audit to show GSC data for DE pages."

5. What you tried. So we do not suggest things you already ruled out. Example: "Ran data --lang de twice, checked .wire/gsc.db exists."

Feature Requests

A good feature request describes the pain, not the solution:

• Bad: "Add a --fix-links flag to the build command."
• Good: "After translating 132 pages, I have 250 lint warnings for cross-language links. Fixing them manually is not realistic."

We may solve your problem differently than you imagined. Describing the pain gives us room to find the right approach. If you have a proposed solution, include it, but lead with the problem.

What Makes a Ticket Actionable

What Happens After You File

Triage Process

We periodically review all open issues together. Here is what happens:

1. We read your site. Your wire.yml, your .wire/ directory, your build output. We look at real data, not just your description.

2. We cluster issues by root cause. If five tickets describe symptoms of the same architectural gap, we file one architectural fix that addresses all of them. Your ticket stays open for its remaining scope.

3. We comment on your ticket. You will see one of:

   • "Update from #N": An architectural fix partially addresses your issue. We explain what changes and what remains.
   • "Covered by #N": Your issue is fully addressed by another ticket. We close yours with an explanation.
   • "Refined scope": Your issue is valid but we adjusted the approach. We explain why.

4. We write an execution roadmap. Issues get ordered by dependency. Some must land before others. We post the order so you know what comes first.

What You Can Expect

• Every ticket gets a response. Even if the answer is "this is not a Wire problem."
• Root cause over symptoms. We may not fix your exact request, but we will fix the underlying problem.
• Your data informs the fix. We test with your actual site, not just the dogfood site. If it works on our site but breaks on yours, that is a Wire bug.
• Transparent decisions. If we close your ticket, we explain why. If we change the approach, we explain why.

What We Ask of You

• One issue per problem. Do not bundle unrelated problems into one ticket. "Build crashes AND the footer is ugly" is two issues.
• Comment if things change. If you find a workaround, if the problem gets worse, if you have new context, comment on the ticket. Stale tickets get deprioritized.
• Update Wire before commenting "still broken." We ship fixes between triage rounds. Reinstall from the wheel, retry.

Filing from the Command Line

If you use the GitHub CLI, file the issue with gh issue create. Pass --repo explicitly. Run from your own site directory without it and gh files the issue against your repository, not Wire's. The Wire issues repository is the one set in extra.wire.issues_repo in your wire.yml (your operator configured this during setup). Substitute it below.

# Bug report
gh issue create --repo your-org/wire-issues \
  --title "issue: build crashes on German pages with tabs shortcode" \
  --body "Site: helm-nagel.com
Command: python -m wire.build
Expected: Clean build
Actual: KeyError on line 2450
Install: reinstalled today via 'wire.chief update'
Tried: Removed tabs shortcode from one page — build passes"

# Feature request
gh issue create --repo your-org/wire-issues \
  --title "feat: auto-fix cross-language links after translation" \
  --body "Site: helm-nagel.com
Problem: 250 RULE-36 warnings after translating DE pages. All are mechanical link rewrites.
Workaround: None — fixing 250 links manually across 132 files is not realistic."

If You Don't Use GitHub

You do not need the GitHub CLI, or even a GitHub account, to get help.

• Open the issues repository in a browser. It is the value of extra.wire.issues_repo in your wire.yml, at https://github.com/<that-value>. Click "New issue" and fill in the same fields described above.
• Ask whoever runs Wire for you. If your site is managed (someone else runs the pipeline and deploys for you), send them the same five bug-report details and they will file or fix it. You do not need repo access yourself.

Either way, the information that makes a ticket actionable is identical: which site, what command, what happened, what you expected, what you tried.

GitHub Issue Templates

When you create an issue on GitHub, you will see structured templates for bug reports and feature requests. Follow GitHub's issue best practices for more guidance. These templates enforce the fields above so nothing gets missed. Use them.

Verifying Deployments (GitHub Pages)

After pushing, verify the deployment succeeded:

gh run list --limit 3             # See recent workflow runs
gh run watch                      # Watch the current run live
gh run view --log                 # Read build logs if it failed

Gitignored files (like og-image.png) will not be in CI. Wire version in CI may differ from local. Pin your version in requirements.txt.

See the Guides overview for all Wire documentation.