documentation/ISSUE.md

# Issue conventions

## Issue Title Conventions
Issue titles should follow the format:
```ignore
<type>: <short description>
```

### `<type>`
This should be one of:

- **Feature**: For new features
- **Bug**: For reporting bugs or issues
- **Refactor**: For code refactoring task
- **Performance**: For performance improvements
- **Documentation**: For documentation-related tasks
- **Test**: For task related to testing
- **Build**: For build system or dependency updates
- **CI**: For continuous integration configurations
- **Chore**: For miscellaneous tasks
- **Revert**: For reverting changes

### `<short description>`
- Use imperative, present tense: "Add", "Fix", "Improve"
- Keep it concise and descriptive
- Do not end with a period (`.`)

### Examples:
- `Feature: Add note preview functionality`
- `Bug: Fix crash when opening empty note`
- `Refactor: Restructure configuration module`

## Issue Description Conventions
Issue descriptions should provide enough context and detail to understand and address the issue effectively.

### Structure:
1. **Overview**: A brief summary of the issue.
2. **Steps to Reproduce**: (For bugs) Detailed steps to replicate the issue. 
3. **Expected Behavior**: What should happen.
4. **Actual Behavior**: What actually happens.
5. **Additional Information**: Any other relevant details, screenshots, or logs.

### Example:
```
**Overview:**
The application crashes when attempting to open a note that is empty.

**Steps to Reproduce:**
1. Create a new note without adding any content.
2. Save the note.
3. Attempt to open the newly created empty note.

**Expected Behavior:**
The empty note opens without any issues.

**Actual Behavior:**
The application crashes with an "IndexOutOfBoundsException".

**Additional Information:**
- Occurs on version 1.2.3
- Stack trace attached below.
```

## Labels
Apply appropriate labels to categorize and prioritize issues.

### Common Labels:

- ### Type:
  - `feature`
  - `bug`
  - `refactor`
  - `documentation`
  - `performance`
  - `test`
  - `build`
  - `ci`
  - `chore`
  - `revert`

- ### Status:
  - `status: needs triage`
  - `status: in progress`
  - `status: blocked`
  - `status: review`

## Milestones
Assign issues to milestones to track progress toward releases or date.
- **Release Milestones**: Use version numbers, e.g., `v1.3.0`
- **Date Milestones**: Use dates or sprint numbers, e.g., `15.10.2024`

## Assignees
- Assign yourself to the issue if you intend to work on it.
- Only one assignee per issue to avoid conflicts.
- If collaborating, mention collaborators in the description.

## Issue Type and Templates
When creating an issue, use the appropriate template:

### Bug Report
- **Title**: `Bug: <short description>`
- **Template Sections**:
  - Overview
  - Steps to Reproduce
  - Expected Behavior
  - Actual Behavior
  - Screenshots (if applicable)
  - Environment (OS, software vesions if possible)
- **Labels**:
  - `bug`
  - `status: needs triage`

### Feature Request
- **Title*: `Feature: <short description>`
- **Template Sections**:
  - Overview
  - Motivation
  - Proposed Solution
  - Alternatives Considered
  - Additional Context
- **Labels**:
  - `feature`
  - `status: needs triage`

### Refactor Task
- **Title**: `Refactor: <short description>`
- **Template Sections**:
  - Overview
  - Reason for Refactoring
  - Areas of Impact
  - Expected Benefits
- **Labels**:
  - `refactor`
  - `status: needs triage`

### Documentation Task
- **Title**: `Documentation: <short description>`
- **Template Sections**:
  - Overview
  - Pages or Sections Affected
  - Proposed Changes
- **Labels**:
  - `documentation`
  - `status: needs triage`

### Performance Improvement
- **Title**: `Performance: <short description>`
- **Template Sections**:
  - Overview
  - Current Performance
  - Expected Performance
  - Impact
  - Additional Information
- **Labels**:
  - `performance`
  - `status: needs triage`

### Test Task
- **Title**: `Test: <short description>`
- **Template Sections**:
  - Overview
  - Areas to Test
  - Test Type
  - Motivation
  - Additional Context
- **Labels**:
  - `test`
  - `status: needs triage`

### Build Task
- **Title**: `Build: <short description>`
- **Template Sections**:
  - Overview
  - Current Build Configuration
  - Proposed Changes
  - Reason for Change
  - Impact
- **Labels**:
  - `build`
  - `status: needs triage`

### CI Task
- **Title**: `CI: <short description>`
- **Template Sections**:
  - Overview
  - Current CI Setup
  - Proposed Changes
  - Motivation
  - Impact
- **Labels**:
  - `ci`
  - `status: needs triage`

### Chore Task
- **Title**: `Chore: <short description>`
- **Template Sections**:
  - Overview
  - Task Details
  - Reasoning
  - Impact
- **Labels**:
  - `chore`
  - `status: needs triage`

### Revert Task
- **Title**: `Chore: <short description>`
- **Template Sections**:
  - Overview
  - Commit/PR to Revert
  - Reason for Revert
  - Impact
- **Labels**:
  - `chore`
  - `status: needs triage`

## Referencing Issues and Pull Requests
- **Closing Issues Automatically**: Include keywords in pull requests to close issues automatically when merged
  - Example: `Closes #123`, `Fixes #456`
- **Mentioning Issues**: Reference related issues by numner in descriptions or comments.
  - Example: `See issue #789 for background`
- **Dependencies**: if the issue depends on other issue or tasks, mention them.
  - Example: `Depends on #321 being completed`
- **Breaking Changes**: If the issue involves changes that are not backward-compatible, not this prominently in the description.

## Commenting Guidelines
- Keep comments relevant and concise
- Update the issue with preogress reports if you're assigned

## Workflow
1. **Search Before Posting**: Check if a similar issue already exists. 
2. **Create the Issue**: Use the correct template and follow the conventions.
3. **Label Appropriately**: Add relevant lables for type and status.
4. **Assign and Milestones**: Assign yourself if working on it and add to a milestone if applicable.
5. **Discussion**: Use the issue comments for any discussion or clarification.
6. **Link Pull Requests**: When submitting a PR, reference the issue it addresses.
7. **Closing the Issue**: The issue will be closed automatically when the PR is merged, or manually if resolved otherwise.

## Examples
### Feature Issue
```markdown
Title:
Feature: Implement note graph visualization

Labels:
- feature
- status: needs triage

Description:

# Overview
Implement a visual graph representation of notes showing their connections.

# Motivation
Helps users understand relationships between notes at a glance.

# Proposed Solution
- Use D3.js for rendering the graph.
- Nodes represent notes; edges represent links.

# Additional Context
- Related to the discussion in #400.
```

### Bug Issue
```markdown
Title:
Bug: Unable to save notes with special characters

Labels:
- bug
- status: needs triage

Description:

# Overview
Notes containing special characters like `&`, `<`, and `>` are not saved correctly.

# Steps to Reproduce
1. Create a new note.
2. Include special characters in the content.
3. Save the note.
4. Reopen the note.

# Expected Behavior
The note content is saved and displayed correctly.

# Actual Behavior
Special characters are either stripped out or cause display issues.

# Environment
- Application Version: 1.2.3
- OS: Windows 10

# Additional Information
- Possibly related to encoding issues.
```