Change Control

Failed changes are the largest contributor to downtown with undocumented changes causing 10x the impact of documented changes.

safe - doesn’t break anything
effective - does what it says its intend to do
follows policy - documented, has approvals & isolation procedures

Keys needed for successful change control

• Visibility
• Planning & scheduling
• Defined standards that are followed
• Continuous delivery architecture that provides: predictability, scalability, repeatability, transparency

Change Approver

This is the person that reviews all of the actual code changes & accompanying document
They are ultimately on the hook for any issues that occurring during or resulting from the change

• Evaluate it
• ID dependencies & risks
• Confirm everyone can make the change and roll it back
• Make sure it will be safe effective and follow policy

Change Planning & Execution

• Should I be doing this?
  • Know reason, risk, & intended outcome
  • Filed a “Change Request”
  • I am rested & able
  • Know the sequence of events that need to occur
• Am I qualified to do this?
  • Do I know how?
  • Do I have visibility/access to all the systems required to monitor the process
  • Is the dev environment good? Did any issues occur when the changes were made in this environment?
  • Are the requisite tech resources available for support?
• Can I control my changes?
  • Have plan for making the change
  • Documentation on verification & rollback process
  • Know the risks
  • Know potential issues
• Do I have a valid execution, rollback, and validation plan?
  • Know all contingencies
  • In contact with external teams that may need to assist (like SRE)
  • Have talked to all stakeholders
  • Done a walkthrough
  • Have written testing & validation plan
  • Ensured that any potential rollback would actually roll everything back
• Does my plan isolate the changes?
  these steps are fairly specific to the infrastructure of PayPal, but the ideas are still valid
  • push to a single node > then pool > then availability zone
  • let the change “burn-in” and validate site health prior to applying the change to additional zones
• Is everything documented and approved?
  • “Change Request” is completely filled out
    i.e.: Jira/Trello/etc. thing you’re using to document your work is completed & accurate
  • Risk level assignment is correct and has been approved by proper level:
    • low: manager
    • medium: manager + director
    • high: manager + director + senior director and/or VP of site ops
• Is it scheduled to minimize impact?
  • not between 9am - 3pm PT
  • communicate w/ partners & stakeholders about SLA around returning availability

Change Validation

• Validation testing is present, valid, & successful
• wait 15 minutes prior to running validation testing

A basic video overview providing a general walk-through of Webdriver.IO and it's implementation in Grainger's Next.js/React Starter Kit. For best viewing experience either select a better video quality or view on YouTube directly.

A small collection of sites/services/resources that I’ve found useful throughout my career in web dev. There are tools for visual/design, coding, audio/video and DevOps & routing.

Visual & Design Things

Pixlr: Photoshop for free on the internet

Pixlr is free, runs in the browser, and accomplishes 80% to 90% of the stuff that most people would ever want to do in Photoshop. It’s got layers, masking, transforms, clone stamping…literally all the things. An alternative is Photopea, which provides a lot of the same tools, but also allows you to open native file types like .psd & .ai.

Boxy SVG: Free online SVG editor

Boxy SVG is a free, easy to use, and pretty robust SVG editor. You do have to create an account to export or save anything, but it does allow you to generate alternative file types (png,jpg,etc). It also includes a really neat generator feature that allows you to create valid barcodes & QR codes, jigsaw puzzle templates, parliament charts, or printing marks.

…and if you plan on putting SVGs on the internet you need to use OMG-SVG

If you look at the code behind SVGs that are created using design tools like Photoshop or Illustrator (or even Boxy SVG), it’s kind of a mess. Meaningless metadate, repeating styles, unneccesarily specific coordinate values, and more all conspire to bloat a file to multiple times larger than it needs to be.

That’s where OMG-SVG comes in. Created by the always entertaining Jake Archibald, it takes the SVG optimizer tool SVGO, that would normally run as part of build/deploy process or toolchain and turns it into a web app with a simple user interface. It works really well and is completely open-source.

It’s worth noting that if you’re trying to include an SVGs directly in JSX, TypeScript doesn’t like you using the the style attribute apparently? OMG-SVG allows you to convert those styles to their appropriate attribute values, making them JSX safe.

Easily Make Diagrams w/ Excalidraw

Excalidraw lets you easily make “white-board” style diagrams that look great. It’s completely free, open-source, and even has a community of folks making libraries of shapes & objects that you can use as well.

