How to Report Bugs in Tolaria: A Complete Guide to GitHub Issues and Security Disclosures

File standard bugs as GitHub Issues following the CONTRIBUTING.md template, but send security vulnerabilities privately via email to luca@refactoring.club with the subject [Tolaria Security] as required by SECURITY.md.

Tolaria is an open-source knowledge management application that relies on community feedback to improve stability and features. Understanding how to report bugs in Tolaria ensures maintainers can reproduce and fix issues efficiently. The repository provides clear guidelines in CONTRIBUTING.md for standard defects and SECURITY.md for security-critical vulnerabilities.

Filing Standard Bug Reports via GitHub Issues

According to the contribution guidelines in CONTRIBUTING.md (lines 9-10), all non-security bugs should be opened as GitHub Issues in the public repository. This creates a transparent tracking stream that other users can search to avoid duplicate reports.

Required Information for Reproducible Reports

The CONTRIBUTING.md file (lines 32-41) specifies five essential components for effective bug reports. Providing these details reduces back-and-forth and accelerates triage:

• Tolaria version – Found in the app’s About dialog
• Operating system version – Specific OS and version where the bug occurs
• Step-by-step reproduction steps – Numbered actions that consistently trigger the issue
• Expected versus actual outcomes – Clear description of what should happen versus what actually happens
• Screenshots or recordings – Optional but highly helpful visual evidence

Use the following GitHub CLI command or the markdown template below to structure your report:

# Using the GitHub CLI to open a new bug issue

gh issue create \
  --title "Bug: Note list does not refresh after external edit" \
  --label "bug" \
  --body $'## Tolaria version\n1.3.0\n## OS\nmacOS 14.5\n## Steps to reproduce\n1. Open a vault\n2. Edit a markdown file with an external editor\n3. Return to Tolaria\n\n## Expected\nThe note list updates automatically.\n## Actual\nThe list still shows the old content.\n\n## Screenshots\n<attach png>'

<!-- Example issue body template (markdown) -->

## Tolaria version

`v0.4.2`

## OS version

macOS 14.5 (or Windows 11, Ubuntu 22.04)

## Steps to reproduce

1. Open a vault.
2. Edit `notes/example.md` with VS Code.
3. Switch back to Tolaria.

## Expected behavior

The note list refreshes automatically.

## Actual behavior

The note list still shows the previous content until a manual **Reload Vault**.

## Screenshots / recordings

[Attach images or GIFs here]

## Additional context

Any relevant logs from the developer console (`Cmd+Option+I` → Console)…

Reporting Security Vulnerabilities Privately

For security-related bugs, the public issue tracker is inappropriate. The SECURITY.md policy (lines 5-20) mandates that vulnerabilities must not be posted publicly. Instead, reporters should email luca@refactoring.club with the subject line [Tolaria Security]. This ensures sensitive information remains confidential while the team coordinates a patch and disclosure timeline.

The Bug Fix Workflow and Quality Gates

After you submit a standard bug report, the maintainers follow a structured workflow described in the contribution documentation. They typically acknowledge receipt within a few business days, verify the defect on the reported platform, and discuss potential fixes or workarounds directly in the issue thread.

Before any bug-fix code can merge, the pull request must satisfy CodeScene health gates documented in AGENTS.md. These automated quality checks ensure that bug fixes do not introduce technical debt or reduce code maintainability.

Summary

• Standard bugs: Use GitHub Issues with detailed reproduction steps per CONTRIBUTING.md (lines 9-10 and 32-41)
• Security bugs: Email luca@refactoring.club with [Tolaria Security] subject per SECURITY.md (lines 5-20)
• Required data: Always include version, OS, and expected versus actual behavior
• Quality control: All fixes must pass CodeScene health gates from AGENTS.md before merging

Frequently Asked Questions

How do I report a standard bug in Tolaria?

Open a GitHub Issue in the refactoringhq/tolaria repository. Follow the template in CONTRIBUTING.md by including your Tolaria version, operating system, and step-by-step reproduction instructions so maintainers can verify the defect.

Where do I report security vulnerabilities in Tolaria?

Email luca@refactoring.club with the subject [Tolaria Security]. Do not open public GitHub Issues for security bugs, as instructed in SECURITY.md (lines 5-20), to keep vulnerability details private until patched.

What information is required in a Tolaria bug report?

You must provide the Tolaria version shown in the About dialog, your operating system version, detailed reproduction steps, expected versus actual outcomes, and optionally screenshots or screen recordings according to CONTRIBUTING.md (lines 32-41).

How long does it take for Tolaria bug reports to be processed?

Maintainers typically acknowledge receipt within a few business days. They then verify the defect on the reported platform, discuss fixes in the issue thread, and merge pull requests only after they satisfy the CodeScene health gates described in AGENTS.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}