Wasp-lang/open-saas项目文档与演示应用分支管理优化实践

在开源项目wasp-lang/open-saas的开发过程中，团队发现当前将文档和演示应用(demo app)放在与主模板不同的分支(deployed-version)上的做法存在一些不合理之处。这种分离的管理方式给项目维护带来了诸多不便，需要重新思考更优的代码组织结构。

当前分支管理的问题分析

目前项目采用main分支存放核心模板代码，而deployed-version分支则包含文档和演示应用。这种设计主要带来三个明显问题：

1. 开发流程割裂：开发者无法在同一个PR中同时更新模板和对应的文档/演示应用，必须分别提交两次修改
2. 维护成本增加：相同的变更需要在两个分支上重复实施，增加了工作量和出错概率
3. 同步困难：随着项目演进，保持演示应用与模板的同步变得越来越复杂

潜在解决方案探讨

团队经过深入讨论，提出了几种可能的改进方案：

目录分离方案

将不同功能模块组织到项目内的不同目录中：

• template/目录存放核心模板代码
• open-saas-sh/目录存放演示应用
• docs/目录存放文档

这种结构的优势在于：

• 允许在单个PR中完成所有相关修改
• 保持代码库的整洁和一致性
• 便于开发者理解项目结构

独立仓库方案

将演示应用完全分离到另一个独立的代码仓库中。虽然这在概念上更清晰，但实际维护上可能带来新的挑战，如跨仓库同步问题。

补丁文件方案

通过创建补丁文件来管理演示应用与模板之间的差异。这种方法理论上可以自动化同步过程，但实现复杂度较高，可能引入新的维护负担。

最终决策与实施

经过权衡，团队决定采用目录分离方案作为最佳实践。这一选择基于以下考虑：

1. 开发效率：允许开发者在单一提交中完成模板、文档和演示应用的协同修改
2. 维护简便：相比分支分离或独立仓库，目录结构更直观且易于管理
3. 用户体验：配合wasp new -t saas命令，为用户提供清晰的模板获取方式

在实施过程中，团队还特别关注了如何简化演示应用的更新流程。通过分析，发现演示应用与核心模板的差异主要集中在几个特定方面：

• 少量UI调整
• 部分功能启用/禁用
• 特定配置项的预设值

这些差异相对固定且易于管理，使得目录分离方案在实际操作中具有可行性。

经验总结

这一架构调整为项目带来了显著的维护性提升，主要经验包括：

1. 单一职责原则：每个目录具有明确的功能边界，降低认知负担
2. 协同开发：促进模板、文档和演示应用的同步演进
3. 简化流程：减少重复工作，提高开发效率

对于类似的开源项目，这一实践提供了有价值的参考：当项目包含多个密切相关但又有差异的组件时，通过合理的目录组织而非分支分离来管理这些组件，往往能带来更好的长期维护体验。