Pretty Code Snippet Images w/ Carbon

Carbon lets you create great looking code snippet images for use in things like a presentation slide or blog post. It gives you a ton of syntax highlighting/color scheme options and is a way easier alternative than trying to mess with your editor and the snipping tool.

Aspect Ratio Calculator

Allows you to calculate the missing value of an image based on its original aspect ratio when resizing it. It’s incredibly rudimentary but has been something I’ve used consistently for nearly a decade.

Programmer & Coding Things

MacOS Setup Guide

This has been my go-to guide for setting up a Mac machine for development work for the past 5 years. It covers everything from basic stuff like installing Homebrew & iTerm to more involved topics like Ruby & Node version management with rvm/nvm. More than anything else it’s a good general checklist to prevent you from running into a road blocks down the road because you forgot to install something basic you needed.

The Book of Secret Knowledge

This repository is a collection of various materials and tools for developers. It contains inspiring lists, manuals, cheatsheets, blogs, hacks, one-liners, cli/web tools, and more. It’s an open-source project so new items are being added to it regularly.

Regexr

When I was first starting out, I asked one of the other developers I was working with what programing language I should learn. His response, “It doesn’t matter, just get really good at regular expression. They all do that.” Regexr lets you visualize what your expression is matching and capturing while you’re constructing it, in addition to providing a cheatsheet and common patterns.

Online JavaScript Beautifier - beautifier.io

Basically the “pretty print” button from Chrome Dev Tools attached to a text box. While this functionality is built into most IDEs, I still find myself regularly throwing in a string of minified JSON or HTML into the site.

JSHint

The linting/hinting that most of use know and love from our favorite IDEs, but in the browser. This is great for when you’re working on a project that has bad/wrong/broken eslint config file. It allows you easily toggle through different rule sets & environment assumptions.

BrowserHacks

Y’all remember conditional comments?

<!--[if IE 6]> Internet Explorer 6 <![endif]-->
<!--[if IE 7]> Internet Explorer 7 <![endif]-->
<!--[if IE 8]> Internet Explorer 8 <![endif]-->
<!--[if IE 9]> Internet Explorer 9 <![endif]-->

In “the before times” there were often instances where we would need target changes or functionality for different or older versions of browsers. This site has an exhaustive list of all those sorts of tricks. Thankfully, I haven’t needed to use this site much in recent years, although I do still run into the occasional issue around detecting and implementing something specifically for safari because Apple hates the internet.

Microsoft Virtual Machines

If you ever need to test something on a windows machine, Microsoft has made a complete array of virtual machines available for free. They run on pretty much every platform (VirtualBox, Vagrant, VMware, etc. ) and they go all the way back to IE8 running on Windows 7.

Audio/Video Things

Webcam Test

I use this daily while working from home before every meeting to make sure that things I’d rather not share aren’t inadvertently in frame of the camera.

Online Audio Editors

AudioTrimmer lets you easily trim & cut files, while TimeStrech Player lets you do interesting stuff like adjust speed/pitch/speed and create loops.

Routing & DevOps sort of things

http://xip.io/

xip.io is a magic domain name that provides wildcard DNS for any IP address. Say your LAN IP address is 10.0.0.1, using xip.io:

          10.0.0.1.xip.io   resolves to   10.0.0.1
      www.10.0.0.1.xip.io   resolves to   10.0.0.1

Why? This sort of explains some reasons why you might want to do this.

CORS Anywhere

It’s a live endpoint that allows you to proxy a request to a URL which doesn’t have CORS enabled. I’ve used it when debugging an issues on projects that relied on calls to a URL where CORS was enabled, but not necessarily for that particular environment in which I was currently working.

Endpoint - https://cors-anywhere.herokuapp.com/ Github Repo Example Application

Bundlephobia

Allows you to see the impact of including a dependency in your javascript either by looking up individual packages or by uploading and scanning your package.json file.

Some of my favorite talks, highlights, and things I found interesting from CascadiaJS 2020. Additionally, links to all of the talks can be found at the bottom of this post.

Day 1 Highlights

• Modal Windows for Everyone shared some great ideas around implementing modals that I hadn’t really thought about previously like “trapping focus” within the modal, hooking CSS to aria-attributes to force their usage by future maintainers, and wiring scrims in an accessible way. This was probably my favorite talk of the conference.

