[couchdb] 04/05: Provide some extra comments

[ko...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kocolosk pushed a commit to branch jenkins-dynamic-matrix
in repository https://gitbox.apache.org/repos/asf/couchdb.git

commit 2b2833dfbf4ded0d0319b9339edeb33416a2f79a
Author: Adam Kocoloski <ko...@apache.org>
AuthorDate: Tue Jan 18 10:23:58 2022 -0500

    Provide some extra comments
---
 build-aux/Jenkinsfile.full | 49 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/build-aux/Jenkinsfile.full b/build-aux/Jenkinsfile.full
index e1a3917..01714d0 100644
--- a/build-aux/Jenkinsfile.full
+++ b/build-aux/Jenkinsfile.full
@@ -13,12 +13,15 @@
 // License for the specific language governing permissions and limitations under
 // the License.
 
+// Erlang version embedded in binary packages
 ERLANG_VERSION = '24.2'
 
 // Erlang version used for rebar in release process. CouchDB will not build from
 // the release tarball on Erlang versions older than this
 MINIMUM_ERLANG_VERSION = '21'
 
+// We create parallel build / test / package stages for each OS using the metadata
+// in this map. Adding a new OS should ideally only involve adding a new entry here.
 meta = [
   'centos7': [
     name: 'CentOS 7',
@@ -94,8 +97,16 @@ meta = [
 // Credit to https://stackoverflow.com/a/69222555 for this technique.
 // We can use the scripted pipeline syntax to dynamically generate stages,
 // and inject them into a map that we pass to the `parallel` step in a script.
-// It's arguably more difficult to follow than a pure declarative pipeline, but
-// the opportunity to keep things DRY seems worthwhile. -APK
+// While the scripting approach is very flexible, it's not able to use some
+// functionality specific to Declarative Pipelines, like the `agent` and `post`
+// directives, so you'll see alternatives like try-catch-finally used for flow
+// control and the nested `node` and `docker` blocks in the container stage to
+// configure the worker environment.
+
+// Returns a build stage suitable for non-containerized environments (currently
+// macOS and FreeBSD). Coincidentally we do not currently support automated
+// package generation on these platforms. This method in invoked when we create
+// `parallelStagesMap` below.
 def generateNativeStage(platform) {
   return {
     stage(platform) {
@@ -111,7 +122,7 @@ def generateNativeStage(platform) {
                 'MAKE='+meta[platform].gnu_make
                 ]) {
               sh( script: "mkdir -p ${COUCHDB_IO_LOG_DIR} ${platform}/build", label: 'Create build directories' )
-              sh "tar -xf apache-couchdb-*.tar.gz -C ${platform}/build --strip-components=1"
+              sh( script: "tar -xf apache-couchdb-*.tar.gz -C ${platform}/build --strip-components=1", label: 'Unpack release' )
               dir( "${platform}/build" ) {
                 sh "./configure --skip-deps --spidermonkey-version ${meta[platform].spidermonkey_vsn}"
                 sh '$MAKE'
@@ -148,6 +159,8 @@ def generateNativeStage(platform) {
   }
 }
 
+// Determines the label we filter on to select an appropriate worker for
+// container-based builds.
 def getNodeLabel(platform) {
   if (meta[platform].node_label) {
     return meta[platform].node_label
@@ -157,6 +170,8 @@ def getNodeLabel(platform) {
   }
 }
 
+// Returns a build stage suitable for container-based deployments. This method
+// is invoked when we create the `parallelStagesMap` in the pipeline below.
 def generateContainerStage(platform) {
   return {
     // Important: the stage name here must match the parallelStagesMap key for the
@@ -235,16 +250,9 @@ def generateContainerStage(platform) {
   }
 }
 
-// Including failFast: true in map fails the build immediately if any parallel step fails
-def parallelStagesMap = meta.collectEntries( [failFast: true] ) { key, values ->
-  if (values.image) {
-    ["${key}": generateContainerStage(key)]
-  }
-  else {
-    ["${key}": generateNativeStage(key)]
-  }
-}
-
+// Finally we have the actual Pipeline. It's mostly a Declarative Pipeline,
+// except for the 'Test and Package' stage where we use the `script` step as an
+// "escape hatch" to dynamically generate a set of parallel stages to execute.
 pipeline {
 
   // no top-level agent; agents must be declared for each stage
@@ -290,8 +298,7 @@ pipeline {
         timeout(time: 15, unit: "MINUTES")
       }
       steps {
-        sh 'ls -l'
-        sh 'rm -rf apache-couchdb-*'
+        sh (script: 'rm -rf apache-couchdb-*', label: 'Clean workspace of any previous release artifacts' )
         sh "./configure --spidermonkey-version ${spidermonkey}"
         // sh 'make erlfmt-check'
         sh 'make elixir-check-formatted'
@@ -302,6 +309,9 @@ pipeline {
           stash includes: 'apache-couchdb-*.tar.gz', name: 'tarball'
           archiveArtifacts artifacts: 'apache-couchdb-*.tar.gz', fingerprint: true
         }
+        failure {
+          sh 'ls -l ${WORKSPACE}'
+        }
         cleanup {
           // UGH see https://issues.jenkins-ci.org/browse/JENKINS-41894
           sh 'rm -rf ${WORKSPACE}/*'
@@ -312,6 +322,15 @@ pipeline {
     stage('Test and Package') {
       steps {
         script {
+          // Including failFast: true in map fails the build immediately if any parallel step fails
+          parallelStagesMap = meta.collectEntries( [failFast: true] ) { key, values ->
+            if (values.image) {
+              ["${key}": generateContainerStage(key)]
+            }
+            else {
+              ["${key}": generateNativeStage(key)]
+            }
+          }
           parallel parallelStagesMap
         }
       }