是否应该使用提交历史记录将关键信息传达给开发人员？

#1 楼

如果我打算升级到第三方SDK的较新版本，那么我最后要看的是源代码管理系统的历史。

如果您的产品使用的是SDK的2.0版，并且有人有兴趣升级到3.0，我认为认为他们应该及时在源代码控制系统中倒退以查找是不合理的。这不是一个好主意。

这里，我们有一个团队Wiki，其中包含一些页面，其中包含每个开发人员都可以阅读的有趣信息（编码约定，如何设置开发环境来构建产品，您需要哪些第三方的东西）安装等）。这是一个适合警告不要升级第三方库的地方。

#2 楼

应该在提交历史记录中注明，但是放置通知的绝对最佳位置是在定义依赖项的相同位置。例如，如果您有一个声明您的工件依赖项的maven .pom文件，我将执行以下操作：

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

在<dependency>行的正上方。

问题123将包含有关崩溃的详细信息，您导致崩溃的更新版本，然后可能应将其重新添加到待办事项列表中，以供日后再次使用-可能还有一个更新的版本解决此问题。通过自动编辑故障单，或者自己手动，它将向团队发送电子邮件以立即告知他们当前的问题，并且通过进入跟踪器，人们可以稍后再次找到它。

原因将其与依赖项声明放在一起是因为任何想要更改版本的人都会在他们想要更改它的时刻看到它，并了解为什么不应该这样做。

我不会在源代码中发表评论代码，因为我可以轻松地描绘出有人检查您的依赖项并开始升级它们的情况。他们不需要为每个TODO注释而去搜索代码库。

链接到问题单可以使好奇的开发人员知道它是如何失败的，并可能在以后重新访问。没有它，它可能会变得相当静态并且永远不会再次更新。

#3 楼

重要的和非直觉的信息应该记录下来，以便人们在考虑信息时会去寻找。

对于我所从事的团队和项目，我将回撤带有评论的内容关于新版本失败的原因。如果新版本得到修复，我会添加积压的故事来重试升级。我会在链接库的构建系统/构建脚本中添加注释。

回滚将为将来的开发人员在查看项目的历史记录时提供上下文。积压的故事使此升级成为该项目的积极组成部分。构建系统注释恰好是在库最终更新时需要进行更改的地方。

我不会在代码中注释它，也不会将其添加到自述文件中。考虑尝试升级的开发人员不会关注这些内容。如果您确实将其添加到此处，则最终解决了库问题并完成升级后，您将需要删除它。通常会忘记这一步：产生与项目相反的注释。


如果您的项目具有不同的设置或流程，则答案可能会有所不同。我认为关键是要正确处理信息，以便开发人员在进行升级工作时看到信息。这样，如果升级的时间不合适，开发人员将看到它并停止，并且当时间合适时，开发人员将看到它并删除注释，以免将来的开发人员感到困惑。

#4 楼

我想通过在回答中强调他的重要思想来给予马修的评论更多的关注。有一个您不想升级SDK的原因，并且应该在单元测试中捕获该原因。不是检查修订版本号，而是实际的根本原因。
例如，说新版本中有一个错误。编写一个检查该错误的单元测试。如果他们以后在SDK中修复了该错误，则升级将顺利进行。如果有不兼容的API更改，请编写测试以检查您的代码是否支持新API或SDK是否支持旧API。与单元测试相比，这更多的是集成测试，但仍然应该可行。

我的公司每天产生50多个提交，而我们的规模还不算很大。即使每个开发人员都阅读了每条提交消息（坦率地说他们没有读），我们需要记录的提交历史的全部原因是因为人们不记得了。除非有问题，否则人们不会再回头阅读历史记录。而且，他们没有理由怀疑到目前为止尚未发生的升级问题。

通过所有方式发送电子邮件以防止近期内重复工作，并注意它在您的构建脚本和自述文件或勘误表中。但是，特别是如果新版本的问题很细微并且需要花费大量时间进行故障排除，则需要一种使其变得明显的方法。这意味着单元测试。