• I18N | L10N - The Principals for a more Accessible Web talked about internalization & localization, but my big take-away from this talk was the last 5 minutes where he went through the Intl object which gives you a bunch of internationalization utility methods like:
  .DateTimeFormat with (dateStyle,timeStyle,formatRange),
  .RelativeTimeFormat,
  .ListFormat,
  & .DisplayNames
  and Temporal which is in the process of joining the language and lets you do stuff that you historically needed to use libraries like Moment.js/Day.js.

• Understanding Accessibility as a Concept talked about accessibility broadly and shared some tools around testing accessibility that I hadn’t heard of before like WAVE Web Accessibility Evaluation Tool & the Web Accessibility VS Code Extension.

• Memory Leaks and the Havoc They Wreak gave a general overview of memory leaks in JS and how to start going about debugging them.

Day 2 Highlights

• The Zen of Git walks through what is happening under the hood when you use git and what the various commands are doing behind the scenes.

• Musical Creativity in the Browser was a really neat talk about connecting instruments to the internet using the Web Midi API

• Complex Geometry in HTML! - The talk itself was fairly in the weeds, but the demos were really really cool.
  ・3D game written entirely in vanilla JS, HTML & CSS ( play it | github )
  ・a really cool Mario Cart demo

Video time stamps for every talk

Day 1 - Video
Opening Message About Racial Justice - Claudius Mbemba
Mo’Problems, Mo’Nads - Kyle “Getify” Simpson
Modal Windows for Everyone - James Steinbach
The Past, Present, and Future of Favicons - Tiger Oakes
I18N | L10N - The Principals for a more Accessible Web - Romulo Cintra
Understanding Accessibility as a Concept - Jemima Abu
Memory Leaks and the Havoc They Wreak - Will Klein
Saving Data to the DWeb: A Primer and a Practical Perspective - Kelsey Breseman
Human Centered On-Call Practices - Najla Elmachtoub
Developing Your Community Brand - Joel Hooks
The ACID/BASE Conundrum - Sangeetha KP
The Operating System of You - Shawn Wang

Day 2 - Video
How I learned to Stop Worrying and Let the Robot Publish to NPM - Evan Tahler
The Zen of Git - Tianyu Pu
Musical Creativity in the Browser - Scott Ammon
Complex Geometry in HTML! A story of Constrained Creativity - Pantelis Kalogiros
SVG, Canvas, and WebGL: The Power, The Beauty, & The Cost - Amber Hoak
Building Better Communities with Mental Health Support - Rahat Chowdhury
You Might Not Need a Build Step - Kristofer Joseph
My Assistant Misty - April Speight
Relax, it’s IoTea Time! - Myriam E Walden-Duarte
How I Graduated from React to Vanilla JavaScript - Dan McKeon
Oh Sweet, Gif - Rachelle Rathbone
Snowpack, Webpack and the Third Age of JavaScript - Fred K Schott

"All of the sites look the same", had been a consistent refrain that the product team has heard from both the editorial staff and readers throughout the life of Kinja, and only intensified when the brands of Onion, Inc. migrated on to the platform.

With that in mind, we set about creating a new way for the different sites to be able to express their own unique and creative brand identities without having to rely on time from the product team. The ability to completely customize headers on any different category, story type, vertical (sub-site) page is available from within Kinja's internal management UI, which all site editors have access to.

Some great examples of the editorial staff taking full advantage of the project can be found on the Gizmodo sub-sites like Paleofuture, io9, & Earther; and the various sections of The A.V. Club: Film, T.V., Music, Games, & AUX.

I was singularly responsible for defining, overseeing, and implementing all the technical aspects of this product including:

• Designing an iterative and incremental development plan for the project
• Defining the API endpoint schema
• Creating robust documentation for use by staff across all parts of the business

Feel free to explore the code, or play around with it in StoryBook

So, I wrote a simple function that I’ve added to my .bashrc file to do exactly that.

Basically it is just a simple wrapper around curl that:

1. Uses curl -I to fetch the header of a user provided URL
2. Checks to make sure the header returned useful information
3. Takes that useful header information and formats it in a way that is easy to understand.

Code

