Add some documentation

.env

@@ -1,63 +1,23 @@
 
-# TODO: organize
-# TODO: probably change to .env.development so these are
-#   never accidentally loaded in production.
-
-# We must also define these variables in other places:
-# * Add build time and runtime environment variable values to the
-#   ZEIT dashboard. As of 4/14/2020, this is is a beta feature:
-#   https://github.com/zeit/now/issues/2613#issuecomment-611274567
-#   https://zeit.co/_flags
-# * For variables we need accessible at build time, add the variable to 
-#   next.config.js
-# * Add production and preview env variables to .env.info as a
-#   convenience to keep the info in source control. "Preview" is
-#   what ZEIT Now calls its staging deployments.
-
-# For secret values:
-# 1. If needed in local development, add the variable to .env.local,
-#    outside of source control.
-# 2. To use it in deployment, add the secret to Now with the command
-#    `now secret add <secret-name> <secret-value>`. See:
-#    https://zeit.co/docs/v2/build-step/#adding-secrets
-#    Note the different syntax required for storing private keys:
-#    https://github.com/zeit/now/issues/749#issuecomment-533873759
-
-NEXT_PUBLIC_ADS_ENABLED=true
-NEXT_PUBLIC_ADS_USE_MOCK_ADS=false
-
-# CODECOV_TOKEN=a-codecov-secret # secret
-
-NEXT_PUBLIC_DEVELOPMENT_SHOW_DEMO_PAGES=true
-NEXT_PUBLIC_DEVELOPMENT_SHOW_MOCK_ACHIEVEMENTS=true
-
-NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=dev-tab-for-a-cause.firebaseapp.com
-NEXT_PUBLIC_FIREBASE_CLIENT_EMAIL=next-js-firebase-admin-sdk@dev-tab-for-a-cause.iam.gserviceaccount.com
-NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://dev-tab-for-a-cause.firebaseio.com
-NEXT_PUBLIC_FIREBASE_PROJECT_ID=dev-tab-for-a-cause
-NEXT_PUBLIC_FIREBASE_PUBLIC_API_KEY=AIzaSyDrGghKLnfOwwaSnPM0unRDXz_4YdorKU4
-# FIREBASE_PRIVATE_KEY=some-key-here # secret
-
-NEXT_PUBLIC_RELAY_ENDPOINT=http://localhost:8080/graphql/
-
-# SENTRY_AUTH_TOKEN=faketoken # secret
-NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/5258438
-SENTRY_ORG=gladly-inc
-SENTRY_PROJECT=tab-v4
-SENTRY_UPLOAD_SOURCE_MAPS_ON_BUILD=false
-
-NEXT_PUBLIC_SERVICE_WORKER_ENABLED=false
-
-SESSION_COOKIE_SECURE_SAME_SITE_NONE=false
-
-# Set these privately.
-# SESSION_SECRET_CURRENT=some-secret
-# SESSION_SECRET_PREVIOUS=a-previous-secret
-
-# Note that the base path is also hardcoded in vercel.json and
-# next.config.js.
-NEXT_PUBLIC_URLS_BASE_PATH=/newtab
-NEXT_PUBLIC_URLS_USE_TRAILING_SLASH=true
-# To allow calls to this API from the legacy app
-NEXT_PUBLIC_URLS_API_BASE_PATH=/v4
-
+# Don't put environment variables here, as they might
+# accidentally be used on production. We'll rely on the
+# Vercel dashboard to set preview/production environment
+# variables.
+
+# To add a new environment variable:
+#  1. Set the variable value to use in local development.
+#      * If it is not a secret, set the variable in
+#        .env.development.
+#      * If it should be exposed to the browser, prefix its
+#        name with "NEXT_PUBLIC_".
+#      * If it is secret, set the value in .env.local.info,
+#        which individual developers should copy into their
+#        own .env.local (outside of source control).
+#  2. Add the variable to the Vercel dashboard.
+#      * Set values for both "Preview" and "Production"
+#        environments.
+#      * From the command line: `vercel env add SOME_VAR`
+#  3. Add the Preview and Production environment variable
+#     values to .env.preview.info and .env.production.info,
+#     respectively. This serves to keep a history of changes
+#     in source control.

.env.development

@@ -0,0 +1,63 @@
+
+# TODO: organize
+# TODO: probably change to .env.development so these are
+#   never accidentally loaded in production.
+
+# We must also define these variables in other places:
+# * Add build time and runtime environment variable values to the
+#   ZEIT dashboard. As of 4/14/2020, this is is a beta feature:
+#   https://github.com/zeit/now/issues/2613#issuecomment-611274567
+#   https://zeit.co/_flags
+# * For variables we need accessible at build time, add the variable to 
+#   next.config.js
+# * Add production and preview env variables to .env.info as a
+#   convenience to keep the info in source control. "Preview" is
+#   what ZEIT Now calls its staging deployments.
+
+# For secret values:
+# 1. If needed in local development, add the variable to .env.local,
+#    outside of source control.
+# 2. To use it in deployment, add the secret to Now with the command
+#    `now secret add <secret-name> <secret-value>`. See:
+#    https://zeit.co/docs/v2/build-step/#adding-secrets
+#    Note the different syntax required for storing private keys:
+#    https://github.com/zeit/now/issues/749#issuecomment-533873759
+
+NEXT_PUBLIC_ADS_ENABLED=true
+NEXT_PUBLIC_ADS_USE_MOCK_ADS=false
+
+# CODECOV_TOKEN=a-codecov-secret # secret
+
+NEXT_PUBLIC_DEVELOPMENT_SHOW_DEMO_PAGES=true
+NEXT_PUBLIC_DEVELOPMENT_SHOW_MOCK_ACHIEVEMENTS=true
+
+NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=dev-tab-for-a-cause.firebaseapp.com
+NEXT_PUBLIC_FIREBASE_CLIENT_EMAIL=next-js-firebase-admin-sdk@dev-tab-for-a-cause.iam.gserviceaccount.com
+NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://dev-tab-for-a-cause.firebaseio.com
+NEXT_PUBLIC_FIREBASE_PROJECT_ID=dev-tab-for-a-cause
+NEXT_PUBLIC_FIREBASE_PUBLIC_API_KEY=AIzaSyDrGghKLnfOwwaSnPM0unRDXz_4YdorKU4
+# FIREBASE_PRIVATE_KEY=some-key-here # secret
+
+NEXT_PUBLIC_RELAY_ENDPOINT=http://localhost:8080/graphql/
+
+# SENTRY_AUTH_TOKEN=faketoken # secret
+NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/5258438
+SENTRY_ORG=gladly-inc
+SENTRY_PROJECT=tab-v4
+SENTRY_UPLOAD_SOURCE_MAPS_ON_BUILD=false
+
+NEXT_PUBLIC_SERVICE_WORKER_ENABLED=false
+
+SESSION_COOKIE_SECURE_SAME_SITE_NONE=false
+
+# Set these privately.
+# SESSION_SECRET_CURRENT=some-secret
+# SESSION_SECRET_PREVIOUS=a-previous-secret
+
+# Note that the base path is also hardcoded in vercel.json and
+# next.config.js.
+NEXT_PUBLIC_URLS_BASE_PATH=/newtab
+NEXT_PUBLIC_URLS_USE_TRAILING_SLASH=true
+# To allow calls to this API from the legacy app
+NEXT_PUBLIC_URLS_API_BASE_PATH=/v4
+

.env.local.info

@@ -0,0 +1,2 @@
+
+# TODO