From 571d130f508bfb88481cc1a0c0547a4a2941c23b Mon Sep 17 00:00:00 2001
From: Bryan MacFarlane <bryanmacf@gmail.com>
Date: Sat, 3 Aug 2019 12:15:05 -0400
Subject: [PATCH] Branching Strategy for Production Modules (#39)

* starting walkthrough docs
---
 docs/node12-action.md | 60 +++++++++++++++++++++++++++++--------------
 1 file changed, 41 insertions(+), 19 deletions(-)

diff --git a/docs/node12-action.md b/docs/node12-action.md
index eff3adf5..fcc47484 100644
--- a/docs/node12-action.md
+++ b/docs/node12-action.md
@@ -21,17 +21,23 @@ steps:
     using: actions/setup-node@master
 ```
 
-# Install Dependencies
+# Dev Workflow
 
-This will install the toolkit and other dependencies
+The workflow below describes one possible workflow with a branching strategy.  Others exist.  
+
+> Key Point: the branch that users reference in their workflow files should reference an action that has **only** the production dependencies. 
+
+The workflow below describes a strategy where you code in master (with node_modules ignored) with a V1 branch users reference and contains the product references.  Actions are self contained referenced on the github graph of repos.
+
+## Install Dependencies
+
+After creating a repo from the template and cloning it, you will be in master.  The command below will install the toolkit, other dependencies and dev dependencies
 
 ```bash
 $ npm install
 ```
 
-The production dependencies are vendored into your action.  At runtime, the self contained action will be downloaded, extracted and run.
-
-# Define Metadata
+## Define Metadata
 
 Your action has a name and a description.  Update the author.
 
@@ -53,7 +59,7 @@ runs:
 
 Note that the action will be run with node 12 (carried by the runner) and the entry point is specified with `main:` 
 
-# Change Code and Add Tests
+## Change Code and Add Tests
 
 The entry point is in main.ts
 
@@ -74,13 +80,13 @@ run();
 
 Modify tests in `__tests__\main.test.ts`.  The template uses [jest](https://github.com/facebook/jest).
 
-# Format the Code
+## Format the Code
 
 ```bash
 $ npm run format
 ```
 
-# Build and Test
+## Build and Test
 
 ```bash
 $ npm run build
@@ -100,31 +106,47 @@ Test Suites: 1 passed, 1 total
 ...
 ```
 
-# Commit and Push Changes
+## Commit and Push Changes
 
 ```bash
 $ git add <whatever only files you added>
 $ git commit -m "Message"
 ```
 
-**IMPORTANT**: do not git add or .gitignore node_modules.
+## Publish a V1 Action
 
-Husky will add/vendor node_modules and prune dev dependencies.  See husky in package.json for details.  There is no need for you to add node_modules.
-
-NOTE: We understand that the process of checking in node_modules is currently somewhat painful for some use cases. We are actively tracking an enhancement in [this issue](https://github.com/actions/node12-template/issues/4) to improve this process (and are open to any suggestions :smile:).
-
-In the meantime we still **strongly encourage** you to not check in dev-dependencies, it will significantly bloat the size of actions and degrade the experience.
-
-# Publish Action
-
-Simply push your action to publish.
+After changing some files, create a V1 branch which we will release 
 
 ```bash
+$ git checkout -b V1
+```
+
+> NOTE: We will provide tooling and an action to automate this soon.
+
+Checkin production dependencies:
+1. **Do not ignore node_modules**:  Add a `!` in front of the `node_modules` line.
+2. **Delete node_modules**: rm -Rf node_modules
+3. **Install production dependencies**: npm install --production
+4. **Add**: git add node_modules
+
+
+Simply commit and push your action to publish.
+
+```bash
+$ git commit -a -m "publishing V1 of action"
 $ git push
 ```
 
 > NOTE: Consider versioning your actions with tags.  See [versioning](docs/action-versioning.md)
 
+# Users Referencing
+
+Users can now reference your action in their workflows with
+
+```yaml
+steps:
+    using: {org}/{reponame}@V1
+```