VCDL-87 Add DEVELOPMENT guidance and helper scripts

common/Makefile

@@ -0,0 +1,10 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# This should be symlinked into each individual track
+# directory - not useful to run it in the 'common' directory
+
+REPO_TOP=$(shell git rev-parse --show-toplevel)
+
+include ${REPO_TOP}/common/mk/core.mk
+

common/bin/alternative_track

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# NOTE: So, `yq` likes to `prettify` output if you use its
+#       `-i` option to update a file in-place, which causes
+#       excessivly complicated diffs to review. So we use
+#       `yq` to query things out of yaml files, but edit
+#       with things like sed or awk
+
+# Our standard process for creating test or alternative versions
+# of a track:
+#
+# 1. Change title to start with "WIP $(jira ticket number) - "
+# 2. Change track slug to start with "wip-$(jira ticket number)-"
+# 3. Remove 'id:' field from 'track.yml' and all 'assignment.md' files
+# 4. Remove 'checksum:' field from 'track.yml'
+# 
+# This allows us to easily identify alternative versions of a track
+# by both the name and slug, keeps the "production" version of the track 
+# easily identifiable, and does the right thing with the 'id' and
+# 'checksum' fields so Instruqt doesn't get confused. Having things start
+# with 'WIP' or 'wip' also tends to push them later in the listing.
+#
+# You must supply a JIRA ticket number, it's our standard system for
+# recording work progress and history, so it's the best identifier for
+# the job.
+#
+# Steps 3 and 4 are handled by `clean_id_and_checksums` in the standard
+# track Makefile
+
+# Assumes being ran from make, in a track directory
+
+if [ ! -f track.yml ] || [ ! -f config.yml ]; then
+    echo "This assumes it is being ran from a Makefile in the track directory"
+    echo "You do not appear to be so"
+    exit 1
+fi
+
+# First argument is Jira ticket number
+JIRA_TICKET=$1
+JIRA_TICKET_LOWER=$(echo "${JIRA_TICKET}" | tr '[A-Z]' '[a-z'] | tr '[:blank:]' '-')
+
+if [ -z "${JIRA_TICKET}" ]; then
+    echo "Usage: $0 <jira_ticket_number>"
+    exit 1
+fi
+
+# Edit 'track.yml'
+# 1. change title to start with "WIP $(jira) - "
+# 2. change track slug to start with "wip-$(jira)-"
+
+OLD_TITLE=$(yq '.title' track.yml)
+OLD_SLUG=$(yq '.slug' track.yml)
+sed -i '' \
+    -e 's/^title: .*/title: WIP '"${JIRA_TICKET} - ${OLD_TITLE}"'/' \
+    -e 's/^slug: .*/slug: wip-'"${JIRA_TICKET_LOWER}-${OLD_SLUG}"'/' \
+    track.yml

common/bin/check-make-prereqs

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+err=0
+
+which yq >/dev/null 2>&1
+if [ $? -ne 0 ]; then
+    echo "You must install the 'yq' tool"
+    echo "See https://mikefarah.gitbook.io/yq/"
+    err=1
+fi
+
+if [ "${err}" -ne 0 ]; then
+    exit 1
+fi

common/bin/clean_id_and_checksums

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# When you upload a track to Instruqt, it 'helpfully' adds an
+# 'id:' and 'checksum:' field to your 'track.yml', and adds
+# 'id:' to all of your 'assignment.md' files, which it appears
+# to use internally to associate things. If you attempt to make
+# a test or alternate version of a track and leave these in,
+# Instruqt can get confused, ranging from complaining at you to
+# overwriting parts of the original track. But you can safely
+# delete these lines from those files, which is how we get around
+# this in general
+
+# Assumes being ran from make, in a track directory
+
+if [ ! -f track.yml ] || [ ! -f config.yml ]; then
+    echo "This assumes it is being ran from a Makefile in the track directory"
+    echo "You do not appear to be so"
+    exit 1
+fi
+
+# Remove from 'track.yml'
+sed -i '' \
+    -e '/^id: .*/d' \
+    -e '/^checksum: .*/d' \
+    track.yml
+
+# For each 'assignment.md' in a sub-directory
+# 1. delete challenge id
+
+for f in */assignment.md; do
+    sed -i '' \
+	-e '/^id: .*/d' \
+	"${f}"
+done

