Merge pull request #49906 from Expensify/new_help_branch

Added README.md, and unified deployment to both Preview and Production CF environments.

.github/workflows/deployNewHelp.yml

@@ -1,15 +1,17 @@
 name: Deploy New Help Site
 
 on:
-  # Run on any push to main that has changes to the help directory
-# TEST: Verify Cloudflare picks this up even if not run when merged to main
-#  push:
-#    branches:
-#      - main
-#    paths:
-#      - 'help/**'
+  # Run on any push to main that has changes to the help directory.  This will cause this
+  # to deploy the latest code to newhelp.expensify.com
+  push:
+    branches:
+      - main
+    paths:
+      - 'help/**'
 
-  # Run on any pull request (except PRs against staging or production) that has changes to the help directory
+  # Run on any pull request (except PRs against staging or production) that has
+  # changes to the help directory.  This will cause it to deploy this unmerged branch to
+  # a Cloudflare "preview" environment
   pull_request:
     types: [opened, synchronize]
     branches-ignore: [staging, production]
@@ -27,10 +29,17 @@ concurrency:
 jobs:
   build:
     env:
+      # Open source contributors do not have write access to the Expensify/App repo,
+      # so must submit PRs from forks.  This variable detects if the PR is coming
+      # from a fork, and thus is from an outside contributor.
       IS_PR_FROM_FORK: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork }}
+
+    # Set up a clean Ubuntu build environment
     runs-on: ubuntu-latest
 
     steps:
+      # We start by checking out the entire repo into a clean build environment within
+      # the Github Action
       - name: Checkout code
         uses: actions/checkout@v4
 
@@ -41,34 +50,41 @@ jobs:
           bundler-cache: true
           working-directory: ./help
 
+      # Manually run Jekyll, bypassing Github Pages
       - name: Build Jekyll site
         run: bundle exec jekyll build --source ./ --destination ./_site
         working-directory: ./help  # Ensure Jekyll is building the site in /help
 
+      # This will copy the contents of /help/_site to Cloudflare.  The pages-action will
+      # evaluate the current branch to determine into which CF environment to deploy:
+      # - If you are on 'main', it will deploy to 'production' in Cloudflare
+      # - Otherwise it will deploy to a 'preview' environment made for this branch
       - name: Deploy to Cloudflare Pages
         uses: cloudflare/pages-action@v1
-        id: deploy
-        if: env.IS_PR_FROM_FORK != 'true'
+        id: cloudflarePagesAction
+        if: ${{ env.IS_PR_FROM_FORK != 'true' }}
         with:
           apiToken: ${{ secrets.CLOUDFLARE_PAGES_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           projectName: newhelp
           directory: ./help/_site  # Deploy the built site
 
+      # After deploying to Cloudflare, share wherever it deployed to in the PR comment.
+      - name: Leave a comment on the PR
+        uses: actions-cool/[email protected]
+        if: ${{ env.IS_PR_FROM_FORK != 'true' }}
+        with:
+          token: ${{ github.token }}
+          body: ${{ format('Your New Help changes have been deployed to {0} :zap:️', steps.cloudflarePagesAction.outputs.alias) }}
+
+      # Use the Cloudflare CLI...
       - name: Setup Cloudflare CLI
-        if: env.IS_PR_FROM_FORK != 'true'
+        if: ${{ env.IS_PR_FROM_FORK != 'true' }}
         run: pip3 install cloudflare==2.19.0
 
+      # ... to purge the cache, such that all users will see the latest content.
       - name: Purge Cloudflare cache
-        if: env.IS_PR_FROM_FORK != 'true'
+        if: ${{ env.IS_PR_FROM_FORK != 'true' }}
         run: /home/runner/.local/bin/cli4 --verbose --delete hosts=["newhelp.expensify.com"] /zones/:9ee042e6cfc7fd45e74aa7d2f78d617b/purge_cache
         env:
           CF_API_KEY: ${{ secrets.CLOUDFLARE_TOKEN }}
-
-      - name: Leave a comment on the PR
-        uses: actions-cool/[email protected]
-        if: ${{ github.event_name == 'pull_request' && env.IS_PR_FROM_FORK != 'true' }}
-        with:
-          token: ${{ github.token }}
-          body: ${{ format('A preview of your New Help changes have been deployed to {0} :zap:️', steps.deploy.outputs.alias) }}
-

help/README.md

@@ -0,0 +1,48 @@
+# Welcome to New Help!
+Here are some instructions on how to get started with New Help...
+
+## How to contribute
+Expensify is an open source app, with its public Github repo hosted at https://github.com/Expensify/App.  The newhelp.expensify.com website is a part of that same open source project.  You can contribute to this helpsite in one of two ways:
+
+### The hard way: local dev environment
+If you are a developer comfortable working on the command line, you can edit these files as follows:
+
+1. Fork https://github.com/Expensify/App repo
+  * `...tbd...`
+2. Install Homebrew: https://brew.sh/
+3. Install `rbenv` using brew:
+  * `brew install rbenv`
+4. Install ruby v3.3.4 using
+  * `rbenv install 3.3.4`
+5. Set the your default ruby version using 
+  * `rbenv global 3.3.4`
+6. Install Jekyll and bundler gem 
+  * `cd help`
+  * `gem install jekyll bundler`
+7. Create a branch for your changes
+8. Make your changes
+9. Locally build and test your changes:
+  * `bundle exec jekyll build`
+10. Push your changes
+
+### The easy way: edit on Github
+If you don't want to set up your own local dev environment, feel free to just edit the help materials directly from Github:
+
+1. ... give instructions here ...
+
+## How to add a page
+The current design of NewHelp.expensify.com is only to have a very small handful pages (one for each "product"), each of which is a markdown file stored in `/help` using the `product` template (defined in `/help/_layouts/product.html`).  Accordingly, it's very unlikely you'll be adding a new page.
+
+The goal is to use a system named Jekyll to do the heavy lifting of not just converting that Markdown into HTML, but also allowing for deep linking of the headers, auto-linking mentions of those titles elsewhere, and a ton more.  So, just write a basic Markdown file, and it should handle the rest.
+
+## How to preview the site online
+Every PR pushed by an authorized Expensify employee or representative will automatically trigger a "build" of the site using a Github Action.  This will [follow these steps](../.github/workflows/deployNewHelp.yml) to:
+1. Start a new Ubuntu server
+2. Check out the repo
+3. Install Ruby and Jekyll
+4. Build the entire site using Jekyll
+5. Create a "preview" of the newly built site in Cloudflare
+6. Record a link to that preview in the PR.
+
+## How to deploy the site for real
+Whenever a PR that touches the `/help` directory is merged, it will re-run the build just like before.  However, it will detect that this build is being run from the `main` branch, and thus push the changes to the `production` Cloudflare environment -- meaning, it will replace the contents hosted at https://newhelp.expensify.com

help/_config.yml

@@ -5,3 +5,6 @@ url: https://newhelp.expensify.com
 twitter_username: expensify
 github_username:  expensify
 
+# Ignore what's only used for the Github repo
+exclude:
+  - README.md