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

> Learn how to report bugs in Tolaria efficiently. Discover the correct methods for submitting standard bugs via GitHub Issues and security vulnerabilities through private email.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: how-to-guide
- Published: 2026-05-04

---

**File standard bugs as GitHub Issues following the [`CONTRIBUTING.md`](https://github.com/refactoringhq/tolaria/blob/main/CONTRIBUTING.md) template, but send security vulnerabilities privately via email to `luca@refactoring.club` with the subject `[Tolaria Security]` as required by [`SECURITY.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/CONTRIBUTING.md) for standard defects and [`SECURITY.md`](https://github.com/refactoringhq/tolaria/blob/main/SECURITY.md) for security-critical vulnerabilities.

## Filing Standard Bug Reports via GitHub Issues

According to the contribution guidelines in [`CONTRIBUTING.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```bash

# 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>'

```

```markdown
<!-- 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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/CONTRIBUTING.md) (lines 9-10 and 32-41)
- **Security bugs**: Email `luca@refactoring.club` with `[Tolaria Security]` subject per [`SECURITY.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/AGENTS.md).