From 035f10fda0c4e6c05878062169c7da46c4946148 Mon Sep 17 00:00:00 2001 From: yukkop Date: Tue, 15 Oct 2024 01:00:03 +0000 Subject: [PATCH] docs: create ISSUE.md --- CONTRIBUTING.md | 5 -- ISSUE.md | 221 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++ 3 files changed, 229 insertions(+), 5 deletions(-) create mode 100644 ISSUE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f9e458..c566cf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,5 @@ # Contribution conventions -## Syntax legend: - -- `` is mandatory -- `[foo]` is optional - ## Branch conventions - `/[/, ...]` diff --git a/ISSUE.md b/ISSUE.md new file mode 100644 index 0000000..e5c7d20 --- /dev/null +++ b/ISSUE.md @@ -0,0 +1,221 @@ +# Issue conventions + +## Issue Title Conventions +Issue titles should follow the format: +```ignore +: +``` + +### `` +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 + +### `` +- 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: ` +- ### Template Sections: + - Overview + - Steps to Reproduce + - Expected Behavior + - Actual Behavior + - Screenshots (if applicable) + - Environment (OS, software vesions if possible) + +### Feature Request +- ### Title: `Feature: ` +- ### Template Sections: + - Overview + - Motivation + - Proposed Solution + - Alternatives Considered + - Additional Context + +### Refactor Task +- ### Title `Refactor: ` +- ### Template Sections: + - Overview + - Reason for Refactoring + - Areas of Impact + - Expected Benefits + +### Documentation Task +- ### Title: `Documentation: ` +- ### 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. +``` diff --git a/README.md b/README.md index 8a3f605..9b2031a 100644 --- a/README.md +++ b/README.md @@ -2,5 +2,13 @@ >... +## Syntax legend: + +- `` is mandatory +- `[foo]` is optional +- `{foo|bar}` is optional +- Words in **bold** are literal and should be used as is + ## Index - [CONTRIBUTING](CONTRIBUTING.md) +- [ISSUE](ISSUE.md)