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

在有关从最新版本回滚第三方SDK的会议中，我们注意到开发人员已经在提交历史记录中标记了不应使用最新版本。

一些开发人员认为这是一种不好的做法，应该在源文件（即// Don't upgrade SDK Version x.y.z, see ticket 1234）或项目级别的README文件中进行注明。其他人则认为，由于提交历史记录是项目文档的一部分，因此对于此类信息而言，它是可接受的位置，因为无论如何我们都应该阅读它。

应该使用提交历史记录将关键信息传达给其他开发人员，还是应该将这些信息复制到其他位置（例如项目README或相关源文件中的注释）？

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

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

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

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

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

直接在您的<dependency>线上方。

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

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

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

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

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

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

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

我不会在代码中注释它，也不会将其添加到自述文件中。考虑尝试升级的开发人员不会关注这些内容。如果您确实将其添加到那里，那么当库的问题最终得到解决并完成升级时，您将需要删除它。该步骤通常被遗忘：产生的注释对项目不利。

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

我想给马修的评论在答复突出他的重要思想更多的关注。有一个您不想升级SDK的原因，并且应该在单元测试中捕获该原因。不是检查版本号，而是实际的根本原因。

例如，假设新版本中存在错误。编写一个检查该错误的单元测试。如果他们以后在SDK中修复了该错误，则升级将顺利进行。如果有不兼容的API更改，请编写测试以检查您的代码是否支持新API或SDK是否支持旧API。与单元测试相比，这更多的是集成测试，但是仍然应该可行。

我的公司每天产生50笔以上的提交，而且我们的规模还不是很大。即使每个开发人员都阅读了每条提交消息（坦率地说他们没有读），我们需要记录的提交历史的全部原因是因为人们不记得了。除非有问题，否则人们以后不回去阅读历史记录。而且，他们没有理由怀疑升级方面的问题，据他们所知尚未发生。

一定要发送电子邮件以防止近期内重复工作，并在构建脚本和自述文件或勘误表中注明该电子邮件。但是，特别是如果新版本的问题很细微且排错时间很长，则需要一种使其变得明显的方法。这意味着单元测试。

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

如果导致我进行此类发现的动作链是由故障单触发的，则我将更新故障单（并确保应该知道此故障的人员具有可见性），我可能会面对面提及（希望至少让某人感到“，“哎呀，我想达蒙说了些有关更新的东西”），我当然会在包含SDK的那一点上在代码中留下评论，以便没有人可以更新它没有机会看到它。我可能会看看是否也可以将其塞入我们的开发Wiki中的某个位置，尽管这样做的目的更多是针对未来的员工，而不是当前的团队。

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

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

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

我不确定您的团队如何沟通，但是我认为最有效的表达方式是先发送并发送电子邮件到团队的电子邮件组，该组标有“紧急”字样

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

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

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

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

源代码管理中的文件历史记录可能很长，并且每天根据开发人员的不同而有所不同，具体取决于开发人员。某个已经休假一周的人可能没有时间阅读一周的提交历史记录。自述文件是一个更好的地方，因为它更集中一些，人们可能更倾向于阅读它，但是您不能确保每个人都会真正阅读自述文件。好吧，我想如果他们看到它已被更改，他们可能会 ...

诸如此类的东西应该已经被提交到提交注释中，但是它也会因为在其他地方而受益。

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

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

• 它解决什么问题？
• 为什么选择这个特定的人？
• 到目前为止，需要考虑哪些因素：版本，升级，测试等。
• 谁做出这个决定？

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

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

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

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

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

• 不需要的SDK升级使其成为源代码，可能会对产品产生负面影响。
• 从一个问题开始：执行了不必要的升级的贡献者不知道之前是否做出了不升级的特定决定。

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

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

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

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

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

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

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

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

在扩展Karl的答案时，我将采用一种在检查过程本身中自动强制执行限制的方法。您需要不需要开发人员采取任何主动行动的内容，例如阅读doc / wiki / README，并且不能被秘密覆盖。

在TFS源代码管理域中，您可以编写在签入时执行规则的自定义签入策略。例如，您可以定义一个策略，该策略使用挂起的签入评估配置文件中的版本，如果不等于xyz，则该策略将失败。这些规则实际上阻止开发人员执行签入，并可以提供描述性消息。可以覆盖策略，但是有可能在发生这种情况时生成警报。

如Karl所提到的，可以选择门控检入失败，该检入将通过某种形式的单元测试而失败，该单元测试可以直接或间接地评估SDK版本。

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