Explain what our expeditor scripts are doing

Signed-off-by: Tim Smith <tsmith@chef.io>

3 files changed, 29 insertions, 6 deletions

diff --git a/.expeditor/update_dep.sh b/.expeditor/update_dep.sh
index 24c4c89830..ef2bd3e6a7 100644
--- a/.expeditor/update_dep.sh
+++ b/.expeditor/update_dep.sh
@@ -1,5 +1,14 @@
 #!/bin/bash
 
+############################################################################
+# What is this script?
+#
+# Chef uses a workflow tool called Expeditor to manage version bumps, changelogs
+# and releases. When a dependency of chef is released, expeditor is triggered
+# against this repository to run this script. It bumps our gem lock files and opens
+# a PR. That way humans can do hard work and bots can open gem bump PRs.
+############################################################################
+
 set -evx
 
 branch="expeditor/${GEM_NAME}_${VERSION}"
@@ -9,7 +18,10 @@ bundle install
 bundle exec rake dependencies:update
 
 git add .
-git commit --message "Bump $GEM_NAME to $VERSION" --message "This pull request was triggered automatically via Expeditor when $GEM_NAME $VERSION was promoted to Rubygems." --message "Obvious fix - no DCO required"
+
+# give a friendly message for the commit and make sure it's noted for any future audit of our codebase that no
+# DCO sign-off is needed for this sort of PR since it contains no intellectual property
+git commit --message "Bump $GEM_NAME to $VERSION" --message "This pull request was triggered automatically via Expeditor when $GEM_NAME $VERSION was promoted to Rubygems." --message "This change falls under the obvious fix so no Developer Certificate of Origin (DCO) is required."
 
 open_pull_request
 
diff --git a/.expeditor/update_dockerfile.sh b/.expeditor/update_dockerfile.sh
index 9ae260fcb8..3ed0ed186a 100755
--- a/.expeditor/update_dockerfile.sh
+++ b/.expeditor/update_dockerfile.sh
@@ -1,7 +1,13 @@
 #!/bin/sh
+
+############################################################################
+# What is this script?
 #
-# This file updates the default VERSION build argument in the Dockerfile to the
-# VERSION passed in to the file via environment variables.
+# Chef uses a workflow tool called Expeditor to manage version bumps, changelogs
+# and releases. When the current release of Chef is promoted to stable this script
+# is run by Expeditor to update the version in the Dockerfile to match the stable
+# release.
+############################################################################
 
 set -evx
 
diff --git a/.expeditor/update_version.sh b/.expeditor/update_version.sh
index 17ad5a16a7..222ae5cf27 100755
--- a/.expeditor/update_version.sh
+++ b/.expeditor/update_version.sh
@@ -1,8 +1,13 @@
 #!/bin/sh
+
+############################################################################
+# What is this script?
 #
-# After a PR merge, Chef Expeditor will bump the PATCH version in the VERSION file.
-# It then executes this file to update any other files/components with that new version.
-#
+# Chef uses a workflow tool called Expeditor to manage version bumps, changelogs
+# and releases. After a PR is merged in Chef Expeditor calls this script to update
+# the PATCH version in the VERSION file as well as the version.rb file in both chef
+# and chef-config. When that's done it bundle updates to pull in that new chef-config.
+############################################################################
 
 set -evx