diff --git a/common/Makefile b/common/Makefile new file mode 100644 index 00000000..6f85e68e --- /dev/null +++ b/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 + diff --git a/common/bin/alternative_track b/common/bin/alternative_track new file mode 100755 index 00000000..c7ce9655 --- /dev/null +++ b/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 " + 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 diff --git a/common/bin/check-make-prereqs b/common/bin/check-make-prereqs new file mode 100755 index 00000000..26764cf0 --- /dev/null +++ b/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 diff --git a/common/bin/clean_id_and_checksums b/common/bin/clean_id_and_checksums new file mode 100755 index 00000000..f89cc692 --- /dev/null +++ b/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 diff --git a/common/bin/mk_help b/common/bin/mk_help new file mode 100755 index 00000000..82491547 --- /dev/null +++ b/common/bin/mk_help @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +cat < 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 diff --git a/common/mk/core.mk b/common/mk/core.mk new file mode 100644 index 00000000..14aca096 --- /dev/null +++ b/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) diff --git a/instruqt-tracks/DEVELOPMENT.md b/instruqt-tracks/DEVELOPMENT.md new file mode 100644 index 00000000..f148c31d --- /dev/null +++ b/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-` + - 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 diff --git a/instruqt-tracks/sentinel-cli-basics/Makefile b/instruqt-tracks/sentinel-cli-basics/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/sentinel-cli-basics/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/sentinel-for-terraform-v4/Makefile b/instruqt-tracks/sentinel-for-terraform-v4/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/sentinel-for-terraform-v4/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-aws-v2/Makefile b/instruqt-tracks/terraform-cloud-aws-v2/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-aws-v2/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-aws/Makefile b/instruqt-tracks/terraform-cloud-aws/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-aws/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-azure-v2/Makefile b/instruqt-tracks/terraform-cloud-azure-v2/Makefile new file mode 100644 index 00000000..c153aa0e --- /dev/null +++ b/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 + diff --git a/instruqt-tracks/terraform-cloud-azure/Makefile b/instruqt-tracks/terraform-cloud-azure/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-azure/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-bonus-lab/Makefile b/instruqt-tracks/terraform-cloud-bonus-lab/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-bonus-lab/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-gcp-v2/Makefile b/instruqt-tracks/terraform-cloud-gcp-v2/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-gcp-v2/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-cloud-gcp/Makefile b/instruqt-tracks/terraform-cloud-gcp/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-cloud-gcp/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-foundations-aws/Makefile b/instruqt-tracks/terraform-foundations-aws/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-foundations-aws/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-intro-aws/Makefile b/instruqt-tracks/terraform-intro-aws/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-intro-aws/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-intro-azure/Makefile b/instruqt-tracks/terraform-intro-azure/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-intro-azure/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-intro-gcp/Makefile b/instruqt-tracks/terraform-intro-gcp/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-intro-gcp/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-module-lab/Makefile b/instruqt-tracks/terraform-module-lab/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-module-lab/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file diff --git a/instruqt-tracks/terraform-workshop-base/Makefile b/instruqt-tracks/terraform-workshop-base/Makefile new file mode 120000 index 00000000..b0700363 --- /dev/null +++ b/instruqt-tracks/terraform-workshop-base/Makefile @@ -0,0 +1 @@ +../../common/Makefile \ No newline at end of file