
技术团队提出:项目中所有产出物都应进行版本管理
来源标题:Version Everything
一位团队负责人提出,软件项目中所有产出物都应加版本号,而不只是软件发布。提案、设计文档、Figma 设计、信息架构、变更请求甚至发布说明都要有版本,便于对比改动、锁定讨论对象。开发者已由 CI/CD 自动生成版本号,其他部门则需手动维护,作者认为这点投入后续回报很大。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
在开始任何软件项目之前,我给团队定的第一条规则就是:一切都要有版本。大多数人只把版本和软件发布联系在一起,但我希望项目里的每一样东西都有版本,不管它来自哪个部门——提案、设计文档、Figma 设计稿、信息架构、变更请求,甚至发布说明。
你们已经知道版本为什么有用。版本标记的是内容处于稳定、已评审或已批准状态的那个时间点。有了版本,就能轻松比较两个版本,看清批准之后改了什么。讨论时,大家也能指向同一个东西:“我们说的是 v1.2”,而不是“我上周发的最新那版”。
开发人员早就给自己的软件发布打版本号了。大多数情况下,CI/CD 流水线会在构建过程中生成版本号,所以没人需要为这件事费心。这些版本号随后会出现在 Jira 工单、发布说明、缺陷报告等地方。
其他部门通常不会给自己的产出打版本。他们不习惯这么做,而且这需要一些手动操作。我仍然坚持这样做,因为这点小小的付出,后面会成倍地回报你。
在 Figma 里工作的 UI 设计师,可能会在首次批准之后的每一个变更请求中,反复更新同一份设计稿。几轮下来,就没人知道当初批准的到底是哪一版了。
我的规则很简单:设计稿一旦经过评审或批准,就给它一个版本号(比如 v1.0),然后复制一份,在新副本上继续做新的改动。绝不要碰已批准的版本。当副本获得批准后,它就成为 v2.0,下一轮改动再另起一个副本。小改动则给一个小版本号,比如 v2.1。
我还要求设计师把各个版本并排放置,方便对比。变更日志也是很好的补充,我的设计师一直都会维护一份。
每一份与客户或团队共享的文档里都必须带版本号。我通常会让文档停留在 v0.1—DRAFT、v0.2—DRAFT 等状态,直到它被批准,第一个获批的版本就成为 v1.0。文档还应该有版本历史(或变更日志),清楚地说明哪些章节发生了变化、具体改了什么。
版本一旦获批,我会把它记录在项目文档或 Jira 工单里——版本号、日期,以及指向 PDF 格式文档的链接。
注意:任何版本命名方案都可以(比如 SemVer 或 CalVer),只要每个人都能清楚地识别某份文档,并能回溯到那个时间点的版本就行。
当文件在你掌控之中时,版本管理效果很好。但有时我会收到来自另一方、没有版本号的文件,而我又没法让他们加上版本号。我仍然需要在文档和工单里引用这些文件。
例如,客户的设计团队可能分享了一个 HTML 原型或 PDF,但没有版本号。后来他们的设计师更新了原型,又发了一次——文件名还一样。现在就有两个不同文件、同一个名字,而我需要确切知道我的文档指的是哪一个。
遇到这种情况,我用文件的 SHA256 校验和来代替版本号。校验和就像文件内容的指纹:哪怕只改动一个字节,校验和也会完全改变。我把校验和写进文档,把文件上传到在线网盘中文档旁边,并把那份副本永久保存在那里。
假设我正在处理一个变更请求,要给公司历史页面加一条时间线,客户的设计团队分享了一个名为 Company_History_Timeline.html 的文件。
首先,我计算该文件的 SHA256 校验和:
macOS
$ shasum -a 256 Company_History_Timeline.html 7e25874bb9e0e1cf3c29c5c402b484e3745e3e0fb2de623f18c15e232a83d31b Company_History_Timeline.html
Linux: sha256sum Company_History_Timeline.html
Windows PowerShell: Get-FileHash Company_History_Timeline.html
然后我把它写进文档: 接着我把这个 HTML 文件上传到在线网盘,就放在文档旁边。
现在任何人都能核对自己拿到的是不是正确的文件。他们只需运行同样的命令,比对校验和即可。最妙的是,校验和只取决于文件内容,与文件名无关。即使有人之后重命名了文件,校验和依然匹配。
一周后,设计团队发来了新版本的原型,文件名还是一样。我算出新的校验和,并这样更新文档: 两份文件都留在网盘里,我的每一版文档都精确指向其中一份。再也不用猜我们说的是哪个 Company_History_Timeline.html 了。
如果客户分享的是链接而不是文件呢?比如 Figma 设计稿、Google Doc 或某个在线工具的链接。这些内容随时可能被编辑,哪怕我已经在文档里引用了它,链接也总是显示最新状态。
这种情况下,我会做快照:导出为 PDF 或截图,把它们连同各自的 SHA256 校验和一起放进文档。这样,我就始终保有一份记录,说明我引用该链接时它长什么样。
给一切打版本,在管理软件项目上帮了我大忙。我可以追踪每一次变更,更重要的是,避免了很多与团队和客户之间的冲突和混乱。
一开始需要一点自律,但一旦团队习惯了,它就会变成第二天性。你再也不用问“哪个才是最终文件?”了。
写这篇文章时,我想起了这个经典梗图 :)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。