striblab / tc-essential-guide

All the best places to go to when you are in the Twin Cities targeted for large events, such as the Super Bowl 🏈
http://startribune.com/guide
MIT License
1 stars 0 forks source link

Essential Twin Cities Guide.

All the best places to go to when you are in the Twin Cities (for the Super Bowl).

Quickstart

The default gulp develop will not get new data from Airtable, nor will it create the responsive images. So, to make these things happen specifically, use the following:

  1. New data: gulp source:data
  2. Create responsive images: gulp assets:responsive:images, gulp assets:responsive:airtable
  3. Create responsive video images: gulp assets:responsive:videos

You should only have to run these when you have updated content.

In order to publish and build everything from scratch, run the following (note that it will take some time to run all this, specifically the publishing will take some time unless you have done it before on your computer):

  1. gulp deploy --production

Development

Meta tag and "SEO" testing

See the following resources to test attributes.

Install

The following are global prerequisites and may already be installed.

  1. (on Mac) Install homebrew.
  2. Install Node.js.
    • (on Mac) brew install node
  3. Install Gulp: npm install gulp -g
  4. Set the following environment variables:
    • AIRTABLE_API_KEY: The Airtable API key used to get data from the spreadsheets.
  5. Install ffmpeg
    • With Homebrew:
      brew tap varenc/ffmpeg && \
      brew tap-pin varenc/ffmpeg && \
      brew install ffmpeg --with-libvpx --with-libvorbis --with-fdk-aac --with-opus;
      # This will install all extensions (probably not needed)
      brew install ffmpeg $(brew options ffmpeg | grep -v -e '\s' | grep -e '--with-\|--HEAD' | tr '\n' ' ');

The following should be performed for initial and each code update:

  1. Install Node dependencies: npm install

Local

To run a local web server that will auto-reload with Browsersync, watch for file changes and re-build: gulp develop

Directories and files

Content and copy

The majority of content is managed in this Airtable. Use the following command to get new data from the Airtable, saved as sources/guide-data.json:

gulp source:data

Note that the gulp develop process does not automatically download new data as it would be slow to run every time, which means you will have to manually run the above command.

Dependencies and modules

Depending on what libraries or dependencies you need to include there are a few different ways to get those into the project.

Testing

Testing is run via Jest. Fast, unit and higher level testing will happen on build. You can run these test manually with gulp js:test or npm test.

Acceptance testing (i.e. high level quality assurance) is done separately as running headless Chrome takes more than a couple seconds. You will need a new version of Chrome or Chrome Canary installed, then run js:test:acceptance.

NOTE: Acceptance test will fail until this fix is published.

TODO: Some basic automated, cross-browser testing would be very beneficial. Unfortunately things like Browserstack are very expensive, and managing our own servers to do this would be very expensive time-wise as well.

Embed testing

A manual test page is provided for looking at the piece embeded in another page.

  1. Assumes you are running the development server with gulp develop
  2. Run a local server for the test directory, such as cd tests && python -m SimpleHTTPServer or http-server ./tests/
  3. In a browser, go to http://localhost:8080/manual/embed.html.

Build

All parts are compiled into the build/ folder. The default complete build can be done with gulp or gulp build

Publish and deploy

Deployment is setup for AWS S3. Set the following environment variables; they can be set in a .env file as well. For further reading on setting up access, see Configureing the JS-SDK.

To deploy, run gulp deploy. This will build and publish to the location configured as default (see Configuration below).

To deploy to the production location, for instance, simply use that flag like: gulp deploy --production

A handy command is to use gulp publish:open to open the URL to that project.

Configuration

Publishing is configured in the config.json file. The publish property can have the following keys: default, testing, staging, and production. It is suggested to use default in place of the staging as the default gets used when no flag is specified (see below). Each key should correspond to an object with bucket, path, and url. IMPORTANT: The url should be a fully qualified URL that ends with a /. This URL will get inserted into some meta tags on the page by default. For example:

{
  "publish": {
    "default": {
      "bucket": "static.startribune.com",
      "path": "news/projects-staging/all/super-bowl-guide/",
      "url": "http://static.startribune.com/news/projects-staging/all/super-bowl-guide/"
    },
    "production": {
      "bucket": "static.startribune.com",
      "path": "news/projects/all/super-bowl-guide/",
      "url": "http://static.startribune.com/news/projects/all/super-bowl-guide/"
    }
  }
}

Using the flags --testing, --staging, or --production will switch context for any relevant publish or deploy commands. Note that if the flag is not configured, the default will be used.

Publishing token

The publishing function, uses a token that helps ensure a name collision with another project doesn't overwrite files unwittingly. The publishToken in config.json is used as an identifier. This gets deployed to S3 and then checked whenever publishing happens again. The gulp publish (run via gulp deploy) will automatically create this token if it doesn't exist.

If you see an error message that states that the tokens do not match, make sure that the location you are publishing to doesn't have a different project at it, or converse with teammates or administrators about the issue.

Styles and practices

Having a consistent style for code and similar aspects makes collaboration easier. Though there is nothing that enforces these things, intentionally so, spending some time to adhere to these styles will be beneficial in the long run.

Other good practices that are not encompassed with linters.

License

Code is licensed under the MIT license included here. Content (such as images, video, audio, copy) can only be reused with express permission by Star Tribune.

Generated

Generated by Star Tribune StribLab generator.