How to Submit an Issue

Bug Reporting and Feature Suggestion Guide

🎯 Overview

Issues help us track bugs, feature requests, and improvement suggestions. A well-written issue helps maintainers understand and resolve your problem faster.

Issue Types

Type	Label	Use Case
🐛 Bug Report	`bug`	Feature not working as expected
✨ Feature Suggestion	`enhancement`	You have an improvement idea
📝 Documentation Issue	`documentation`	Documentation unclear or missing
❓ Question	`question`	Need help or clarification

🔍 Before Submitting

Search Existing Issues - Your problem may have been reported already
Check Documentation - The answer might be in the docs
Try Troubleshooting - Check Troubleshooting Guide
Update to Latest - Make sure you're using the latest version

🐛 Bug Report

Template

When reporting a bug, please include the following information:

## Bug Description
Clearly and concisely describe the bug.

## Steps to Reproduce
1. Open '...'
2. Click '...'
3. Scroll to '...'
4. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Screenshots
If applicable, add screenshots.

## Environment Information
- OS: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04]
- Node.js: [e.g., 20.10.0]
- Package Manager: [e.g., bun 1.0.0, pnpm 8.0.0]
- Browser: [e.g., Chrome 120, Safari 17]

## Additional Context
Other relevant information.

## Error Logs

Paste relevant error messages here

Example: Good Bug Report

## Bug Description
Login form shows "Invalid credentials" even when email and password are correct.

## Steps to Reproduce
1. Open `/auth/login`
2. Enter valid email: [email protected]
3. Enter valid password
4. Click "Login" button
5. Error message appears

## Expected Behavior
Should redirect to `/admin` dashboard after successful login.

## Actual Behavior
Shows "Invalid credentials" error, but account exists in database.

## Environment Information
- OS: macOS 14.2
- Node.js: 20.10.0
- Package Manager: bun 1.0.18
- Browser: Chrome 120

## Error Logs

[auth] Error: Invalid credentials at authenticateUser (/lib/auth/auth.js:45) at POST /api/auth/login

Example: Bad Bug Report ❌

Can't login. Please fix.

Such description doesn't help us understand or reproduce the issue.

✨ Feature Suggestion

Template

## Feature Description
Clearly describe the feature you want.

## Problem Solved
What problem does this feature solve?

## Proposed Solution
How do you envision this feature working?

## Alternatives Considered
Other solutions you've considered.

## Additional Context
Designs, examples, or references.

Example: Good Feature Suggestion

## Feature Description
Add dark mode support to admin panel.

## Problem Solved
Currently admin only has light theme, prolonged use causes eye strain, especially at night.

## Proposed Solution
1. Add theme toggle button in header
2. Save preference to localStorage
3. Use CSS variables for theme colors
4. Support following system preference

## Alternatives Considered
- Browser extension for dark mode (not ideal, affects styles)
- Manual CSS override (hard to maintain)

## Additional Context
Reference: Ant Design has similar implementation we can reference.

📝 Documentation Issue

Template

## Document Location
Which documentation page has the issue?

## Problem Description
What is unclear, missing, or incorrect?

## Improvement Suggestion
How to improve?

## Additional Context
Relevant links or examples.

Example

## Document Location
/docs/admin/guides/SMART_CRUD

## Problem Description
Custom row actions section doesn't explain how to add confirmation dialog.

## Improvement Suggestion
Add an example showing:
```javascript
customRowActions={[
  {
    key: 'delete',
    label: 'Delete',
    confirm: {
      title: 'Are you sure?',
      content: 'This action cannot be undone.'
    },
    onClick: handleDelete
  }
]}

Additional Context

I had to dig through source code to find this usage.


---

## 💡 Tips

### Should Do ✅

- **Be Specific** - Include accurate error messages and steps
- **Provide Context** - Environment, version, relevant configuration
- **One Issue Per Problem** - Don't mix multiple issues
- **Use Formatting** - Code blocks, headings, lists
- **Be Patient** - Maintainers are usually volunteers
- **Follow Up Promptly** - Reply to questions promptly

### Shouldn't Do ❌

- **Duplicate Submissions** - Search first
- **Vague Descriptions** - "Doesn't work" isn't helpful
- **Include Sensitive Info** - Hide passwords, API keys
- **Demand Immediate Fix** - This is an open source project
- **Be Rude** - We're all here to help

---

## 🏷️ Issue Labels

Common label meanings:

| Label | Meaning |
|:---|:---|
| `bug` | Confirmed bug |
| `enhancement` | Feature request |
| `documentation` | Documentation improvement |
| `good first issue` | Good for beginners |
| `help wanted` | Needs contributors |
| `wontfix` | Won't be fixed |
| `duplicate` | Duplicate issue |
| `needs info` | Needs more information |

---

## 🔄 Issue Lifecycle

Created → Issue submitted
Categorized → Maintainer reviews and labels
Confirmed → Issue valid and accepted
In Progress → Someone is working on it
Resolved → Fix merged or question answered
Closed → Issue complete


---

## 📋 Quick Reference

### Bug Report Minimum Requirements

- [ ] What happened
- [ ] What you expected
- [ ] How to reproduce
- [ ] Error message (if any)
- [ ] Environment information

### Feature Suggestion Minimum Requirements

- [ ] What you want
- [ ] Why you want it
- [ ] How it might be implemented

---

## 📚 Related Documentation

<Cards className="not-prose grid gap-4 md:grid-cols-2">
	<Card
		title="Submit Pull Request"
		description="Want to fix it yourself? Here's how"
		href="/docs/contributing/PULL_REQUEST"
	/>
	<Card
		title="Troubleshooting Guide"
		description="Check solutions to common problems first"
		href="/docs/troubleshooting"
	/>
	<Card
		title="Contributing Guide"
		description="Overall contributing guide"
		href="/docs/contributing"
	/>
</Cards>

On this page