├── .issues └── templates │ ├── issue.md │ └── story.md ├── issues-template ├── templates │ ├── issue.md │ └── story.md └── sample │ └── m001-auth-system │ ├── 005-fix-password-validation.md │ ├── 004-test-login-flow.md │ ├── 002-feat-login-page-implementation.md │ └── 001-story-user-login-system.md ├── .cursor └── rules │ └── local-issues.mdc ├── README_zh.md ├── README.md └── LICENSE /.issues/templates/issue.md: -------------------------------------------------------------------------------- 1 | # Title 2 | Brief issue title 3 | 4 | # Introduction 5 | Detailed description of the issue 6 | 7 | # Tasks 8 | - [ ] Task 1 9 | - [ ] Task 2 10 | 11 | # Dependencies 12 | - [ ] {id} Dependency description 13 | 14 | # Status History 15 | - YYYY-MM-DD: Created -------------------------------------------------------------------------------- /issues-template/templates/issue.md: -------------------------------------------------------------------------------- 1 | # Title 2 | Brief issue title 3 | 4 | # Introduction 5 | Detailed description of the issue 6 | 7 | # Tasks 8 | - [ ] Task 1 9 | - [ ] Task 2 10 | 11 | # Dependencies 12 | - [ ] {id} Dependency description 13 | 14 | # Status History 15 | - YYYY-MM-DD: Created -------------------------------------------------------------------------------- /issues-template/sample/m001-auth-system/005-fix-password-validation.md: -------------------------------------------------------------------------------- 1 | # Title 2 | Fix Password Validation Bug 3 | 4 | # Introduction 5 | Current password validation is not properly handling special characters and has inconsistent behavior between frontend and backend validation rules. This needs to be fixed to ensure consistent validation and improve user experience. 6 | 7 | # Tasks 8 | - [ ] Audit current password validation rules 9 | - [ ] Align frontend and backend validation 10 | - [ ] Update regex pattern for special characters 11 | - [ ] Add proper error messages for each validation rule 12 | - [ ] Test with various password combinations 13 | - [ ] Update documentation with new validation rules 14 | 15 | # Dependencies 16 | - [ ] 002 Login page implementation 17 | - [ ] 003 Authentication service implementation 18 | 19 | # Status History 20 | - 2024-01-08: Created -------------------------------------------------------------------------------- /issues-template/sample/m001-auth-system/004-test-login-flow.md: -------------------------------------------------------------------------------- 1 | # Title 2 | Comprehensive Test Suite for Login Flow 3 | 4 | # Introduction 5 | Implement end-to-end and unit tests for the entire login flow, covering both successful and failure scenarios, edge cases, and security aspects. 6 | 7 | # Tasks 8 | - [ ] Set up testing environment and tools 9 | - [ ] Write unit tests for form validation 10 | - [ ] Write unit tests for authentication service 11 | - [ ] Implement E2E tests for successful login flow 12 | - [ ] Implement E2E tests for failed login scenarios 13 | - [ ] Add security testing (XSS, CSRF, SQL injection) 14 | - [ ] Test session management 15 | - [ ] Add performance tests for login endpoints 16 | 17 | # Dependencies 18 | - [ ] 002 Login page implementation 19 | - [ ] 003 Authentication service implementation 20 | 21 | # Status History 22 | - 2024-01-08: Created -------------------------------------------------------------------------------- /issues-template/sample/m001-auth-system/002-feat-login-page-implementation.md: -------------------------------------------------------------------------------- 1 | # Title 2 | Implement Login Page UI and Form 3 | 4 | # Introduction 5 | Create a responsive login page with form validation and error handling. The page should provide a clean user interface for entering credentials and handle various login scenarios gracefully. 6 | 7 | # Tasks 8 | - [ ] Create responsive login page layout 9 | - [ ] Implement form with email and password fields 10 | - [ ] Add client-side validation for inputs 11 | - [ ] Create loading state for form submission 12 | - [ ] Implement error message display 13 | - [ ] Add "Forgot Password" link 14 | - [ ] Style according to design system 15 | - [ ] Add accessibility features (ARIA labels, keyboard navigation) 16 | 17 | # Dependencies 18 | - [ ] 001 Parent user story 19 | - [ ] Design system must be finalized 20 | 21 | # Status History 22 | - 2024-01-08: Created -------------------------------------------------------------------------------- /issues-template/sample/m001-auth-system/001-story-user-login-system.md: -------------------------------------------------------------------------------- 1 | # Title 2 | User Authentication Login System 3 | 4 | # Story 5 | As a registered user 6 | I want to be able to log into the system using my credentials 7 | So that I can access my personal account and protected features 8 | 9 | # Acceptance Criteria 10 | - [ ] User can input email and password 11 | - [ ] System validates credentials against database 12 | - [ ] Successful login redirects to dashboard 13 | - [ ] Failed login shows appropriate error message 14 | - [ ] "Forgot Password" option is available 15 | - [ ] User session is properly maintained 16 | 17 | # Sub-Issues 18 | - [ ] 002 Implement login page UI and form 19 | - [ ] 003 Implement authentication backend service 20 | - [ ] 004 Add comprehensive test suite for login flow 21 | - [ ] 005 Fix password validation bug 22 | 23 | # Dependencies 24 | - [ ] Database system is set up 25 | - [ ] Email service is configured 26 | 27 | # Status History 28 | - 2024-01-08: Created -------------------------------------------------------------------------------- /.issues/templates/story.md: -------------------------------------------------------------------------------- 1 | # Title 2 | [Verb] + [Object] + [Qualifier] 3 | Example: Create User Payment Flow 4 | 5 | # Story 6 | As a [user role: specific target user] 7 | I want [goal/action: specific operation to complete] 8 | So that [benefit/value: value gained from this operation] 9 | 10 | 11 | # Basic Concept 12 | - Domain Term A: [definition of the term in current business context] 13 | - Domain Term B: [definition of the term in current business context] 14 | - Business Rules: [key business rules to follow] 15 | - Related Concepts: [other business concepts that need explanation] 16 | 17 | # Scenario 18 | Preconditions: 19 | - [conditions that must be met before using this feature] 20 | 21 | Main Flow: 22 | 1. [User action step 1] 23 | 2. [System response 1] 24 | 3. [User action step 2] 25 | 4. [System response 2] 26 | 27 | Exception Handling: 28 | - Case 1: [exception scenario description] 29 | - Handling: [how to handle this exception] 30 | - Case 2: [exception scenario description] 31 | - Handling: [how to handle this exception] 32 | 33 | # Acceptance Criteria 34 | Functional Requirements: 35 | - [ ] [specific functional acceptance criterion 1] 36 | - [ ] [specific functional acceptance criterion 2] 37 | 38 | Non-functional Requirements: 39 | - [ ] [performance/security/UX acceptance criteria] 40 | 41 | 42 | # Sub-Issues 43 | - [ ] {id} Issue description 44 | - [ ] {id} Issue description 45 | 46 | # Dependencies 47 | Technical Dependencies: 48 | - [ ] {DEP-001} [dependent system/service/component] 49 | - [ ] {DEP-002} [dependent API/data] 50 | 51 | Business Dependencies: 52 | - [ ] {BIZ-001} [dependent business process/rule] 53 | 54 | # Status History 55 | - YYYY-MM-DD: Created -------------------------------------------------------------------------------- /issues-template/templates/story.md: -------------------------------------------------------------------------------- 1 | # Title 2 | [Verb] + [Object] + [Qualifier] 3 | Example: Create User Payment Flow 4 | 5 | # Story 6 | As a [user role: specific target user] 7 | I want [goal/action: specific operation to complete] 8 | So that [benefit/value: value gained from this operation] 9 | 10 | 11 | # Basic Concept 12 | - Domain Term A: [definition of the term in current business context] 13 | - Domain Term B: [definition of the term in current business context] 14 | - Business Rules: [key business rules to follow] 15 | - Related Concepts: [other business concepts that need explanation] 16 | 17 | # Scenario 18 | Preconditions: 19 | - [conditions that must be met before using this feature] 20 | 21 | Main Flow: 22 | 1. [User action step 1] 23 | 2. [System response 1] 24 | 3. [User action step 2] 25 | 4. [System response 2] 26 | 27 | Exception Handling: 28 | - Case 1: [exception scenario description] 29 | - Handling: [how to handle this exception] 30 | - Case 2: [exception scenario description] 31 | - Handling: [how to handle this exception] 32 | 33 | # Acceptance Criteria 34 | Functional Requirements: 35 | - [ ] [specific functional acceptance criterion 1] 36 | - [ ] [specific functional acceptance criterion 2] 37 | 38 | Non-functional Requirements: 39 | - [ ] [performance/security/UX acceptance criteria] 40 | 41 | 42 | # Sub-Issues 43 | - [ ] {id} Issue description 44 | - [ ] {id} Issue description 45 | 46 | # Dependencies 47 | Technical Dependencies: 48 | - [ ] {DEP-001} [dependent system/service/component] 49 | - [ ] {DEP-002} [dependent API/data] 50 | 51 | Business Dependencies: 52 | - [ ] {BIZ-001} [dependent business process/rule] 53 | 54 | # Status History 55 | - YYYY-MM-DD: Created -------------------------------------------------------------------------------- /.cursor/rules/local-issues.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: When agent works with user story , issues or other requirments and task jobs 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # Local Issues Management System 7 | 8 | ## Directory Structure 9 | 10 | - `/.issues` - Root directory for all issues 11 | - First level: Milestone folders (e.g., `m001-InitProject`) 12 | - Second level: Issue files within each milestone 13 | - `/.issues/templates` - Issue templates, for story and issue 14 | - @story.md - For user stories 15 | - @issue.md - For features, fixes, and tests 16 | 17 | ## Issue Types and Naming 18 | 19 | Issue files follow the naming pattern: `{id}-{type}-{description}.md` 20 | - `{id}`: Globally unique identifier across all issues, cross all issues in any sub-directory of /issues/* 21 | - `{type}`: One of the following: 22 | - `story` - User story describing complete user value 23 | - `feat` - New feature implementation 24 | - `fix` - Bug fix 25 | - `test` - Test implementation 26 | - `{description}`: Brief kebab-case description 27 | 28 | ## Issue States 29 | 30 | Tasks and issues can have the following states: 31 | - `[ ]` - Not started 32 | - `[x]` - Completed 33 | - `[-]` - In progress 34 | - `[*]` - Skipped 35 | - `[!]` - Abandoned 36 | 37 | ## Templates 38 | 39 | Two types of issue templates are available in `/.issues/templates/`: 40 | 1. @story.md : For user stories 41 | 2. @issue.md : For features, fixes, and tests 42 | 43 | ## File Modification Rules 44 | - When creating 45 | - New issue, use @issue.md template 46 | - New story, use @story.md template 47 | - Always check all issues and stories in /.issues to make sure the id is unique 48 | - Only modify task/issue states in existing files 49 | - Do not alter other content without creating a new issue 50 | - Always update Status History when changing states 51 | 52 | -------------------------------------------------------------------------------- /README_zh.md: -------------------------------------------------------------------------------- 1 | # 本地问题管理系统 2 | 3 | 一个用于本地管理项目问题的结构化模板系统。该系统提供了一个清晰的、基于文件的方法来跟踪用户故事、功能特性、缺陷和测试。 4 | 5 | [English](README.md) | 简体中文 6 | 7 | ## 目录 8 | - [特性](#特性) 9 | - [目录结构](#目录结构) 10 | - [问题类型](#问题类型) 11 | - [问题状态](#问题状态) 12 | - [文件命名规范](#文件命名规范) 13 | - [模板](#模板) 14 | - [入门指南](#入门指南) 15 | - [使用方法](#使用方法) 16 | - [示例](#示例) 17 | - [最佳实践](#最佳实践) 18 | - [编辑器集成](#编辑器集成) 19 | - [常见问题](#常见问题) 20 | - [贡献](#贡献) 21 | - [许可证](#许可证) 22 | 23 | ## 特性 24 | 25 | - 📁 按里程碑组织的结构化目录 26 | - 📝 标准化的故事和问题模板 27 | - ✅ 清晰的任务状态跟踪 28 | - 🔗 内置的依赖关系管理 29 | - 📊 通过状态历史进行进度跟踪 30 | 31 | ## 目录结构 32 | 33 | ``` 34 | .issues/ 35 | ├── templates/ 36 | │ ├── story.md 37 | │ └── issue.md 38 | ├── m001-project-milestone/ 39 | │ ├── 001-story-feature-description.md 40 | │ ├── 002-feat-implementation.md 41 | │ ├── 003-test-test-suite.md 42 | │ └── 004-fix-bug-fix.md 43 | └── m002-another-milestone/ 44 | └── ... 45 | ``` 46 | 47 | ## 问题类型 48 | 49 | - `story`: 描述完整用户价值的用户故事 50 | - `feat`: 新功能实现 51 | - `fix`: 缺陷修复实现 52 | - `test`: 测试实现 53 | 54 | ## 问题状态 55 | 56 | - `[ ]` 未开始 57 | - `[x]` 已完成 58 | - `[-]` 进行中 59 | - `[*]` 已跳过 60 | - `[!]` 已放弃 61 | 62 | ## 文件命名规范 63 | 64 | 文件遵循以下模式：`{id}-{type}-{description}.md` 65 | 66 | - `id`: 在所有问题中全局唯一的标识符 67 | - `type`: 问题类型 (story/feat/fix/test) 68 | - `description`: 简短的 kebab-case 描述 69 | 70 | ## 模板 71 | 72 | 提供两种标准模板： 73 | 74 | 1. 故事模板 (`templates/story.md`) 75 | ```markdown 76 | # 标题 77 | 简短的故事标题 78 | 79 | # 故事 80 | 作为 [角色] 81 | 我想要 [目标/行动] 82 | 以便 [收益/价值] 83 | 84 | # 验收标准 85 | - [ ] 标准 1 86 | - [ ] 标准 2 87 | 88 | # 子问题 89 | - [ ] {id} 问题描述 90 | 91 | # 依赖关系 92 | - [ ] {id} 依赖描述 93 | 94 | # 状态历史 95 | - YYYY-MM-DD: 创建 96 | ``` 97 | 98 | 2. 问题模板 (`templates/issue.md`) 99 | ```markdown 100 | # 标题 101 | 简短的问题标题 102 | 103 | # 简介 104 | 详细的问题描述 105 | 106 | # 任务 107 | - [ ] 任务 1 108 | - [ ] 任务 2 109 | 110 | # 依赖关系 111 | - [ ] {id} 依赖描述 112 | 113 | # 状态历史 114 | - YYYY-MM-DD: 创建 115 | ``` 116 | 117 | ## 入门指南 118 | 119 | 1. 克隆此仓库 120 | 2. 在你的项目中创建 `.issues` 目录 121 | 3. 将 `local-issues.mdc` 复制到你的项目 cursor rules 目录 122 | 4. 从 `issues-template/templates` 复制模板到 `.issues/templates` 123 | 5. 查看 `issues-template/sample` 中的示例以理解结构 124 | 6. 开始按照命名规范和使用模板创建你的问题 125 | 126 | ## 使用方法 127 | 128 | ### 创建新的里程碑 129 | 130 | 1. 在 `.issues/` 下创建新目录，使用模式 `m{number}-{description}` 131 | ```bash 132 | mkdir .issues/m001-user-authentication 133 | ``` 134 | 135 | ### 创建问题 136 | 137 | 1. **用户故事** 138 | - 复制故事模板 139 | - 分配唯一ID（如 001） 140 | - 填写用户故事部分 141 | - 列出验收标准 142 | - 添加将要实现此故事的子问题 143 | ```bash 144 | cp .issues/templates/story.md .issues/m001-user-authentication/001-story-login-system.md 145 | ``` 146 | 147 | 2. **功能/修复/测试问题** 148 | - 复制问题模板 149 | - 分配下一个可用ID 150 | - 选择适当的类型（feat/fix/test） 151 | - 列出具体任务 152 | - 链接到其他问题的依赖关系 153 | ```bash 154 | cp issues/templates/issue.md issues/m001-user-authentication/002-feat-login-page.md 155 | ``` 156 | 157 | ### 跟踪进度 158 | 159 | 1. 使用定义的标记更新任务状态： 160 | ```markdown 161 | - [x] 已完成的任务 162 | - [-] 进行中的任务 163 | - [ ] 未开始的任务 164 | - [*] 已跳过的任务 165 | - [!] 已放弃的任务 166 | ``` 167 | 168 | 2. 更改状态时始终更新状态历史： 169 | ```markdown 170 | # 状态历史 171 | - 2024-01-08: 创建 172 | - 2024-01-09: 开始实现 173 | - 2024-01-10: 完成基本功能 174 | ``` 175 | 176 | ### 管理依赖关系 177 | 178 | 1. 使用ID引用其他问题： 179 | ```markdown 180 | # 依赖关系 181 | - [ ] 001 父用户故事 182 | - [ ] 002 后端API实现 183 | ``` 184 | 185 | 2. 在将问题标记为完成前检查依赖关系 186 | 187 | ### 最佳工作流程实践 188 | 189 | 1. 首先创建里程碑目录 190 | 2. 从用户故事开始 191 | 3. 分解为实现问题 192 | 4. 定期更新状态 193 | 5. 保持依赖关系最新 194 | 6. 每日审查和更新任务状态 195 | 196 | ## 示例 197 | 198 | 查看 `issues-template/sample/m001-auth-system/` 中的示例实现，包括： 199 | - 用户认证故事 200 | - 登录页面实现 201 | - 测试套件 202 | - 缺陷修复任务 203 | 204 | ## 最佳实践 205 | 206 | 1. 始终使用提供的模板以保持一致性 207 | 2. 在所有问题中维护唯一ID 208 | 3. 保持状态历史更新 209 | 4. 清晰地记录依赖关系 210 | 5. 在文件名中使用有意义的描述 211 | 6. 在适当的里程碑下组织相关问题 212 | 213 | ## 编辑器集成 214 | 215 | ### Cursor 216 | - `local-issues.mdc` 文件在你的项目 cursor rules 目录中使 Cursor 能够理解问题管理结构 217 | - 使用 Cursor 的 markdown 预览查看问题 218 | - 利用 Cursor 的文件导航快速切换问题 219 | - 使用 Cursor 的搜索功能查找相关问题 220 | - Cursor 将帮助执行 `local-issues.mdc` 中定义的命名规范和结构 221 | 222 | ### VSCode 223 | - 安装 Markdown 预览扩展 224 | - 使用工作区文件夹组织里程碑 225 | - 使用集成终端创建新问题 226 | - 启用自动换行以提高可读性 227 | 228 | ## 项目进度跟踪 229 | 230 | 你可以通过以下几种方式跟踪项目进度： 231 | 1. **里程碑概览**：检查每个里程碑内问题的完成状态 232 | 2. **状态统计**：统计里程碑内各状态的问题数量 233 | 3. **依赖关系**：审查依赖关系图以识别瓶颈 234 | 4. **历史时间线**：查看问题的状态历史以了解进度 235 | 236 | ## 常见问题 237 | 238 | ### Q: 如何处理紧急修复？ 239 | A: 在当前里程碑中创建一个新的修复问题，在简介部分注明高优先级。链接到相关的故事或功能。 240 | 241 | ### Q: 如果需要将一个问题拆分为多个问题怎么办？ 242 | A: 创建新的问题，并在原始问题的子问题部分引用它们。更新原始任务以反映拆分。 243 | 244 | ### Q: 是否应该删除已完成的问题？ 245 | A: 不，保留所有问题以便历史追踪。使用状态标记表示完成。 246 | 247 | ## 贡献 248 | 249 | 欢迎贡献！请随时提交 Pull Request。 250 | 251 | ## 许可证 252 | 253 | 本项目采用 Apache License 2.0 许可证 - 查看 LICENSE 文件了解详情。 254 | 255 | Apache License 2.0 是一个宽松的许可证，允许你： 256 | - 将软件用于任何目的 257 | - 分发和修改软件 258 | - 明确授予专利权 259 | - 以任何许可证分发修改版本 260 | 261 | 该许可证还为用户提供了贡献者明确的专利权授权。 -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Local Issues Management System 2 | 3 | A structured template system for managing project issues locally. This system provides a clear, file-based approach to track user stories, features, bugs, and tests. 4 | 5 | English | [简体中文](README_zh.md) 6 | 7 | ## Table of Contents 8 | - [Features](#features) 9 | - [Directory Structure](#directory-structure) 10 | - [Issue Types](#issue-types) 11 | - [Issue States](#issue-states) 12 | - [File Naming Convention](#file-naming-convention) 13 | - [Templates](#templates) 14 | - [Getting Started](#getting-started) 15 | - [How to Use](#how-to-use) 16 | - [Example](#example) 17 | - [Best Practices](#best-practices) 18 | - [Editor Integration](#editor-integration) 19 | - [FAQ](#faq) 20 | - [Contributing](#contributing) 21 | - [License](#license) 22 | 23 | ## Features 24 | 25 | - 📁 Structured directory organization by milestones 26 | - 📝 Standardized templates for stories and issues 27 | - ✅ Clear task state tracking 28 | - 🔗 Built-in dependency management 29 | - 📊 Progress tracking through status history 30 | 31 | ## Directory Structure 32 | 33 | ``` 34 | .issues/ 35 | ├── templates/ 36 | │ ├── story.md 37 | │ └── issue.md 38 | ├── m001-project-milestone/ 39 | │ ├── 001-story-feature-description.md 40 | │ ├── 002-feat-implementation.md 41 | │ ├── 003-test-test-suite.md 42 | │ └── 004-fix-bug-fix.md 43 | └── m002-another-milestone/ 44 | └── ... 45 | ``` 46 | 47 | ## Issue Types 48 | 49 | - `story`: User stories describing complete user value 50 | - `feat`: New feature implementation 51 | - `fix`: Bug fix implementation 52 | - `test`: Test implementation 53 | 54 | ## Issue States 55 | 56 | - `[ ]` Not started 57 | - `[x]` Completed 58 | - `[-]` In progress 59 | - `[*]` Skipped 60 | - `[!]` Abandoned 61 | 62 | ## File Naming Convention 63 | 64 | Files follow the pattern: `{id}-{type}-{description}.md` 65 | 66 | - `id`: Globally unique identifier across all issues 67 | - `type`: Issue type (story/feat/fix/test) 68 | - `description`: Brief kebab-case description 69 | 70 | ## Templates 71 | 72 | Two standard templates are provided: 73 | 74 | 1. Story Template (`templates/story.md`) 75 | ```markdown 76 | # Title 77 | Brief story title 78 | 79 | # Story 80 | As a [role] 81 | I want [goal/action] 82 | So that [benefit/value] 83 | 84 | # Acceptance Criteria 85 | - [ ] Criteria 1 86 | - [ ] Criteria 2 87 | 88 | # Sub-Issues 89 | - [ ] {id} Issue description 90 | 91 | # Dependencies 92 | - [ ] {id} Dependency description 93 | 94 | # Status History 95 | - YYYY-MM-DD: Created 96 | ``` 97 | 98 | 2. Issue Template (`templates/issue.md`) 99 | ```markdown 100 | # Title 101 | Brief issue title 102 | 103 | # Introduction 104 | Detailed description of the issue 105 | 106 | # Tasks 107 | - [ ] Task 1 108 | - [ ] Task 2 109 | 110 | # Dependencies 111 | - [ ] {id} Dependency description 112 | 113 | # Status History 114 | - YYYY-MM-DD: Created 115 | ``` 116 | 117 | ## Getting Started 118 | 119 | 1. Clone this repository 120 | 2. Create an `.issues` directory in your project 121 | 3. Copy `local-issues.mdc` to your project cursor rules directory 122 | 4. Copy the templates from `issues-template/templates` to `.issues/templates` 123 | 5. Review the sample in `issues-template/sample` to understand the structure 124 | 6. Start creating your issues following the naming conventions and using the templates 125 | 126 | ## How to Use 127 | 128 | ### Creating a New Milestone 129 | 130 | 1. Create a new directory under `.issues/` with the pattern `m{number}-{description}` 131 | ```bash 132 | mkdir .issues/m001-user-authentication 133 | ``` 134 | 135 | ### Creating Issues 136 | 137 | 1. **User Story** 138 | - Copy the story template 139 | - Assign a unique ID (e.g., 001) 140 | - Fill in the user story sections 141 | - List acceptance criteria 142 | - Add sub-issues that will implement this story 143 | ```bash 144 | cp .issues/templates/story.md .issues/m001-user-authentication/001-story-login-system.md 145 | ``` 146 | 147 | 2. **Feature/Fix/Test Issues** 148 | - Copy the issue template 149 | - Assign the next available ID 150 | - Choose appropriate type (feat/fix/test) 151 | - List specific tasks 152 | - Link dependencies to other issues 153 | ```bash 154 | cp issues/templates/issue.md issues/m001-user-authentication/002-feat-login-page.md 155 | ``` 156 | 157 | ### Tracking Progress 158 | 159 | 1. Update task states using the defined markers: 160 | ```markdown 161 | - [x] Completed task 162 | - [-] Task in progress 163 | - [ ] Not started task 164 | - [*] Skipped task 165 | - [!] Abandoned task 166 | ``` 167 | 168 | 2. Always update the Status History when changing states: 169 | ```markdown 170 | # Status History 171 | - 2024-01-08: Created 172 | - 2024-01-09: Started implementation 173 | - 2024-01-10: Completed basic features 174 | ``` 175 | 176 | ### Managing Dependencies 177 | 178 | 1. Reference other issues using their IDs: 179 | ```markdown 180 | # Dependencies 181 | - [ ] 001 Parent user story 182 | - [ ] 002 Backend API implementation 183 | ``` 184 | 185 | 2. Check dependencies before marking an issue as complete 186 | 187 | ### Best Workflow Practices 188 | 189 | 1. Create the milestone directory first 190 | 2. Start with a user story 191 | 3. Break down into implementation issues 192 | 4. Update status regularly 193 | 5. Keep dependencies up to date 194 | 6. Review and update task states daily 195 | 196 | ## Example 197 | 198 | Check out the sample implementation in `issues-template/sample/m001-auth-system/` for a complete example of: 199 | - User authentication story 200 | - Login page implementation 201 | - Test suite 202 | - Bug fix task 203 | 204 | ## Best Practices 205 | 206 | 1. Always use the provided templates for consistency 207 | 2. Maintain unique IDs across all issues 208 | 3. Keep the status history updated 209 | 4. Document dependencies clearly 210 | 5. Use meaningful descriptions in file names 211 | 6. Group related issues under appropriate milestones 212 | 213 | ## Editor Integration 214 | 215 | ### Cursor 216 | - The `local-issues.mdc` file in your project cursor rules directory enables Cursor to understand the issue management structure 217 | - Use Cursor's markdown preview to view issues 218 | - Utilize Cursor's file navigation to quickly switch between issues 219 | - Use Cursor's search functionality to find related issues 220 | - Cursor will help enforce naming conventions and structure defined in `local-issues.mdc` 221 | 222 | ### VSCode 223 | - Install a Markdown preview extension 224 | - Use workspace folders to organize milestones 225 | - Use the integrated terminal for creating new issues 226 | - Enable word wrap for better readability 227 | 228 | ## Project Progress Tracking 229 | 230 | You can track project progress in several ways: 231 | 1. **Milestone Overview**: Check the completion status of issues within each milestone 232 | 2. **Status Counts**: Count issues by their status within a milestone 233 | 3. **Dependencies**: Review the dependency graph to identify bottlenecks 234 | 4. **History Timeline**: Review status history across issues to understand progress 235 | 236 | ## FAQ 237 | 238 | ### Q: How should I handle urgent hotfixes? 239 | A: Create a new fix issue in the current milestone with a high priority note in the introduction section. Link it to the relevant story or feature. 240 | 241 | ### Q: What if I need to split an issue into multiple issues? 242 | A: Create new issues and update the original issue to reference them in the Sub-Issues section. Update the original tasks to reflect the split. 243 | 244 | ### Q: Should I delete completed issues? 245 | A: No, keep all issues for historical tracking. Use the status markers to indicate completion. 246 | 247 | ## Contributing 248 | 249 | Contributions are welcome! Please feel free to submit a Pull Request. 250 | 251 | ## License 252 | 253 | This project is licensed under the Apache License 2.0 - see the LICENSE file for details. 254 | 255 | The Apache License 2.0 is a permissive license that allows you to: 256 | - Use the software for any purpose 257 | - Distribute and modify the software 258 | - Patent rights are explicitly granted 259 | - Distribute modified versions under any license of your choice 260 | 261 | This license also provides an express grant of patent rights from contributors to users. 262 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2024 LocalIssues 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at 6 | 7 | http://www.apache.org/licenses/LICENSE-2.0 8 | 9 | Unless required by applicable law or agreed to in writing, software 10 | distributed under the License is distributed on an "AS IS" BASIS, 11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | See the License for the specific language governing permissions and 13 | limitations under the License. 14 | 15 | Apache License 16 | Version 2.0, January 2004 17 | http://www.apache.org/licenses/ 18 | 19 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 20 | 21 | 1. Definitions. 22 | 23 | "License" shall mean the terms and conditions for use, reproduction, 24 | and distribution as defined by Sections 1 through 9 of this document. 25 | 26 | "Licensor" shall mean the copyright owner or entity authorized by 27 | the copyright owner that is granting the License. 28 | 29 | "Legal Entity" shall mean the union of the acting entity and all 30 | other entities that control, are controlled by, or are under common 31 | control with that entity. For the purposes of this definition, 32 | "control" means (i) the power, direct or indirect, to cause the 33 | direction or management of such entity, whether by contract or 34 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 35 | outstanding shares, or (iii) beneficial ownership of such entity. 36 | 37 | "You" (or "Your") shall mean an individual or Legal Entity 38 | exercising permissions granted by this License. 39 | 40 | "Source" form shall mean the preferred form for making modifications, 41 | including but not limited to software source code, documentation 42 | source, and configuration files. 43 | 44 | "Object" form shall mean any form resulting from mechanical 45 | transformation or translation of a Source form, including but 46 | not limited to compiled object code, generated documentation, 47 | and conversions to other media types. 48 | 49 | "Work" shall mean the work of authorship, whether in Source or 50 | Object form, made available under the License, as indicated by a 51 | copyright notice that is included in or attached to the work 52 | (an example is provided in the Appendix below). 53 | 54 | "Derivative Works" shall mean any work, whether in Source or Object 55 | form, that is based on (or derived from) the Work and for which the 56 | editorial revisions, annotations, elaborations, or other modifications 57 | represent, as a whole, an original work of authorship. For the purposes 58 | of this License, Derivative Works shall not include works that remain 59 | separable from, or merely link (or bind by name) to the interfaces of, 60 | the Work and Derivative Works thereof. 61 | 62 | "Contribution" shall mean any work of authorship, including 63 | the original version of the Work and any modifications or additions 64 | to that Work or Derivative Works thereof, that is intentionally 65 | submitted to Licensor for inclusion in the Work by the copyright owner 66 | or by an individual or Legal Entity authorized to submit on behalf of 67 | the copyright owner. For the purposes of this definition, "submitted" 68 | means any form of electronic, verbal, or written communication sent 69 | to the Licensor or its representatives, including but not limited to 70 | communication on electronic mailing lists, source code control systems, 71 | and issue tracking systems that are managed by, or on behalf of, the 72 | Licensor for the purpose of discussing and improving the Work, but 73 | excluding communication that is conspicuously marked or otherwise 74 | designated in writing by the copyright owner as "Not a Contribution." 75 | 76 | "Contributor" shall mean Licensor and any individual or Legal Entity 77 | on behalf of whom a Contribution has been received by Licensor and 78 | subsequently incorporated within the Work. 79 | 80 | 2. Grant of Copyright License. Subject to the terms and conditions of 81 | this License, each Contributor hereby grants to You a perpetual, 82 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 83 | copyright license to reproduce, prepare Derivative Works of, 84 | publicly display, publicly perform, sublicense, and distribute the 85 | Work and such Derivative Works in Source or Object form. 86 | 87 | 3. Grant of Patent License. Subject to the terms and conditions of 88 | this License, each Contributor hereby grants to You a perpetual, 89 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 90 | (except as stated in this section) patent license to make, have made, 91 | use, offer to sell, sell, import, and otherwise transfer the Work, 92 | where such license applies only to those patent claims licensable 93 | by such Contributor that are necessarily infringed by their 94 | Contribution(s) alone or by combination of their Contribution(s) 95 | with the Work to which such Contribution(s) was submitted. If You 96 | institute patent litigation against any entity (including a 97 | cross-claim or counterclaim in a lawsuit) alleging that the Work 98 | or a Contribution incorporated within the Work constitutes direct 99 | or contributory patent infringement, then any patent licenses 100 | granted to You under this License for that Work shall terminate 101 | as of the date such litigation is filed. 102 | 103 | 4. Redistribution. You may reproduce and distribute copies of the 104 | Work or Derivative Works thereof in any medium, with or without 105 | modifications, and in Source or Object form, provided that You 106 | meet the following conditions: 107 | 108 | (a) You must give any other recipients of the Work or 109 | Derivative Works a copy of this License; and 110 | 111 | (b) You must cause any modified files to carry prominent notices 112 | stating that You changed the files; and 113 | 114 | (c) You must retain, in the Source form of any Derivative Works 115 | that You distribute, all copyright, patent, trademark, and 116 | attribution notices from the Source form of the Work, 117 | excluding those notices that do not pertain to any part of 118 | the Derivative Works; and 119 | 120 | (d) If the Work includes a "NOTICE" text file as part of its 121 | distribution, then any Derivative Works that You distribute must 122 | include a readable copy of the attribution notices contained 123 | within such NOTICE file, excluding those notices that do not 124 | pertain to any part of the Derivative Works, in at least one 125 | of the following places: within a NOTICE text file distributed 126 | as part of the Derivative Works; within the Source form or 127 | documentation, if provided along with the Derivative Works; or, 128 | within a display generated by the Derivative Works, if and 129 | wherever such third-party notices normally appear. The contents 130 | of the NOTICE file are for informational purposes only and 131 | do not modify the License. You may add Your own attribution 132 | notices within Derivative Works that You distribute, alongside 133 | or as an addendum to the NOTICE text from the Work, provided 134 | that such additional attribution notices cannot be construed 135 | as modifying the License. 136 | 137 | You may add Your own copyright statement to Your modifications and 138 | may provide additional or different license terms and conditions 139 | for use, reproduction, or distribution of Your modifications, or 140 | for any such Derivative Works as a whole, provided Your use, 141 | reproduction, and distribution of the Work otherwise complies with 142 | the conditions stated in this License. 143 | 144 | 5. Submission of Contributions. Unless You explicitly state otherwise, 145 | any Contribution intentionally submitted for inclusion in the Work 146 | by You to the Licensor shall be under the terms and conditions of 147 | this License, without any additional terms or conditions. 148 | Notwithstanding the above, nothing herein shall supersede or modify 149 | the terms of any separate license agreement you may have executed 150 | with Licensor regarding such Contributions. 151 | 152 | 6. Trademarks. This License does not grant permission to use the trade 153 | names, trademarks, service marks, or product names of the Licensor, 154 | except as required for reasonable and customary use in describing the 155 | origin of the Work and reproducing the content of the NOTICE file. 156 | 157 | 7. Disclaimer of Warranty. Unless required by applicable law or 158 | agreed to in writing, Licensor provides the Work (and each 159 | Contributor provides its Contributions) on an "AS IS" BASIS, 160 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 161 | implied, including, without limitation, any warranties or conditions 162 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 163 | PARTICULAR PURPOSE. You are solely responsible for determining the 164 | appropriateness of using or redistributing the Work and assume any 165 | risks associated with Your exercise of permissions under this License. 166 | 167 | 8. Limitation of Liability. In no event and under no legal theory, 168 | whether in tort (including negligence), contract, or otherwise, 169 | unless required by applicable law (such as deliberate and grossly 170 | negligent acts) or agreed to in writing, shall any Contributor be 171 | liable to You for damages, including any direct, indirect, special, 172 | incidental, or consequential damages of any character arising as a 173 | result of this License or out of the use or inability to use the 174 | Work (including but not limited to damages for loss of goodwill, 175 | work stoppage, computer failure or malfunction, or any and all 176 | other commercial damages or losses), even if such Contributor 177 | has been advised of the possibility of such damages. 178 | 179 | 9. Accepting Warranty or Additional Liability. While redistributing 180 | the Work or Derivative Works thereof, You may choose to offer, 181 | and charge a fee for, acceptance of support, warranty, indemnity, 182 | or other liability obligations and/or rights consistent with this 183 | License. However, in accepting such obligations, You may act only 184 | on Your own behalf and on Your sole responsibility, not on behalf 185 | of any other Contributor, and only if You agree to indemnify, 186 | defend, and hold each Contributor harmless for any liability 187 | incurred by, or claims asserted against, such Contributor by reason 188 | of your accepting any such warranty or additional liability. 189 | 190 | END OF TERMS AND CONDITIONS 191 | 192 | APPENDIX: How to apply the Apache License to your work. 193 | 194 | To apply the Apache License to your work, attach the following 195 | boilerplate notice, with the fields enclosed by brackets "[]" 196 | replaced with your own identifying information. (Don't include 197 | the brackets!) The text should be enclosed in the appropriate 198 | comment syntax for the file format. We also recommend that a 199 | file or class name and description of purpose be included on the 200 | same "printed page" as the copyright notice for easier 201 | identification within third-party archives. --------------------------------------------------------------------------------