common/bin/mk_help

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+cat <<EOF 
+
+
+Available commands:
+
+* \`make jira=<jira-ticket-number> alternate_track\`
+
+  In the directory for a given track, do the right thing to prepare
+  the track to be a alternate version: remove track and challenge IDs,
+  and track checksum, so Instruqt doesn't get confused, and change the
+  track title and slug so it is easy to distinguish it from production
+  versions of tracks.
+
+  Running this command and then performing an \`instruqt track push\`
+  should Just Do The Right Thing(TM)
+
+
+* \`make clean_id_and_checksums\`
+
+  In the directory for a given track, remove track and challenge IDs
+  and track checksum. Useful for tidying before creating a PR to merge
+  changes back in. Automatically done by \`alternate_track\`
+
+
+EOF

common/mk/core.mk

@@ -0,0 +1,19 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# Variables which should be set on the command line
+jira := ""
+
+.PHONEY: help check_prereqs clean_id_and_checksums alternate_track
+
+help: check_prereqs
+	${REPO_TOP}/common/bin/mk_help
+
+check_prereqs:
+	${REPO_TOP}/common/bin/check-make-prereqs
+
+clean_id_and_checksums: check_prereqs
+	${REPO_TOP}/common/bin/clean_id_and_checksums
+
+alternate_track: clean_id_and_checksums
+	${REPO_TOP}/common/bin/alternative_track $(jira)

instruqt-tracks/DEVELOPMENT.md

@@ -0,0 +1,46 @@
+# How to safely test Instruqt tracks
+
+Instruqt can be a bit finicky when it comes to testing tracks, because
+it appears internally to use track and challenge IDs and embeds them
+in your `track.yml` and `assigment.md` files when you push tracks. This
+can cause a problem when trying to make a test version of the track; if
+you are not careful you can confuse Instruqt or cause it to overwrite
+the production version of a track. 
+
+What follows is our standard flow and procedure for making a test 
+version of the track.
+
+# Standard Flow
+
+1. Create a Jira ticket for your work—all work should be logged and
+   documented in a Jira ticket anyways, and we use the ticket identifier
+   to provide context when committing changes. For this document, we're
+   going to assume you have a ticket number of `IL-99999`
+1. Ensure you are on the `master` branch of this repo (the current default
+   branch) and do not have uncommited changes. Pull the latest from 
+   `origin` (e.g. `git pull origin master`)
+1. Create a branch for this work, e.g. `git checkout -b IL-99999`
+1. In the track directory, run the command
+   `make jira=IL-99999 alternate_track`
+   - This removes the `track.yml` id and checksum fields, and all
+     of the `assignment.md` id fields
+   - It also changes the track slug so it starts with 
+     `wip-il-99999-<original slug`, and the track title to start
+     with `WIL IL-99999 - <Original Title>`
+   - The end result of this is that Instruqt will treat this like
+     an entirely independent track, as well as make it easy to
+     distinguish this as a test track
+1. Do whatever work you need to do. You can safely `instruqt track push`
+   to test your track
+1. When it becomes time to merge, change the track slug and title 
+   to remove the `wip-il-99999-` and `WIP IL-99999 - ` prefixes. If there
+   are any track or challenge 'id:' fields, or any track 'checksum:' fields
+   you should remove them; `make clean_id_and_checksums` will do that for
+   you
+
+*Note* it is our convention that all commit messages start with the
+jira ticket number, e.g.:
+
+> IL-99999 Add support for HashiCups
+>
+> Update the Fizbin track to show HashiCups usage

instruqt-tracks/sentinel-cli-basics/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/sentinel-for-terraform-v4/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-aws-v2/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-aws/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-azure-v2/Makefile

@@ -0,0 +1,8 @@
+
+
+
+all: clean_assignment_md
+
+clean_assignment_md:
+	@for f in $(wildcard [0-9][0-9]-*/assignment.md); do sed -e '/^id: /d' -i '' $${f}; done
+

instruqt-tracks/terraform-cloud-azure/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-bonus-lab/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-gcp-v2/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-cloud-gcp/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-foundations-aws/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-intro-aws/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-intro-azure/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-intro-gcp/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-module-lab/Makefile

@@ -0,0 +1 @@
+../../common/Makefile

instruqt-tracks/terraform-workshop-base/Makefile

@@ -0,0 +1 @@
+../../common/Makefile