From 2d8e8181fa7ceb9ea1825c013c903563b1020dff Mon Sep 17 00:00:00 2001 From: Tim Pepper Date: Fri, 15 Jun 2018 09:40:25 -0700 Subject: [PATCH] contributors/devel: request better godep vendoring commit messages On the release team I've seen a number of issues go by this year where vendor code was updated and later implicated in issue triage and bisection, but the original commits didn't sufficiently document the change. Reverting the update then reintroduced a previously fixed issue, which was insufficiently documented in the changelog. The subsequent churn led to a lot of work by multiple people to resolve. Terse godep vendor code update commit messages seem to be the norm and we should aim higher. Signed-off-by: Tim Pepper --- contributors/devel/godep.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/contributors/devel/godep.md b/contributors/devel/godep.md index 36856aa29..4f81c85e3 100644 --- a/contributors/devel/godep.md +++ b/contributors/devel/godep.md @@ -156,6 +156,22 @@ transitively), you'll also need to update deps there: ./hack/update-staging-godeps.sh ``` +## Commit messages + +Terse messages like "Update foo.org/bar to 0.42" are problematic +for maintainability. Please include in your commit message the +detailed reason why the dependencies were modified. + +Too commonly dependency changes have a ripple effect where something +else breaks unexpectedly. The first instinct during issue triage +is to revert a change. If the change was made to fix some other +issue and that issue was not documented, then a revert simply +continues the ripple by fixing one issue and reintroducing another +which then needs refixed. This can needlessly span multiple days +as CI results bubble in and subsequent patches fix and refix and +rerefix issues. This may be avoided if the original modifications +recorded artifacts of the change rationale. + ## Sanity checking After all of this is done, `git status` should show you what files have been