How to Report a Bug in Apache Maka: A Step-by-Step Guide

To report a bug in Apache Maka, search existing issues to avoid duplicates, select the Bug report template on GitHub, and provide your environment details (including the exact commit SHA), minimal reproduction steps, and specific file references like apps/desktop/src/main/main.ts:120.

Reporting bugs effectively ensures the Apache Maka maintainers can triage and resolve issues quickly. This guide walks through the exact workflow defined in the CONTRIBUTING.md and issue templates found in the apache/maka repository.

Verify the Bug Has Not Been Reported

Before creating a new issue, search the open bug issues with the bug label to confirm your problem is not already tracked. Reproducing the issue on the latest main branch and noting the exact commit SHA (via git rev-parse HEAD) ensures you are testing the most recent code.

Security Vulnerabilities Require Private Reporting

Security bugs must never be filed publicly. According to SECURITY.md, critical vulnerabilities should be reported via email to security@maka.app or through a private GitHub Security Advisory. This prevents exposing exploit details before a patch is available.

Submitting a Standard Bug Report to Apache Maka

For non-security issues, navigate to the Issues tab and click New issue, then select the Bug report template. Complete every section with precise technical details:

Environment Specification

Include the Maka version from the About page, operating system, Node.js and Electron versions, and the exact Git commit SHA. This context allows maintainers to match your runtime conditions exactly.

Minimal Reproduction Steps

Provide an ordered list that reliably triggers the bug. Start from a clean state (e.g., "1. Open Maka. 2. Click Open Workspace..."). Each step should be verifiable and exclude unnecessary actions.

Source Code References

Point to specific locations in the codebase where the error originates. For example, cite apps/desktop/src/main/main.ts:132‑149 if the crash relates to main process memory handling. Line numbers help developers locate logic without searching the entire repository.

Expected vs. Actual Behavior

Clearly state what the application should do versus what it actually does. Attach crash logs, screenshots, or GIFs in the Additional context section to provide visual or log-based evidence.

Example Bug Report Structure

Below is a complete example demonstrating the level of detail expected in the Apache Maka issue tracker:

### Description

The desktop app crashes when opening a workspace that contains a file larger than 50 MB.

### Environment

- Maka version: 0.9.3 (Commit `a1b2c3d4`)
- OS: macOS 14.4
- Node: 22.19.0
- Electron: 28.0.0

### Steps to Reproduce

1. Open Maka.
2. Click **Open Workspace** and select a folder containing `large-file.bin` (≈ 60 MB).
3. Observe the crash after ~2 seconds.

### Expected Behavior

The workspace should open and display the file list without crashing.

### Actual Behavior

The app shows a native crash dialog and exits.

### Relevant Code

`apps/desktop/src/main/main.ts:132‑149` – potential out-of-memory handling.

### Additional Information

- Crash logs attached (`crash.log`).
- No custom plugins loaded.

Post-Submission Workflow

After submitting, the maintainers automatically apply the bug label and add the issue to the triage board. Monitor notifications for requests to test patches or provide additional logs. When a fix merges into the main branch referencing your issue number, GitHub will close the ticket automatically.

Summary

• Search existing bug issues before filing to avoid duplicates.
• Send security vulnerabilities privately to security@maka.app per SECURITY.md, never through public issues.
• Use the Bug report template and include the exact commit SHA, Node/Electron versions, and OS details.
• Cite specific file paths like apps/desktop/src/main/main.ts:120‑145 to pinpoint problematic code.
• Provide ordered reproduction steps and attach crash logs or screenshots for context.

Frequently Asked Questions

Where do I find the commit SHA to include in my Apache Maka bug report?

Run git rev-parse HEAD in your local Maka repository clone, or check the version information in the application's About page. Including this SHA allows maintainers to test against the exact codebase state where you observed the bug.

Can I report a bug without knowing which source file is causing it?

Yes, but providing a best-guess file reference (such as apps/desktop/src/main/main.ts based on where the crash occurs) significantly speeds up triage. If uncertain, describe the UI location or error message instead.

What should I do if my bug report receives no response?

Apache Maka uses a triage board to manage open issues. If your issue remains unassigned after several days, verify you have provided all template fields, especially reproduction steps and environment details. Maintainers prioritize issues with complete information and clear source code references.

How do I report a security vulnerability in Apache Maka?

Never open a public issue for security bugs. Instead, email security@maka.app or create a private GitHub Security Advisory as detailed in the repository's SECURITY.md file. This ensures the vulnerability remains confidential during remediation.

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