documentation/ISSUE.md

Issue conventions

Issue Title Conventions

Issue titles should follow the format:

<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: low
  • 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)
• Labels:
  • bug
  • priority: {high|megium|low}
  • status: needs triage

Feature Request

• *Title: Feature: <short description>
• Template Sections:
  • Overview
  • Motivation
  • Proposed Solution
  • Alternatives Considered
  • Additional Context
• Labels:
  • feature
  • priority: {high|megium|low}
  • status: needs triage

Refactor Task

• Title Refactor: <short description>
• Template Sections:
  • Overview
  • Reason for Refactoring
  • Areas of Impact
  • Expected Benefits
• Labels:
  • refactor
  • priority: {high|megium|low}
  • status: needs triage

Documentation Task

• Title: Documentation: <short description>
• Template Sections:
  • Overview
  • Pages or Sections Affected
  • Proposed Changes
• Labels:
  • documentation
  • priority: {high|megium|low}
  • status: needs triage

Performance Improvement

• Title: Performance: <short description>
• Template Sections:
  • Overview
  • Current Performance
  • Expected Performance
  • Impact
  • Additional Information
• Labels:
  • performance
  • priority: {high|megium|low}
  • status: needs triage

Test Task

• Title: Test: <short description>
• Template Sections:
  • Overview
  • Areas to Test
  • Test Type
  • Motivation
  • Additional Context
• Labels:
  • test
  • priority: {high|megium|low}
  • status: needs triage

Build Task

• Title: Build: <short description>
• Template Sections:
  • Overview
  • Current Build Configuration
  • Proposed Changes
  • Reason for Change
  • Impact
• Labels:
  • build
  • priority: {high|megium|low}
  • status: needs triage

CI Task

• Title: CI: <short description>
• Template Sections:
  • Overview
  • Current CI Setup
  • Proposed Changes
  • Motivation
  • Impact
• Labels:
  • ci
  • priority: {high|megium|low}
  • status: needs triage

Chore Task

• Title: Chore: <short description>
• Template Sections:
  • Overview
  • Task Details
  • Reasoning
  • Impact
• Labels:
  • chore
  • priority: {high|megium|low}
  • status: needs triage

Revert Task

• Title: Chore: <short description>
• Template Sections:
  • Overview
  • Commit/PR to Revert
  • Reason for Revert
  • Impact
• Labels:
  • chore
  • priority: {high|megium|low}
  • 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, 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

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

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.