评论

---

这是一个真实的答案。在单元测试中捕获失败可防止发生不良升级。期。

–德克·贝斯特（Dirk Bester）
2014年12月21日在1:09

---

#5 楼

我将问题重播为“是否仅通过提交消息将发现的关键信息传达给团队的其他成员？”因为我认为很明显不，您不应该这样做。我努力交流很多（根据我的经验，大多数开发团队都需要努力），并且我当然会尽一切努力避免造成陷阱或让他们撒谎。

如果通过票证触发了导致此类发现的一系列操作，那么我将更新票证（并确保应该知道此事的人员具有可见性），我可能会面对面提及（希望至少能使人对“ Gee，我想Damon说了一些有关更新该内容的想法”感到）恼），并且我当然会在包含SDK的那一点上在代码中留下评论，以便没人能更新它而没有机会看到它。我可能还会看看是否也可以将其塞入我们的开发Wiki上的某个位置，尽管这样做的目的更多是为了将来的员工，而不是当前的团队。

与之相比只花了几分钟的时间遇到和发现问题所花费的时间。我当然不会决定将其作为文档中使用最少的低信号部分之一，而留给我们。

#6 楼

它应该在提交历史记录中，但不仅应该在提交历史记录中，想象一下您雇用了一名新开发人员。您是否希望新开发人员阅读项目过去10年中的所有提交消息，因为其中有几个对理解您的代码库至关重要？

第二种情况，而不是代码更改，是否要提交“文档”提交，以便您可以按照“来自修订版5432的提交消息现在不正确”的行添加提交消息，这是当前情况。“

#7 楼

我不确定您的团队如何沟通，但我认为最有效的表达方式是先发送并发送电子邮件至团队的电子邮件组，标为“紧急”，并在正文中写上


伙计们，我们不能使用SDK v xyz，因为它会导致Foo缓冲区溢出并且Bar服务将崩溃。坚持使用x.y.y版本。


这就是我们在这里所做的，这是在其中发布消息的最可靠方法。如果您真的想挑剔（如果您的电子邮件系统允许），请在电子邮件中索取“已读回执”。

一旦您告诉了整个团队，就应该放置更详细的文档进入团队Wiki。具体取决于您的文档结构。如果您有专门针对您的应用程序“依赖关系和需求”的部分，那将是添加它的好地方。

记录此类问题的另一个地方可能是源代码本身，尽管可能并不总是有效。如果仅在一个或两个明显的地方引用了SDK version ...，则可以包括有关不升级的注意事项。

源代码管理中的文件历史记录可能很长，并且取决于开发人员，可能会有多个条目每天。某个已经休假一周的人可能没有时间阅读一周的提交历史记录。 README文件是一个更好的地方，因为它位于中心位置，人们可能更倾向于阅读它，但是您不能确保每个人都会真正阅读README。好吧，我想他们可能会发现他们已经改变了...

#8 楼

像这样的东西应该放在提交注释中，但是也会从其他地方受益。

谁决定升级，谁都需要有事实。该人可能不在源代码管理中。如果有人会在SO上阅读有关此问题的信息而从未将其放入代码库中怎么办？

需要有关此第三方SDK的某种文档。


它解决什么问题？
为什么这个特殊的SDK？
选择了什么？
需要考虑哪些因素：版本，升级，测试等。
谁来做这个决定？

你遇到这样的情况它的版本控制中，您应该建议每个人都尽可能使用此信息。只有您的团队才能决定某人将在任何文档，源代码控制或错误跟踪器中进行搜索的地方，以获取有关该主题的尽可能多的信息。否则，您会忘记，总有人会这样做，如果它慢跑了某人的记忆并迅速将其回滚，您将很幸运。

#9 楼

我认为这种情况有两个基本问题，可能是三个。