function curl-size {
  if [[ -z $1 ]]; then
    printf '%s\n' "Please provide a URL"
  else
    local response=$(curl -sI "$1" | tr -d '\r' )
    local statusCode=$(echo $response | awk '/^HTTP/ {print}')
    local byteLength=$(echo $response | awk '/[cC]ontent-[lL]ength/ {print $2}')
    if [[ -z $response ]]; then
      printf '%s\n' "Please provide a valid URL"
    else
      local disposition=UNKNOWN

      if [[ $statusCode = *"200"* ]]; then
        disposition=OK
      elif [[ $statusCode = *" 30"* ]]; then
        disposition=REDIRECT
        local newLocation=$(echo $response | awk '/^[lL]ocation:/ {print $2}')
        print $statusCode
      else
        disposition=OTHER
      fi

      function _doMath {
        divisor=$1
        print "scale=3;$byteLength/$divisor" | bc -l
      }

      if [[ $disposition == REDIRECT ]]; then
        printf 'redirecting to %s\n' $newLocation
        curl-size $(echo $newLocation)
      elif [[ $disposition == OTHER ]]; then
         print $statusCode
      else
        local value=""
        local unit=""
        if [[ -z $byteLength || ($byteLength == "0") ]]; then
          unit="Please provide a valid URL"
        elif (($byteLength>1000000000));then #1*10^9
          value=$(_doMath 1000000000)
          unit="gb"
        elif (($byteLength>1000000));then #1*10^6
          value=$(_doMath 1000000)
          unit="mb"
        elif (($byteLength>1000));then
          value=$(_doMath 1000)
          unit="kb"
        else
          value="$byteLength"
          unit="bytes"
        fi
        
        printf '%s\n' "$(printf '%s\n' "$value" | grep -o '.*[1-9]') $unit"
      fi
    fi
  fi
}

In Use

Using it for it’s original purpose…

It even handles URLs that return non-200 status codes…

Useful links from this post:

• “Official Ad Code Parameters”
• All 137 values that onejs is looking for on the global scope
• Amazon’s onejs file unminified

Background & the problem at hand…

Amazon Native Shopping Ads can be controlled by setting specific values on the global scope prior to loading the onejs script which is responsible for creating the ad. You can see this when using the “Create Custom Ads” tool. If you play around with some of the advance settings, you’ll notice that providing different parameters changes how the ad looks & behaves.

One of these ads had been implemented previously and I was now tasked with getting it to look & behave a particular way. The pattern the widget used of setting certain values prior to loading seemed straight forward enough, so I set to work. First, I tried looking for documentation around what parameters could actually be set and what they do. As far as I can tell, that information doesn’t exist publicly and the info that is available is basically just forum users throwing things against the wall and seeing what sticks.

My next thought was to unminifiying the one.js that is actually responsible for constructing the ad and pulling out all of the values that it looks for.

Many of the naming conventions they use rely on a lot of acronyms and/or are generic enough that they don’t give good enough context clues as to what they actually do, but it did provide me with a list of 137 values to start to play around with. This let me start to control some fairly rudimentary thing like:

amzn_assoc_widget_padding = "12";
amzn_assoc_text_style = "font-size: 17px;font-weight: normal;";

Having been working at peak efficiency with our counterparts at Amazon up to this point while trying to implement this ad unit, I specifically asked if they had any documentation around those 137 values that they could share. Eventually we received…

The Official Parameters for Native Shopping Ads

The tables below cover all the possible ad code parameters used for Native Shopping Ads. This information was provided by an Amazon Account Manager & PM that my team was working with to implement these sorts of ads.

Grid Format

Parameters specific to the Grid format.

Strip Format

Parameters specific to the Grid format.

Closing thoughts

If you’re going provide a technical service that will explicitly generate revenue for you, perhaps it might be a good idea to provide some public facing documentation.

• all

• Setup
  • ready
  • setupError
  • remove
• Viewability
  • viewable
• Playlist
  • playlist
  • playlistItem
  • playlistComplete
• Buffer
  • bufferChange
• Playback
  • autostartNotAllowed
  • play
  • pause
  • playAttemptFailed
  • buffer
  • idle
  • complete
  • firstFrame
  • error
  • playbackRateChanged
• Seek
  • seek
  • seeked
  • time
• Volume
  • mute
  • volume
• Resize
  • fullscreen
  • resize
• Quality
  • levels
  • levelsChanged
  • visualQuality
• Audio Tracks
  • audioTracks
  • audioTracksChanged
