Copy updates

README.md

@@ -1,11 +1,13 @@
 # SnipFlow Methodology
 
-> A workflow for productive engineers
+[![uses SnipFlow](https://img.shields.io/badge/snipflow-v0.0.3-brightgreen?link=https://snipflow.works&link=https://github.com/marcelkornblum/snipflow&style=flat)](https://snipflow.works)
+
+> A workflow for productive engineers and their teams
 
 Snipflow is a workflow based on GitHub Flow but with some additions, and covering more than just git. For most teams, no new tooling or purchases are required to use it.
 
 SnipFlow connects version control, issue tracking, CI and non-production environments into a cohesive way of working. It reduces admin and context switching, improves communication and transparency between team members, and scales from side hustles to business critical product teams.
 
-Browse the repo, [read the docs](./docs/readme.md), or [browse the website](https://snipflow.works) built from the docs.
+Browse the repo, [read the docs](./site/readme.md), or [browse the website](https://snipflow.works) built from the docs.
 
 Please feel free to [start a discussion](https://github.com/marcelkornblum/snipflow/discussions) if you have ideas, questions or suggestions.

samples/github-actions/README.md

@@ -0,0 +1,13 @@
+# GitHub Actions samples
+
+These scripts are written to run in GitHub Actions, available when repo hosting is with GitHub.
+
+The examples here take full advantage of the GitHub Deployments API that provides rich details and trigger buttons about the deployments taking place inside the GitHub repo UI (e.g. on the `.../deployments` page, and in each PR activity feed).
+
+The scripts in this directory are written without deployment instructions, but only with the hooks in place for you to fill in the details.
+
+These scripts should all be placed in the `/.github/workflows` directory in the root of your repo. You can manually trigger a deployment by going to the "Actions" tab in the GitHub UI, then choosing "Manually trigger deployment" on the left column, and "Run workflow" at thetop right of the list of runs. You need to select a branch and environment and the rest is automated.
+
+You may want to connect a Chat client to the manual trigger, which will usually require a third party helper, such as https://github.com/marcelkornblum/deploybot.
+
+These scripts depends on GitHub Secrets set up for GitHub Tokens, and AWS Credentials, and ENV vars being available for builds. You can see a version of these scripts in use on this site by browsing the relevant directory.

samples/github-actions/build_deploy.yml

@@ -0,0 +1,88 @@
+# Runs all project tests, build process and deployment to hosting env
+# triggered by GH Deployment event
+name: "Build & Deploy"
+
+on: deployment
+
+permissions: write-all
+
+jobs:
+  build_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Update GH Deployment status to "in progress"
+        id: create_in_progress_status
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.repos.createDeploymentStatus({
+              deployment_id: "${{ github.event.deployment.id }}",
+              environment: "${{ github.event.deployment.environment }}",
+              log_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
+              description: "starting CI/CD run",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "in_progress"
+            })
+
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Run linting, tests
+        run: |
+          # this step left to the user, can also be done in a separate workflow
+          exit
+
+      - name: Run build
+        run: |
+          # this step left to the user
+          exit
+
+      - name: Set Credentials
+        run: |
+          # if needed, this step left to the user
+          exit
+
+      - name: Create temporary PR environment
+        continue-on-error: true
+        run: |
+          # if needed, this step left to the user
+          exit
+
+      - name: Deploy
+        run: |
+          # this step left to the user
+
+          URL=# set to whatever the final deployment URL is
+          echo "ENV_URL=$URL" >> $GITHUB_ENV
+          exit
+
+      - name: Update GH Deployment status to "success"
+        id: create_success_status
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.repos.createDeploymentStatus({
+              deployment_id: "${{ github.event.deployment.id }}",
+              environment: "${{ github.event.deployment.environment }}",
+              environment_url: "${{ env.ENV_URL }}",
+              log_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "success"
+            })
+
+      - name: Update GH Deployment status to "failure"
+        id: create_failed_status
+        if: ${{ failure() }}
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.repos.createDeploymentStatus({
+              deployment_id: "${{ github.event.deployment.id }}",
+              environment: "${{ github.event.deployment.environment }}",
+              log_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "failure"
+            })

samples/github-actions/ghdeployment_manual.yml

@@ -0,0 +1,30 @@
+# Creates a GitHub "Deployment" record, which GH uses to populate the UI
+name: "Manually trigger deployment"
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: environment
+        description: "Deploy to which environment"
+        required: true
+        default: "staging"
+
+jobs:
+  create-manual-deployment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create Manual GH Deployment
+        id: create_deployment
+        uses: actions/github-script@v6
+        with:
+          github-token: "${{ secrets.GH_TOKEN }}"
+          script: |
+            github.rest.repos.createDeployment({
+              environment: "${{ github.event.inputs.environment }}",
+              auto_merge: false,
+              ref: "${{ github.ref }}",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              required_contexts: []
+            })

samples/github-actions/ghdeployment_pr.yml

@@ -0,0 +1,74 @@
+# Creates a GitHub "Deployment" record, which GH uses to populate the UI
+name: "PR actions"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - closed
+
+jobs:
+  create-pr-deployment:
+    if: ${{ github.event.pull_request.merged == false }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create GH Deployment for PR environment
+        uses: actions/github-script@v6
+        with:
+          github-token: "${{ secrets.GH_TOKEN }}"
+          script: |
+            github.rest.repos.createDeployment({
+              environment: "pr${{ github.event.number }}",
+              auto_merge: false,
+              ref: "${{ github.event.pull_request.head.ref }}",
+              description: "Auto PR deployment",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              required_contexts: []
+            })
+
+  create-preview-deployment:
+    if: ${{ github.event.pull_request.merged }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create GH Deployment for Preview environment
+        uses: actions/github-script@v6
+        with:
+          github-token: "${{ secrets.GH_TOKEN }}"
+          script: |
+            github.rest.repos.createDeployment({
+              environment: "preview",
+              auto_merge: false,
+              ref: "${{ github.event.pull_request.base.ref }}",
+              description: "Auto preview deployment",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              required_contexts: []
+            })
+
+  cleanup-pr-environment:
+    if: ${{ github.event.pull_request.merged }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set Credentials
+        run: |
+          # if needed, this step left to the user
+          exit
+
+      - name: Destroy temporary PR environment
+        run: |
+          # if needed, this step left to the user
+          exit
+
+      - name: Delete GH Environment created for PR
+        uses: actions/github-script@v6
+        with:
+          github-token: "${{ secrets.GH_TOKEN }}"
+          script: |
+            github.rest.repos.deleteAnEnvironment({
+              environment_name: "pr${{ github.event.number }}",
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            })

samples/github-actions/ghdeployment_prod.yml

@@ -0,0 +1,26 @@
+# Creates a GitHub "Deployment" record, which GH uses to populate the UI
+name: "Release actions"
+
+on:
+  release:
+    types:
+      - "published"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create GH Deployment for PROD environment
+        id: create_deployment
+        uses: actions/github-script@v6
+        with:
+          github-token: "${{ secrets.GH_TOKEN }}"
+          script: |
+            github.rest.repos.createDeployment({
+              environment: "production",
+              auto_merge: false,
+              ref: "${{ github.ref }}",
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              required_contexts: []
+            })

site/README.md

@@ -1,19 +1,30 @@
 # The SnipFlow workflow
 
-SnipFlow [builds on](./differences-from-githubflow.md) GitHub Flow to connect the dots between the tools you already use, so your team can focus on the work, not the admin.
+SnipFlow is a way of working for engineering teams, combining a great developer experience with a great experience for non-technical team members.
 
-SnipFlow uses automation and shared terminology, connecting version control, CI, issue tracking, hosting environments and even team chat into a cohesive way of working. SnipFlow reduces technical admin and developer context switching, improves communication and transparency between all team members, and scales from side hustles to business critical product teams.
+It's easy and quick to set up on new projects (and most existing ones). It reduces technical admin and deployment risk while increasing productivity, quality and transparency; it's free and easy to use, and most coders who've used it love it.
+
+Using SnipFlow will allow your team to say goodbye to:
+
+- "it works on my machine"
+- "why on earth did they commit that code?"
+- "can you put the latest version on a link for me?"
+- "how do I run a deployment?"
+
+It suits [all types of teams](./who-for.md) but is most valuable in a studio environment. It [builds on](./what-its-not.html#github-flow) GitHub Flow to connect the dots between the tools you already use, so your team can focus on the work, not the admin.
+
+SnipFlow uses automation and shared terminology; it connects version control, CI, issue tracking, hosting environments and even team chat into a cohesive way of working. It reduces technical admin and developer context switching, improves communication and transparency between all team members, and scales from side hustles to business critical product teams. You don't need to licence it or (probably) use any new tooling to use it.
 
 Tested by many teams over several years, the SnipFlow workflow results in improved developer onboarding, focus and productivity, more transparency for leads and managers, and easier rationalising about code during complex debugging. It is also completely free to adopt.
 
-Read about [how it works](./how-it-works.md), jump straight into the [Getting started](getting-started.md) section, or if you're joining a team that already uses SnipFlow skip to the [onboarding](./getting-started.md#onboarding) part.
+Read about [how it works](./how-it-works.md), jump straight into [Getting started](getting-started.md), or if you're joining a team that already uses SnipFlow, skip to the [onboarding](./onboarding.md) section. Or to see an example of SnipFlow in action, browse [the repo powering this website](https://github.com/marcelkornblum/snipflow).
 
 ## Why use SnipFlow?
 
-There are many tools to help manage aspects of coders' work, but many of them end up needing technical administration, often without warning, which breaks a developer's flow state. SnipFlow abstracts these tasks to automation systems and ChatOps, removing the onus on the individual developer.
+There are many tools to help manage aspects of coders' work, but most of them end up needing technical administration, often unexpectedly, which breaks a developer's flow state. SnipFlow abstracts these tasks to automation systems and ChatOps, removing the onus from the individual developer.
 
-Most out-of-the-box automation-based tooling is aimed at single developers and small projects; as these projects grow and the team realises that it could be improved, often the switching cost is already too high. Alternatively developers need to work in different ways depending on whether they're in the day job on a team that prioritises code integrity, or the weekend project where simple processes are the priority. SnipFlow provides a scalable workflow that suits both of these priorities, meaning less cognitive load for developers across various work, fewer process errors, and quicker onboarding for new team members.
+Most out-of-the-box automation-based tooling is aimed at single developers and small projects; as these projects grow and the team realises that it could be improved, the switching cost is often already too high. SnipFlow provides a scalable workflow that suits both of these priorities, meaning less cognitive load for developers across various work, fewer process errors, and quicker onboarding for new team members.
 
-The majority of the "just works" tooling available doesn't connect very well to an overall project workflow; for example systems like Git Flow don't connect happily to tools that allow you to "push to a specific branch to deploy to a specific environment". SnipFlow replaces the OOTB automations with custom CI scripts that are simple to understand and extend, but that support the wider workflow 100%.
+The majority of the "just works" tooling available doesn't connect very well to an overall project workflow; for example systems like GitFlow don't connect happily to tools like Vercel that allow you to "push to a specific branch to deploy to a specific environment". SnipFlow replaces the OOTB automations with custom CI scripts that are simple to understand and extend, but that support the wider workflow 100%.
 
 Teams that use SnipFlow encounter drastically fewer situations where they are asked to do boring - and often risky - tasks when they could be productive.

site/_config.yml

@@ -1,5 +1,5 @@
 title: SnipFlow
-description: A workflow for productive engineers
+description: A workflow for tech teams
 titles_from_headings:
   enabled: false
 show_downloads: false

site/_data/sitenav.yml

@@ -1,36 +1,39 @@
 toc:
   - title: Introduction
     url: /
-    subfolderitems:
-      - title: Why use SnipFlow
-        url: /#why-use-snipflow
   - title: Getting started
     url: /getting-started.html
     subfolderitems:
-      - title: Setting up
-        url: /getting-started.html#setting-up
-      - title: Onboarding
-        url: /getting-started.html#onboarding
-  - title: Benefits
-    url: /benefits.html
+      - title: Repository
+        url: /getting-started.html#repository
+      - title: Hosting
+        url: /getting-started.html#hosting
+      - title: Automation
+        url: /getting-started.html#cicd-and-automation
+      - title: ChatOps
+        url: /getting-started.html#chat-and-collaboration-software
+      - title: Process
+        url: /getting-started.html#process-and-workflow
+  - title: Onboarding
+    url: /onboarding.html
+  - title: Who it's for
+    url: /who-for.html
+  - title: What you get
+    url: /results.html
     subfolderitems:
       - title: Easy onboarding
         url: /benefits.html#easy-onboarding
       - title: Clean versioning
         url: /benefits.html#clean-versioning
       - title: Transparency
         url: /benefits.html#transparency
-      - title: Communication
-        url: /benefits.html#communication
-  - title: Principles
-    url: /principles.html
-  - title: How SnipFlow works
+  - title: How it works
     url: /how-it-works.html
     subfolderitems:
-      - title: Prerequisites
-        url: /how-it-works.html#prerequisites
       - title: Overview
         url: /how-it-works.html#overview
+      - title: Prerequisites
+        url: /how-it-works.html#prerequisites
       - title: Version control
         url: /how-it-works.html#version-control
       - title: Pull Requests
@@ -41,14 +44,25 @@ toc:
         url: /how-it-works.html#cicd
       - title: ChatOps
         url: /how-it-works.html#chatops
+  - title: What it's not
+    url: /what-its-not.html
+    subfolderitems:
+      - title: Git Flow
+        url: /what-its-not.html#git-flow
+      - title: GitHub Flow
+        url: /what-its-not.html#github-flow
+      - title: Branch based
+        url: /what-its-not.html#branch-based-deployments
+  - title: Principles
+    url: /principles.html
   - title: Resources
     url: /resources.html
-  - title: Differences from GitHub Flow
-    url: /differences-from-githubflow.html
     subfolderitems:
-      - title: Example repository
+      - title: Example repo
         url: /resources.html#example-repository
       - title: CI/CD scripts
         url: /resources.html#cicd-scripts
       - title: Deploybot
         url: /resources.html#deploybot
+      - title: Case studies
+        url: /resources.html#case-studies