# 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`

- ### Priority:
  - `priority: high`
  - `priority: medium`
  - `priority: high`

- ### 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)

### Feature Request
- ### Title: `Feature: <short description>`
- ### Template Sections:
  - Overview
  - Motivation
  - Proposed Solution
  - Alternatives Considered
  - Additional Context

### Refactor Task
- ### Title `Refactor: <short description>`
- ### Template Sections:
  - Overview
  - Reason for Refactoring
  - Areas of Impact
  - Expected Benefits

### Documentation Task
- ### Title: `Documentation: <short description>`
- ### Template Sections:
  - Overview
  - Pages or Sections Affected
  - Proposed Changes

## 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, priority 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
- priority: medium
- 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
- priority: high
- 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.
```