|
| 1 | +# Filing Issues |
| 2 | + |
| 3 | +Thank you for helping improve the LFX Self Serve product! This document explains |
| 4 | +how to report bugs, request features, and submit task tickets. Taking a few |
| 5 | +minutes to follow these guidelines helps maintainers triage and resolve issues |
| 6 | +faster — and keeps the community healthy. |
| 7 | + |
| 8 | +## Before You File an Issue |
| 9 | + |
| 10 | +### 1. Get Product Support First |
| 11 | + |
| 12 | +If you have a **question about how to use the product**, please reach out |
| 13 | +through the **in-application Intercom support bot** before opening a GitHub |
| 14 | +issue. The support bot connects you with the product team and can often resolve |
| 15 | +questions much faster than the GitHub issue tracker. |
| 16 | + |
| 17 | +> GitHub issues are reserved for **bugs**, **feature requests**, and **tracked |
| 18 | +> tasks** — not general usage questions or "how do I…" inquiries. |
| 19 | +
|
| 20 | +### 2. Search for Duplicates |
| 21 | + |
| 22 | +Before opening a new issue, [search existing issues](../../issues) (including |
| 23 | +closed ones) to see if the topic has already been reported or discussed. If a |
| 24 | +relevant issue exists: |
| 25 | + |
| 26 | +- Add a 👍 reaction to signal your interest rather than posting a "+1" comment. |
| 27 | +- Add a comment only if you have new, substantive information (e.g., a different |
| 28 | + reproduction path, an affected version, or a workaround). |
| 29 | + |
| 30 | +### 3. Check the Documentation |
| 31 | + |
| 32 | +Review the project's README, docs site, and any relevant document pages. Your |
| 33 | +question or concern may already be addressed. |
| 34 | + |
| 35 | +## Issue Types |
| 36 | + |
| 37 | +> When filing through GitHub's issue chooser, the appropriate label is applied |
| 38 | +> automatically. Title prefixes (`[Bug]`, `[Feature]`, `[Task]`) are optional. |
| 39 | +
|
| 40 | +### 🐛 Bug Reports |
| 41 | + |
| 42 | +Use this type when something is **broken or behaving unexpectedly**. |
| 43 | + |
| 44 | +**A high-quality bug report includes:** |
| 45 | + |
| 46 | +- **Summary** — A clear, one-sentence description of the problem. |
| 47 | +- **Environment** — OS, runtime/language version, package version, browser (if applicable). |
| 48 | +- **Steps to Reproduce** — A numbered, minimal list of steps that reliably triggers the issue. |
| 49 | +- **Expected Behavior** — What you expected to happen. |
| 50 | +- **Actual Behavior** — What actually happened. |
| 51 | +- **Logs / Screenshots** — Paste relevant error output in a fenced code block. |
| 52 | + Attach screenshots or screen recordings where helpful. |
| 53 | + |
| 54 | +> **Tip:** If you cannot reproduce the bug consistently, say so. Intermittent |
| 55 | +> issues are still valid — just note the frequency and any patterns you've |
| 56 | +> observed. |
| 57 | +
|
| 58 | +**Example title format:** |
| 59 | + |
| 60 | +```code |
| 61 | +[Bug] Login page throws 500 error when email contains a "+" character |
| 62 | +``` |
| 63 | + |
| 64 | +### ✨ Feature Requests |
| 65 | + |
| 66 | +Use this type when you want to **propose new functionality or a meaningful enhancement** to existing behavior. |
| 67 | + |
| 68 | +**A high-quality feature request includes:** |
| 69 | + |
| 70 | +- **Problem Statement** — Describe the problem or limitation you're facing. Focus on the *why*, not just the *what*. |
| 71 | +- **Proposed Solution** — Describe the behavior or interface you'd like to see. |
| 72 | +- **Alternatives Considered** — List any workarounds or alternative approaches you've explored and why they fall short. |
| 73 | +- **Use Case / Impact** — Explain who benefits and how frequently this situation |
| 74 | + arises. Community use cases help maintainers prioritize. |
| 75 | +- **Willingness to Contribute** — If you're open to submitting a pull request, |
| 76 | + say so! Maintainers prioritize requests backed by contributors. |
| 77 | + |
| 78 | +> **Note:** Feature requests are not guarantees of implementation. The |
| 79 | +> maintainer team evaluates proposals against project scope, roadmap, and |
| 80 | +> available capacity. |
| 81 | +
|
| 82 | +**Example title format:** |
| 83 | + |
| 84 | +```code |
| 85 | +[Feature] Add a new table filter for the Me Lens -> Events view |
| 86 | +``` |
| 87 | + |
| 88 | +### 📋 Task Tickets |
| 89 | + |
| 90 | +Use this type for **well-scoped, actionable work items** that don't fit neatly |
| 91 | +into bugs or features — such as refactors, documentation updates, dependency |
| 92 | +upgrades, CI/CD improvements, or technical debt paydown. |
| 93 | + |
| 94 | +**A high-quality task ticket includes:** |
| 95 | + |
| 96 | +- **Objective** — What is the desired end state? |
| 97 | +- **Motivation** — Why does this work matter now? |
| 98 | +- **Acceptance Criteria** — A checklist of conditions that define "done." |
| 99 | +- **Relevant Context** — Links to related issues, PRs, ADRs, or external references. |
| 100 | +- **Estimated Scope** — Small / Medium / Large. Helps with triage and sprint planning. |
| 101 | + |
| 102 | +> **Commit type note:** Task work maps to `build`, `refactor`, `docs`, or `ci` in |
| 103 | +> commit messages — not `chore` or `task`, which commitlint does not accept. See |
| 104 | +> [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages) for the full list. |
| 105 | +
|
| 106 | +**Example title format:** |
| 107 | + |
| 108 | +```code |
| 109 | +[Task] Upgrade eslint to v9 and migrate to flat config |
| 110 | +``` |
| 111 | + |
| 112 | +## Writing Good Issues: Universal Best Practices |
| 113 | + |
| 114 | +| Practice | Why It Matters | |
| 115 | +| :-------- | :--------------- | |
| 116 | +| **One issue, one concern** | Bundled issues are hard to track, assign, and close cleanly. | |
| 117 | +| **Be specific in the title** | Vague titles like "It's broken" are hard to search and triage. | |
| 118 | +| **Use code blocks for code and logs** | Unformatted output is hard to read and easy to misinterpret. | |
| 119 | +| **Avoid editorializing** | Describe facts, not frustrations. Maintainers are volunteers. | |
| 120 | +| **Provide context, not conclusions** | "X is wrong" is less useful than "X produces Y, but I expected Z because of W." | |
| 121 | +| **Follow up if asked** | If a maintainer requests more information, respond promptly or the issue may be closed. | |
| 122 | +| **Respect the Code of Conduct** | All interactions must comply with this project's Code of Conduct. | |
| 123 | + |
| 124 | +## Issue Lifecycle |
| 125 | + |
| 126 | +```code |
| 127 | +Open → Triaged → In Progress → Closed |
| 128 | + ↘ Won't Fix / Duplicate / Needs Info |
| 129 | +``` |
| 130 | + |
| 131 | +- **Needs Info** — A maintainer requires more details before the issue can be |
| 132 | + triaged. Issues in this state may be closed after extended inactivity. |
| 133 | +- **Triaged** — The issue has been reviewed and accepted into the backlog. |
| 134 | +- **In Progress** — Actively being worked on; a linked PR may exist. |
| 135 | +- **Won't Fix** — Out of scope, by design, or not reproducible. The reasoning |
| 136 | + will be explained in a comment. |
| 137 | + |
| 138 | +## Security Vulnerabilities |
| 139 | + |
| 140 | +**Do not file security vulnerabilities as public GitHub issues.** |
| 141 | + |
| 142 | +Please follow the project's [Security Policy](SECURITY.md) and use GitHub's |
| 143 | +[private vulnerability reporting](../../security/advisories/new). Responsible |
| 144 | +disclosure protects all users while a fix is prepared. |
| 145 | + |
| 146 | +## Contributing a Fix |
| 147 | + |
| 148 | +Found a bug and want to fix it yourself? We welcome it! Please read |
| 149 | +[CONTRIBUTING.md](CONTRIBUTING.md) for: |
| 150 | + |
| 151 | +- How to fork and branch |
| 152 | +- Coding standards and linting requirements |
| 153 | +- How to write and run tests |
| 154 | +- The pull request review process |
| 155 | + |
| 156 | +Linking your PR to the relevant issue with `Closes #<issue-number>` in the PR |
| 157 | +description helps maintainers track work and auto-closes the issue on merge. |
| 158 | +Pull requests automatically request review from the code owners listed in |
| 159 | +[`CODEOWNERS`](CODEOWNERS). |
| 160 | + |
| 161 | +## Helpful Resources |
| 162 | + |
| 163 | +- 📖 [Product Documentation](README.md) |
| 164 | +- 💬 [Community Discussions](../../discussions) |
| 165 | +- 🔒 [Security Policy](SECURITY.md) |
| 166 | +- 🤝 [Contributing Guide](CONTRIBUTING.md) |
| 167 | +- 📜 [Code of Conduct](CODE_OF_CONDUCT.md) |
| 168 | + |
| 169 | +*Thank you for your patience and for contributing to the health of this project.* |
0 commit comments