forked from hinterland/documentation
docs: create ISSUE.md
This commit is contained in:
@@ -0,0 +1,221 @@
|
||||
# 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.
|
||||
```
|
||||
Reference in New Issue
Block a user