What to do after migration

Spectate articles heavily depend on the structure of the page due to article hoisting. If migration changes the structure (the section#main and article stuff), the JavaScript of all past Spectate articles will likely need to be updated.

Luckily, all Spectate projects are tracked on the graphicsdesk GitHub. For each Spectate project on our GitHub, spectate clone the repository.

Navigate to the article hoisting code. On most Spectate projects, it's in the same place as documented in the API Documentation.

Now, write new article hoisting code to something that accomodates the new website. This'll take some testing, but once it's figured out, replace the old article hoisting code with the new code and spectate publish. That'll build the project and re-upload dist to the S3 bucket.

On old Spectate projects, article hoisting wasn't a thing, and we just used a bunch of CSS. Example: https://github.com/graphicsdesk/the-box. Thus, there'll be no existing article hoisting code, or even a src/scripts/page.js. You can just insert the hoisting code somewhere inside src/script.js.

BEFORE YOU DO spectate publish on old Spectate projects (i.e. before February 2020 probably), go to the S3 bucket of that project. If the script.js file is not hashed as script.75da7f30.js and the style.scss file is not hashed as styles.164d45a1.css, this means the --no-content-hash flag was not on in that version of Spectate. Without the --no-content-hash flag, the files in dist will have different names every time you spectate publish, even though the HTML of that story does not change. Thus, you'll have to rename all your dist output to the hashes that are already in the S3 bucket. First, add the --no-content-hash flag to the end of the build script in the package.json. This ensures that all the generated files in dist/ will subsequently have the same name. Next, add a postbuild script that renames every hashed file to the name that was in the S3 bucket. It would look something like this:

"postbuild": "mv dist/script.75da7f30.js dist/script.27bc1f26.js; mv dist/styles.164d45a1.css dist/styles.d5e507b6.css;"

What is S3?

The JavaScript and CSS of all Spectate articles are hosted on AWS S3, a simple static file hoster. To access these files, go to the Secret Spec Graphics Credentials doc (currently only deputies and editors have access). The credentials you want are under the Spectate AWS Access Keys heading. Go to the console login link and input the username and password. In the AWS Management Console, go to the S3 service. Go to the spectator-static-assets bucket. Each directory of the bucket represents one Spectate project (the directory name is the slug). Within the bucket is the dist build of that Spectate project.