Add preliminary artifacts for Gatsby

README.md

@@ -21,6 +21,7 @@ Here at DataMade, we do a lot of computer programming. In the spirit of [better
 - [The shell and Ubuntu](/shell/)
     - [tmux, best practices](/shell/tmux-best-practices.md)
     - [How to move a gpg key between servers](/shell/moving-keys-between-servers.md)
+- [GatsbyJS](/gatsby/)
 - [Amazon Web Services](/aws/)
     - [AWS Relational Database Service (RDS)](/aws/rds.md)
 

gatsby/README.md

@@ -0,0 +1,39 @@
+# GatsbyJS
+
+This directory records best practices for working with [GatsbyJS](https://github.com/datamade/tutorials/projects/1), a static site generator built on top of React and GraphQL.
+
+## Contents
+
+- README
+    - [When to use Gatsby](#when-to-use-gatsby)
+    - [How to use Gatsby](#how-to-use-gatsby)
+    - [Resources for learning](#resources-for-learning)
+- [Research](./research/)
+    - [Comparisons with existing tools](./research/comparisons-with-existing-tools.md)
+        - [Gatsby vs. Jekyll](./research/comparisons-with-existing-tools.md#gatsby-vs-jekyll)
+        - [Gatsby vs. Django](./research/comparisons-with-existing-tools.md#gatsby-vs-django)
+    - [Recommendation of adoption](./research/recommendation-of-adoption.md)
+
+## When to use Gatsby
+
+Gatsby is an excellent choice for two types of projects:
+
+1. Static sites (that is, sites that can be deployed with pure HTML/CSS/JavaScript)
+2. Small dynamic sites with a limited range of simple server-side functions **not** including faceted search, user administration, or admin interfaces
+
+For more details on the specific pros and cons of Gatsby, see the [comparisons with existing tools](./research/comparisons-with-existing-tools.md) produced during R&D.
+
+## How to use Gatsby
+
+To start a Gatsby project, [create a new repository from our Static App Template](https://github.com/datamade/static-app-template/generate). Once you're ready to publish the site, follow our guide to [deploy a static site](https://github.com/datamade/deploy-a-site/blob/master/Deploy-a-static-site.md).
+
+For an example of a DataMade app deployed with Gatsby, see [LISC CNDA](https://github.com/datamade/lisc-cnda).
+
+## Resources for learning
+
+The following is a list of good resources for learning how to use Gatsby.
+
+- [The Gatsby.js tutorial](https://www.gatsbyjs.org/tutorial/) - Gatsby's official tutorial. A full walkthrough of building a simple blog from scratch in Gatsby, including quick sidebars on the basics of React, JSX, and GraphQL.
+- [The React docs](https://reactjs.org/docs/hello-world.html) - A step-by-step guide through the basics of React. Useful for getting your bearings in JSX, components, and React state management, which are important prerequisites for Gatsby.
+- [The Fullstack Tutorial for GraphQL](https://www.howtographql.com/) - Gatsby's recommended tutorial for learning GraphQL. We recommend reading the "GraphQL fundamentals" section.
+- [@jeancochrane's lunch&learn on Gatsby](https://gist.github.com/jeancochrane/705dda18da74fafe4b8182d15284114d) - A set of brief notes giving a quick overview of Gatsby's features.

gatsby/research/comparisons-with-existing-tools.md

@@ -0,0 +1,52 @@
+# Comparing Gatsby with existing tools
+
+How does Gatsby compare to other tools in the DataMade toolkit?
+
+### Gatsby vs. Jekyll
+
+Gatsby's most obvious competitor is [Jekyll](https://jekyllrb.com/), a static site generator built in Ruby. We've used Jekyll for a number of static sites in the past, including [the DataMade website](https://github.com/datamade/datamade.us), [dedupe.io](https://github.com/dedupeio/dedupe.io), and [CUAMP](https://github.com/datamade/CUAMP-live).
+
+Gatsby and Jekyll can both be deployed on Netlify as purely static sites, which makes them attractive candidates for sites that require no dynamic backend functionality like faceted search, persistent data storage, user management, or admin interfaces.
+
+In general, you should prefer Gatsby to Jekyll when:
+
+- You have a team that has working knowledge of ES6, NPM, React, and GraphQL
+- You would like to load and display data from data sources other than Markdown
+
+#### Pros
+
+- Gatsby is built on top of JavaScript, a language that we use much more regularly than Ruby.
+- Gatsby supports data loading from a huge variety of data sources via its extensible data layer API. Jekyll can only read data from Markdown posts, or from specially-formatted YAML, JSON, or CSV files living in the `_data` folder.
+- Gatsby uses React under the hood and exposes a fully-configured React development environment, meaning you can make use of JSX and the React plugin ecosystem. Jekyll requires you to use the [Liquid templating language](https://jekyllrb.com/docs/liquid/), which does not integrate as closely with JavaScript as JSX.
+- Gatsby builds in a lot of performance optimizations, including code splitting, progressive rendering, and resized images for different devices. (For a deep dive on Gatsby's performance optimizations, see [Why is Gatsby so fast?](https://www.gatsbyjs.org/blog/2017-09-13-why-is-gatsby-so-fast/))
+- Gatsby bakes in a modern JavaScript development environment by default, including hot reloading, source maps, and JavaScript package management.
+
+#### Cons
+
+- By nature of offering more flexible data management and a modern JavaScript environment, a Gatsby project is typically more complicated to set up than a Jekyll project.
+- Gatsby requires working knowledge of ES6, NPM, React, GraphQL. While these tools are very powerful and fun to use once you understand them, they may be overwhelming at first for devs who are learning them all at once.
+- Since it is built on top of React, Gatsby does not play well with JQuery. This has the disadvantage of making it incompatible with many of the JQuery libraries DataMade uses regularly, and it means you'll often need to use a React plugin to get older JavaScript libraries to work (e.g. [react-leaflet](https://react-leaflet.js.org/) in addition to vanilla [Leaflet](https://leafletjs.com/)).
+
+### Gatbsy vs. Django
+
+At first glance, Gatsby and Django may appear to be very different tools -- Gatsby is a static site generator, while Django is a full-featured MVC web framework -- but in practice, Gatsby can be a good choice for many simple apps that we would otherwise build in Django.
+
+In particular, Gatsby's flexible data layer means that it can [generate pages programmatically from data](https://www.gatsbyjs.org/tutorial/part-seven/). This means that Gatsby can easily generate list and detail views based on a CSV or Postgres database. And since Gatsby can be deployed as a static site on Netlify, you can save a lot of time that you would otherwise spend provisioning staging and production environments, and serve up fast prebuilt assets to boot.
+
+In general, you should prefer Gatsby to Django when:
+
+- You have a team that has working knowledge of ES6, NPM, React, and GraphQL
+- Your app doesn't require any dynamic backend behavior like faceted search, persistent data storage, user management, or admin interfaces
+- Your primary motivation for considering Django over static HTML/CSS/JS is the ability to generate views based on data
+
+#### Pros
+
+- By treating JavaScript as a first-class citizen, Gatsby and React make the process of building frontend interactions much more intuitive (and much more testable) than Django does.
+- Deploying on Netlify reduces the overhead of Continuous Deployment and server provisioning/management.
+- In addition to Gatsby's [built-in performance optimizations](https://www.gatsbyjs.org/blog/2017-09-13-why-is-gatsby-so-fast/), the fact that you're deploying static assets instead of rendering responses on a server means that a Gatsby app by default will load pages much faster than a Django app.
+
+#### Cons
+
+- So far, we don't have a good way of doing faceted search in a Gatsby app. [David Eads has done it](https://www.propublica.org/nerds/the-ticket-trap-news-app-front-to-back-david-eads-propublica-illinois) but we still need to prove it out in our stack.
+- Gatsby lacks a simple solution for user management and admin views. [We're tracking the progress of Netlify Identity](https://jeancochrane.com/blog/netlify-identity-dealbreakers), but it's not production-ready yet.
+- Gatsby requires working knowledge of ES6, NPM, React, and GraphQL. As of May 2019, these technologies are less well-known on our team than Python and Django.

gatsby/research/recommendation-of-adoption.md

@@ -0,0 +1,55 @@
+# Recommendation of adoption: GatsbyJS
+
+Based on our research, we recommend adopting Gatsby as our framework of choice for the following types of projects:
+
+1. Static sites (that is, sites that can be deployed with pure HTML/CSS/JavaScript)
+2. Small dynamic sites with a limited range of simple server-side functions **not** including faceted search, user administration, or admin interfaces
+
+The following document records our recommended path forward for adopting Gatsby.
+
+## Proof of concept and pilot
+
+As a proof of concept, we tested Gatsby by refactoring the CPS SSCE project to make use of it. You can view that spike on the [`feature/jfc/test-drive-gatsbyjs` branch](https://github.com/datamade/cps-ssce-dashboard/tree/jfc/test-drive-gatsbyjs).
+
+Following the proof of concept, Gatsby was piloted on the LISC CNDA project, both for the [awardee map](https://github.com/datamade/lisc-cnda-map) and the [application submission app](https://github.com/datamade/lisc-cnda). Those two repos provide good examples of real-world Gatsby projects.
+
+## Prerequisite skills
+
+The biggest obstacle to incorporating Gatsby into our standard stack is a lack of prerequisite skills among developers. Specifically, Gatsby requires that new developers be comfortable with:
+
+- GraphQL
+- ES6 (modern JavaScript)
+- React
+
+Lack of familiarity with GraphQL is not a pressing challenge, since Gatsby makes only very limited use of GraphQL. Based on our pilot project, we recommend allocating 2 hours for a developer to follow [The Fullstack Tutorial for GraphQL](https://www.howtographql.com/) when working on their first Gatsby project.
+
+Lack of familiarity with ES6 and React is a more important challenge, since both tools are used extensively in Gatsby and neither tool integrates easily with our current stack. Based on our experience in the pilot project, it's particularly important that we invest time in learning ES6 separate from Gatsby projects, since ES6 is important for understanding the Gatsby and React documentation.
+
+In sum, we make the following recommendations for developing prerequisite skills among our staff:
+
+1. Adopt ES6 as our new standard for JavaScript, and invest R&D time in creating a templated build environment for using it with Django projects
+2. Set aside ~2 hours per new dev for Gatsby projects for them to do the GraphQL tutorial
+3. Do one (or both) of two things to encourage React learning:
+    - Set aside ~4 hours per new dev for Gatsby projects for them to do the React and Gatsby tutorials
+    - Try to lead some sort of company-wide Gatsby/React learning group, where we would all do the tutorial and come together to share challenges and lessons
+
+## Maintenance outlook
+
+From a maintenance perspective, there are two primary risks to recommending wide adoption of Gatsby:
+
+1. The risk that Gatsby falls out of vogue, or stops being actively developed
+2. The risk that our team will not have the expertise to maintain Gatsby in the future
+
+We consider each of these risks in turn.
+
+### 1. Will Gatsby stop being actively developed?
+
+We believe it's unlikely that the Gatsby project will be abandoned within the next five years. It's hard to judge what the future will hold for new tools, especially in the JavaScript ecosystem, but Gatsby strikes us as a project that will be stable for the long-term future, given the [long list of well-funded users who have built their sites in Gatsby](https://www.gatsbyjs.org/showcase/) as well as the project's [80,000 dependent packages and 2,100 contributors on GitHub](https://github.com/gatsbyjs/gatsby).
+
+In addition, React and GraphQL are very stable tools, particularly given the substantial support they receive from Facebook. Since Gatsby relies heavily on React and GraphQL, we can be sure that, even in a future where Gatsby becomes less well-supported, the foundation of React and GraphQL will continue to be a good investment for our team.
+
+### 2. Will our team be able to support Gatsby in the long-term?
+
+To us, this is a more concerning maintenance question than 1) above. Gatsby requires expertise in supporting tools that are not yet widely used at DataMade, particularly ES6 and React, and if for some reason we were to lose our employees with ES6/React expertise before we have the chance to build it up team-wide, it might be hard for the team to maintain existing projects.
+
+Rather than discourage us from pushing forward with new tools, this maintenance risk indicates to us that we should invest in building capacity on our team in Gatsby's prerequisite tools as soon as possible. This determination is reflected the recommended next steps we outline in the [Prerequisite skills](#prerequisite-skills) section above.