Maintain a developer workflow

Search…
Keep your track building under control.
This guide explains how to maintain a developer workflow based on Git and GitHub for your track building with development-to-production testing and promotion.
Why would you maintain a developer workflow?
The benefit of a developer workflow is that you can change and test a track without disrupting production tracks. So, by maintaining a developer workflow, you ensure your content is free from errors that could cause a bad experience for learners. 
Overview
The bottom line of the developer workflow is that you maintain a development and production version of a track. In this setup, you change the development version until you are satisfied and it is error-free. And then you merge the changes into the production version, making the updated track available to your learners.
At a high level, the developer workflow looks like this:
1.You start the flow by running a script that creates a development version of your production track.
2.Next, you change the development version and push it to the Instruqt platform for testing. You repeat this change-push-test cycle until you are satisfied and the version is error-free.
3.Then you commit your changes to the development version in Git, push them to GitHub, and create a pull request in GitHub.
4.Finally, you merge the pull request in GitHub, triggering actions that promote your changes to the production track.
As mentioned, this is only a high-level overview. The following sections describe all the steps and components in the developer workflow.
Before you begin
Instruqt CLI and Git/GitHub
You need the following to maintain the developer workflow:
​Instruqt CLI on your machine.
​Git on your machine.
A GitHub account.
Bash scripts
Furthermore, you need this set of Bash script files:
build-slug-id-list.sh
Scans a directory of tracks and creates a track-slugs.yml file.
convert-to-dev-track.sh
Converts to a '-dev' version of a track.
promote-track-changes.sh 
Merges changes made in a '-dev' version of a track.
To install these script files, download and unpack the following file into a directory on your machine that is in your PATH environment variable:
dev-workflow-scripts.zip
2KB
Binary
yq
And in order to run the Bash scripts, you need to have yq installed. yq is a YAML processor for manipulating and extracting YAML data and can be installed from GitHub.
​
Bash scripts on Windows
Bash scripts are native to Linux and Mac. But you can run bash scripts on Windows as well by installing Windows Subsystem for Linux.
Maintain a developer workflow
Install and set up
First, you need to install and set up the following once:
1.Open a terminal on your machine and create a directory called instruqt-development.
2.Inside instruqt-development, create a subdirectory called instruqt-tracks.
3.Move your track directories into the instruqt-tracks subdirectory. 
4.Ensure that all your tracks in the instruqt-tracks subdirectory are up-to-date with the latest content. You might do an instruqt track pull in each track directory to make sure.
5.Download the .github directory into the instruqt-development directory:
1.Open the online Download Directory tool. 
2.In the Past GitHub.com folder URL, enter  https://github.com/instruqt/examples/tree/master/.github and hit Enter.
↳ A ZIP file with the .github directory is downloaded.
3.Extract the ZIP file into a directory called .github and move the .github directory into the instruqt-development directory.
↳ The .github directory contains actions and workflows that will run automatically when you push updates to GitHub and merge pull requests.
6.Move into the instruqt-tracks directory and generate a track-slugs.yml file by running this script:
1
build-slug-id-list.sh
Copied!
↳ The track-slugs.yml file looks something like this:
1
---
2
tracks:
3
  - { slug: myfirsttrack, id: jum7k2jboetj }
4
  - { slug: mysecondtrack, id: baekpuxv2m5g }
Copied!
​
When you add new tracks, you should manually add extra lines to this file with the slug and id of each track.
7.Open the file instruqt-development\.github\dev-track-test.yml in your code editor and enter your team slug into the ORGANIZATION-SLUG property—for example: 
1
ORGANIZATION_SLUG: thetrackcrack
Copied!
8.Open the file instruqt-development\.github\prod-track-test.yml and edit the on property to the following if needed:
1
on:
2
  push:
3
    branches:
4
      - main
Copied!
9. Head over to your team page on the Instruqt platform.
10.Click API, followed by Copy to clipboard to copy the API Key. Or generate an API key if needed and then copy it.
11.Head over to GitHub and create a new repository called InstruqtDevelopment.
12.Open the new repository and click ⚙️Settings.
13.Click Secrets > Actions, followed by New repository secret.
14.In the Name field, enter INSTRUQT_TOKEN.
15.In the Value field, paste the API Key and click Add secret.
16.Click <> Code followed by Code▾ and copy the repository URL to the clipboard. 
17.Go back to the terminal and prepare the instruqt-development directory for Git:
The following steps will activate a push of your tracks to production.
1.Move into the instruqt-development directory.
2.Enter the following Git commands one at a time:
1
git init
2
git add .
3
git commit -m "Setup" 
4
git remote add origin "REPOSITRY_URL"
5
    # ⇨ Paste the repository URL from the clipboard here
6
git push -u origin main
Copied!
↳ The push will activate your first GitHub action deployment. All of the tracks in your track-slugs.yml file will be validated, tested, and pushed to production.
From this point forward, you can manage all changes to your tracks with the Developer Workflow.
Developer workflow
Create a new branch once
Start by creating a new (development) branch once in which you do your development work:
1.Move into the instruqt-development directory if needed.
2.Enter the following Git command:
1
git checkout -b my-dev-branch
Copied!
Repeating workflow
Then you go through this workflow for every new release of your track:
1.Move into the directory of the track that you want to edit and run this script:
1
convert-to-dev-track.sh
Copied!
↳ This script will convert your production track into a development version that is safe to change and test. 
2.Push the development version to the Instruqt platform by entering this Instruqt CLI command:
1
instruqt track push --force
Copied!
↳ On the Creator Studio page on the Instruqt platform, you will see a new version of your track that has a DEV - prefix.
3.Change, push, and test the development version until it is working the way you want.
4.Go back to the terminal and prepare your development version for promotion to production by running this script:
1
promote-track-changes.sh
Copied!
5.Enter the following Git commands one at a time to push your development branch to your GitHub repository:
1
git add .
2
git commit -m "NAME_YOUR_COMMIT_WHAT_YOU_WANT" 
3
git push
Copied!
6.Head over to GitHub, open your repository and click 
 followed by New pull request to open a new pull request.
7.Click compare: main ▾ and select my-dev-branch.
8.Click Create pull request.
9.In the Leave a comment field, enter a comment and click Create pull request.
10.Watch the actions of the Development Track Test workflow run. 
↳ The workflow tests your track and shows a green checkmark when the tests are successful. 
11.Click Merge pull request followed by Confirm merge to commit the merge.
12.Click 
 and watch the Production Track Test workflow run.
↳ The workflow tests your track and promotes your changes to the production track while preserving all your Instruqt track IDs. 
Inform your learners that the new track is available. And reward yourself because you are a true Instruqt master now. For example, by playing this Instruqt based 🕹️Palace Arcade.
Monitor tracks played via a track invite
View track logs
Last modified 2mo ago
Copy link
Edit on GitHub
Contents
Why would you maintain a developer workflow?
Overview
Before you begin
Instruqt CLI and Git/GitHub
Bash scripts
Maintain a developer workflow
Install and set up
Developer workflow