How are episodes published?

After recording an episode and when it's time to publish, there are a few steps that need to be done manually.

Update your local copy of the site's repository

This only needs to be done once somewhere on your machine:

$ git clone https://github.com/unicorn-meta-zoo/unicorn-meta-zoo.github.io.git

That should create a local copy of the repository in a new directory called unicorn-meta-zoo.github.io. After the first time you do that, you'll want to make sure you have the latest changes before doing anything else with:

$ git pull

Write a metadata file

Each episode needs an .md file to go with the .mp3 audio. (md technically stands for MarkDown, but in this context it could easily be MetaData.) The contents of the file will be added to the MP3 file in the form of MP3 tags. As an example, consider the third episode. It starts with a YAML block:

---
episode: 3
title: How do we grade questions?
artist: hairboat, Juan M and Jon Ericson
year: 2019
recording_date: 2019-02-27
url: https://meta.stackexchange.com/questions/tagged/unicorn-meta-zoo
comment: We're talking about whether or not there is such a thing as a bad question and how we might detect one if it exists.
sponsor: Top bar
---

One tricky bit is the url. Note that it should be a link to the meta announcement. The process I'm describing in this document will allow us to put the real URL in the MP3 file.

After that, I've written up some show notes in regular Markdown. These will be put in the MP3's description, the RSS feed item description and posted to Meta Stack Exchange. Make sure you update the actual episode URL:

  [1]: https://dts.podtrac.com/redirect.mp3/unicorn-meta-zoo.github.io/episodes/question-grade.mp3

Post the episode announcement

When you are ready to publish, copy the show notes from the md file and paste them into the body of a new question. Update the title and post. Then immediately delete the question. This is so we can grab the URL and put it in the MP3 and RSS feeds.

Add the tags to the MP3 file and generate the RSS

Copy the URL of the announcement to the url value in the metadata file and make sure the episode's MP3 file is in the episodes directory. Then run the command to add the tags and create the feed:

$ bundle exec ./add_tags.ksh episodes/question-grade.md

This command requires a few things to be installed first:

• yq,
• unicornify (requires go),
• ImageMagick,
• Pandoc,
• eyeD3 (which requires Python),
• a recent Ruby (I recommend using rbenv to manage versions) and then
• run gem install bundler and bundle install.

(Sorry!)

Publish the MP3

Now you'll want to publish the episode. Start with:

$ git status

That should show the files that have been changed or added. Hopefully the MP3 file and episode image will be listed so you can push it:

$ git add episodes/question-grade.mp3 episodes/E3.jpg episodes/question-grade.md
$ git commit -m "Add another episode or other useful comment."
$ git push

Now you should be able to go back to the deleted meta post, check that the audio link works and undelete the question.

Publish the RSS

You should also have a new RSS feed. It takes a while for Apple and other podcast services to scan the feed, so it doesn't hurt to make sure the episode audio and image are staged before publishing the feed. It also gives use a chance to test it:

$ bundle exec rake

If that finishes with no errors or warnings, it's time to publish the feed. Just do the same things you did for publishing the audio above but with index.rss. You can also push other changes you might have made, such as adding the episode to README.md.

Bob's your uncle!