• Captions
  • captionsList
  • captionsChanged
• Controls
  • controls
  • displayClick
• Advertising
  • adBlock
  • beforePlay
  • beforeComplete
  • adBidRequest
  • adBidResponse
  • adClick
  • adCompanions
  • adComplete
  • adSkipped
  • adError
  • adRequest
  • adStarted
  • adImpression
  • adPlay
  • adPause
  • adTime
  • adBreakStart
  • adBreakEnd
  • adManager
  • adMeta
  • adSchedule
• Metadata
  • meta
• Sharing
  • sharingPlugin.on('open')
  • sharingPlugin.on('close')
  • sharingPlugin.on('click')
• Related
  • relatedPlugin.on('open')
  • relatedPlugin.on('close')
  • relatedPlugin.on('play')

I figured my the topic is interesting enough to share my (perhaps overly verbose) answer to the world outside of a Stack Overflow question with 0 up-votes.

Check out some of the other questions I’ve asked & answered over at Stack Overflow.

TL;DR: With gratuitous code-commenting, I think dictating the structure in the styling is fine. Also, having your mixin accept arguments makes it more flexible to use, but exponentially more complex to build/maintain. Really think hard if you’re ok with that tradeoff.

The nice thing about working in any sort of environment/language that will ultimately be compiled or minified before it gets to production, is that it allows you to be incredibly verbose with your code comments. At best, they can be an incredibly helpful insights into how stuff works. At worst, they are easily ignorable and get stripped when compiling for production anyways, so there really isn’t a cost. SASS is no exception.

With that preface in mind…
I have done something similar in the past where we were using placeholder selectors as a base style for a particular family of elements that would each get extended with their own unique styles given the situation. The structure of the markup that those elements needed to use, along with how to write and an extended style was all included within that particular SASS include. It ended up looking something like:

    %full-width-story-block {
    /* Can be included with article.story-block elements which need to occupy their container's full width.
       See "Usage" section after the style definitions for notes & examples. */

      flex-basis: 100%;
      display: flex;

      & > * {
        @include make-col(6);
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-content: center;
      }
      & > div {
        padding-left: $story-block-spacing*2;
      }
      & > a { display: block; }
      @include media-breakpoint-up(md) {
        h3 { padding-top: 0; }
      }

      @include media-breakpoint-down(sm) {
        flex-wrap: wrap;

        & > div {padding-left:0;}
        & > * {
          @include make-col(12);
        }
      }

    /*  Usage :
        + Ensure that the element is rendered on the page in the following pattern:
          (note the div containing everything but the 1st anchor/image tags.
           This is generally not included when story-block elements are used in "Content Walls")

            <article id="post-4321" class="story-block">
                <a href="/link/to/post"> <img src="story-pic.jpg" /> </a>
                <div>
                  <h3> <a href="/link/to/post">Story Title</a> </h3>
                  <p>A short excerpt from the article...</p>
                  <div class="save-article">
                    <a class="save-to-pocket" href="/pocket/url"/> <svg>...</svg></a>
                    <a class="save-to-instapaper" href="/instapaper/url"/> <svg>...</svg></a>
                  </div>
                </div>
            </article>

        + Extend the styling to the element container:
              .container-needing-full-width-story-block {
                  .story-block { @extend %full-width-story-block; }
              }
    */
    }

The big thing was communicating that the info was there and being consistent in the implementation. There were a couple of different families of components that shared that sort of structure, and they each had their required markup structures and process of extension laid out in the code comments in a similar manner. This made it easy for other dev to come along and start using & extending the structures we had already spent time setting up.

Also, the fact that all of this documentation (for a lack of a better word) existed within the codebase itself means that all this knowledge would be ported around with the project files by default. So in 2 years when a fix or update needs to be applied, as long as we have the code-base, we’re not trying to track down some obscure internal knowledge-base/wiki article or the devs who originally built it.

All of that being said, I would caution you on writing something that would accept arguments. In theory it does allow for more flexibility in the structure of markup, but that flexibility comes at the cost of increased complexity in building and maintaining that mixin. I’ve seen/built things like that which had good intentions, but ultimately ended becoming very “switch case”-ey, with each usage of the mixin elsewhere in the project requiring changes to the mixin itself to handle that particular situation’s idiosyncrasies. Just something to think about…