Organice项目开发指南与协作规范

Organice项目开发指南与协作规范

项目概述

Organice是一个基于Web的Org模式编辑器，它允许用户通过浏览器访问和管理Org模式文件。该项目采用现代前端技术栈开发，旨在为Org模式用户提供便捷的跨平台访问体验。

问题报告与功能请求

区分Bug与功能请求

在提交问题前，开发者需要明确区分以下概念：

1. Bug报告：指现有功能无法正常工作的情况
2. 功能请求：包括对现有功能的改进建议或全新功能的建议

特别需要注意的是，如果Emacs Org模式具备某项功能而Organice尚未实现，这属于功能请求而非Bug。

提交问题的正确流程

1. 问题查重：在提交前应确认该问题未被他人报告过
2. 文档查阅：检查项目文档确认是否为已知行为
3. 规范提交：
   • 使用标准模板提交Bug报告或功能请求
   • 确保问题描述清晰完整
   • 对于非Bug/功能类问题，可直接创建空白issue

问题管理机制

Organice采用严格的问题管理策略以确保项目质量：

1. 问题留存标准：
   • 有明确负责人承诺开发
   • 确认为Bug或功能退化问题
2. 问题处理流程：
   • 对不明确的问题会标记为"question"
   • 5天内无响应将关闭issue
   • 后续可重新开启有效讨论

文档贡献指南

Organice的文档系统基于Org模式文件构建，主要包括：

1. README.org主文档文件
2. 其他辅助文档资源
3. 自动生成的文档系统

文档贡献者需要了解项目的文档构建流程，确保修改符合整体文档架构。

开发协作流程

Organice采用规范的开发工作流，主要步骤如下：

1. 需求描述

采用用户故事(User Story)格式：

作为<角色>，当<条件>时，我需要<功能>，以便<价值>

2. 分支管理

• 分支命名规范：(feature|fix|chore)/issue-id/简短描述
• 重大架构变更需编写架构决策记录(ADR)

3. 开发规范

代码格式化

• 使用prettier-eslint组合工具
• 配置了统一的.prettierrc.json和.eslintrc.yml
• 支持批量格式化或差异检查

代码质量

• 必须通过ESLint检查
• 建议使用渐进式修复工具(nibble)
• 集成检查命令yarn lint

4. 提交流程

1. 本地开发并通过测试
2. 创建PR到master分支
3. CI测试通过
4. 核心团队审核合并

完成标准(Definition of Done)

功能开发被认为完成需满足以下条件：

1. 功能实现：

   • 完成核心功能开发
   • 通过功能验证测试
   • 完成关联功能回归测试

2. 代码审查：

   • 符合代码风格规范
   • 包含适当测试用例
   • 遵循Clean Code原则
   • 完善的代码文档

3. 发布准备：

   • 代码已合并到主分支
   • 通过目标浏览器兼容性测试

代码质量指南

Organice遵循以下Clean Code实践：

1. 模块设计：

   • 保持模块小巧且高内聚
   • 避免过长的模块和类
   • 通过职责分离提取模块

2. 方法设计：

   • 保持方法简短
   • 避免过长方法
   • 单一职责原则
   • 一个方法只做一件事

通过遵循这些规范，Organice项目保持了较高的代码质量和可维护性，为开发者提供了清晰的协作框架。无论是修复问题还是添加新功能，开发者都能按照这套规范高效地参与项目开发。