How to Report a Bug in GeoLibre: A Complete Guide for Contributors

To report a bug in GeoLibre, open a GitHub issue with a clear title, detailed reproduction steps, environment details, and minimal test data.

Reporting bugs effectively helps the opengeos/GeoLibre maintainers reproduce issues quickly and prioritize fixes. The project provides explicit guidelines in its contribution documentation to ensure every report contains the information needed for efficient triage. This guide walks through the exact workflow specified in [docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md), including a ready-to-use markdown template.

Steps to Report a Bug in GeoLibre

Open a GitHub Issue

Navigate to the GeoLibre issues page and click New issue. This is the primary channel for all bug reports and feature requests according to the project documentation.

Provide a Clear Title

Summarize the symptom in one concise sentence. A strong title immediately communicates the problem to maintainers scanning the issue list.

Good examples:

• "Desktop build crashes when loading MBTiles file with custom projection"
• "Web build fails to render vector tiles at zoom level 14+"

Include Reproduction Steps

List the exact actions that trigger the bug. Structure this as:

• Steps to reproduce — numbered sequence of clicks/inputs
• Expected outcome — what should happen
• Actual result — what actually happened, including error messages

The [docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) file explicitly states: "Include steps to reproduce, what you expected, and what happened, plus your OS and whether you hit it in the web or desktop build."

Identify Your Environment

Specify:

• GeoLibre version — run npm run version or check Help → About
• Build type — web or desktop (Tauri)
• Operating system and version
• Node.js and Rust versions (for desktop builds)

This distinction matters because GeoLibre maintains separate codepaths for web and desktop architectures, as detailed in [docs/architecture.md](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md).

Attach Minimal Test Data

If the bug involves a dataset, provide a small example file (≤ 5 MB) via a public URL rather than uploading directly to the issue. The project hosts sample data in the geolibre-assets repository for this purpose.

Apply the Bug Label

Use the "bug" label when creating the issue. The GitHub UI will suggest this label, and it enables triage bots to route your report to the appropriate maintainers automatically.

GeoLibre Bug Report Template

Copy and paste this markdown template into your issue, then adjust placeholders to match your situation:

### Description

A short summary of the bug.

### Steps to Reproduce

1. Open the **Desktop** app (version X.Y.Z) on **Windows 11**.
2. Click **File → Open…** and select `sample.mbtiles`.
3. Observe the crash/error message.

### Expected Result

The MBTiles layer loads and displays correctly on the map.

### Actual Result

The app crashes with the following error: `Error: Invalid MBTiles header`.

### Environment

- **GeoLibre version:** X.Y.Z (run `npm run version` or check *Help → About*)
- **Build:** Desktop (Tauri)
- **OS:** Windows 11 22H2
- **Node:** 22.x, **Rust:** 1.78

### Sample Data

[Download sample MBTiles (≈ 2 MB)](https://assets.geolibre.app/data/sample.mbtiles)

### Additional Context

Any logs, screenshots, or console output that might help.

GitHub renders this structure cleanly, making it easy for maintainers to parse critical information at a glance.

Key Files for Bug Reporters

Understanding these files helps you write more precise bug reports:

File	Relevance
[docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)	Contains the canonical bug-reporting workflow and required information
[README.md](https://github.com/opengeos/GeoLibre/blob/main/README.md)	Links to the issue tracker and community contribution guidelines
[docs/architecture.md](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md)	Explains web vs. desktop build differences to help you specify the affected component

What Happens After Submission

After clicking Submit, maintainers will:

1. Triage the issue using the bug label routing
2. Comment with follow-up questions if reproduction details are unclear
3. Link to a draft pull request when a fix is in progress

Clear, complete reports reduce back-and-forth and accelerate resolution timelines.

Summary

• GeoLibre bug reports are submitted via GitHub Issues at opengeos/GeoLibre
• Required elements: clear title, reproduction steps, expected vs. actual results, environment details (web/desktop, OS, version), and minimal test data
• Use the provided markdown template for consistent, scannable reports
• Reference [docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) and [docs/architecture.md](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md) to understand project conventions

Frequently Asked Questions

Where do I submit a GeoLibre bug report?

Submit all bug reports to the GitHub Issues page in the opengeos/GeoLibre repository. The project does not use external bug trackers or email lists—GitHub Issues is the centralized coordination point for all bug tracking and feature requests.

What information is mandatory in a GeoLibre bug report?

You must include steps to reproduce, expected behavior, actual behavior, your operating system, and whether the bug occurs in the web or desktop build. The [docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) file explicitly lists these as required elements for all issue submissions.

How do I find my GeoLibre version?

Run npm run version in your terminal, or open Help → About in the desktop application. For web builds, check the version displayed in the application footer or browser console. Include this version number in every bug report to help maintainers identify regression ranges.

Can I upload large datasets to a GeoLibre bug report?

No—avoid uploading files directly to GitHub issues. Instead, provide a public URL to sample data under 5 MB, such as files hosted in the geolibre-assets repository or temporary file-sharing services. This keeps the issue tracker lightweight while still giving maintainers access to reproduction materials.

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