不需要的SDK升级使其成为源代码，可能会对产品产生负面影响。
：进行了不必要的升级的贡献者不知道以前是否做出不升级的特定决定。

，我认为其中第一个是最严重的。如果不需要的SDK升级可以将其纳入代码中，那么其他问题也可以解决。

有人建议添加一个单元测试用例，如果检测到升级，该用例将失败。虽然它将阻止升级的发生，但我认为这是一条危险的道路，随着时间的流逝会导致熔岩流。似乎不可避免地会在将来的某个时刻对SDK进行升级，以引入新功能或错误修正，或者是因为不再支持旧版本。试想一下，当这样的单元测试失败时，会发生令人头疼甚至是争论的事情。

我认为最通用的解决方案是调整开发过程。对于git，请使用拉取请求过程。对于Subversion和较旧的工具，请使用branch和diff。但是，有一些过程可以使高级开发人员在将这些问题纳入代码库之前就将其捕获并影响其他开发人员。

如果您的情况已使用了拉取请求过程，并且拉取请求狭窄且具体，不会浪费太多时间。将会提交升级SDK的请求请求，并拒绝提供不希望升级的评论。没有其他人会受到影响，并且现在就无需还原SDK升级。

但是要直接回答最初的问题，我同意其他人的看法，希望所有开发人员都可以完整阅读全部内容。代码的修订历史记录，发行说明等，这样的通知浪费了宝贵的时间。简短的团队电子邮件有什么问题？

可能的第三个问题：为什么首先不希望升级？显然，至少有一个开发人员认为升级将是一件好事。有很多好的理由推迟升级，但也有很多不好的理由。注意避免产生熔岩流（不必要的向后兼容代码）和货物崇拜（“我们无法升级，但我不知道为什么”）反模式！

#10 楼

历史是放置数据的好地方，这些数据供有意识地在寻找数据的读者使用，并且对应该存放的位置有大致的了解。放置必须提供给用户而不是进行搜索的数据是一个非常糟糕的地方。

历史是相对未排序的文本非常大的主体。它们通常旨在为开发人员提供有关更改内容以及更改原因的详细信息。除非有人知道他们在寻找什么，否则这可能是信息过载。

如果用户不知道他们在寻找什么，则信息会很快被埋在数百个提交日志中，而他们却没有修剪前面的一堆信息的工具。

#11 楼

我要说的是，将这种类型的信息添加到提交历史记录中是可以的，但是仍然需要对其进行正确记录。我们最近开始使用合流（按Atlassian）。它可搜索，您可以将某些页面设置为收藏夹等。

其他一些工具可能是evernote或Google文档中的公共笔记本。

#12 楼

在扩展Karl的答案时，我将采用一种方法，该方法在签入过程本身中会自动强制执行限制。您需要不需要开发人员采取任何积极行动的内容，例如阅读doc / wiki / README，并且不能被秘密地覆盖。在签入中执行规则的签入策略。例如，您可以定义一个策略来评估配置文件中具有挂起的签入版本的策略，如果该版本不等于x.y.z，则该策略将失败。这些规则实际上阻止开发人员执行签入，并可以提供描述性消息。这些策略可以被覆盖，但是有可能在发生这种情况时生成警报。

替代方法可以是gate-checkins失败，它将通过某种形式的单元测试直接或间接地评估SDK版本，正如Karl所提到的。

我很欣赏这个答案非常以TFS为中心，但是可能适用于您的情况的版本控制/ CI系统（如果不是TFS）也存在类似的功能。

#13 楼

与公认的答案相反，我坚持认为提交消息是有价值的（主要）信息来源。
让我们扮演释放协调员的角色。您有责任更新当前的PROD版本，从而为公司赢得或损失大量金钱。这是一种推测：我从未担任过该职位。
您检查您的Jira，Confluence，Artifactory，销售指标等。但是您还检查了最后的合并提交。您在脑海中grep，I could have broken X（是，对）