Introduces a .zf directory convention for storing all related assets (

#2)

.gitignore

@@ -0,0 +1,2 @@
+PesterTestResults.xml
+.zf/extensions/

.devops/config.ps1 → .zf/config.ps1

@@ -26,7 +26,7 @@ $zerofailedExtensions = @(
 )
 
 # Load the tasks and process
-. ZeroFailed.tasks
+. ZeroFailed.tasks -ZfPath $here/.zf
 
 # Set the required build options
 $PesterTestsDir = "$here/module"

README.md

@@ -9,20 +9,13 @@ For example, a software build script can use this module to:
     - A boilerplate entrypoint script that installs the top-level dependencies:
         - `InvokeBuild`
         - `ZeroFailed`
-    - A configuration script, by convention stored in `.devops/config.ps1`, that defines:
+    - A configuration script, by convention stored in `.zf/config.ps1`, that defines:
         - One or more `ZeroFailed` extension modules that implement functionality needed for the process (and optionally, the process itself)
         - Configuration to drive those extensions for this specific process
         - InvokeBuild task definitions for custom functionality specific to this process
 
 Examples of these files can be found [here](./examples/).
 
-## TODO: Documentation Topics:
-- Extensions
-    - How they are structured
-    - How to consume
-    - Dependency management
-- Default process
-
 ## Extensions
 
 Extensions are PowerShell modules that follow the conventions below to offer specific features to ZeroFailed processes that consume them.
@@ -43,11 +36,63 @@ For example:
 │   ├── tasksGroupB.tasks.ps1
 │   ├── bigTask.tasks.ps1           (a complex task may be defined in a dedicated code file)
 │   └── someProcess.build.ps1
-├── dependencies.psd1
+├── dependencies.psd1               (defines any other extensions this one depends on)
 ├── MyExtension.psd1
 └── MyExtension.psm1
 ```
 
-The diagram below provides an overview of how the automated process interacts with the extensibility framework & InvokeBuild when it is executed.
+### Using Extensions
+
+A ZeroFailed-based process can use extensions by referencing them via the `zerofailedExtensions` property in its `.zf/config.ps1` file.
+
+#### Simple Syntax
+
+This uses the simplest syntax to reference the latest stable versions of 2 extensions available via PowerShell Gallery.
+
+```
+$zerofailedExtensions = @(
+    "ZeroFailed.Build.DotNet"
+    "ZeroFailed.Build.Containers"
+)
+```
+
+#### Advanced Syntax
+
+This uses the richer syntax to reference specific versions of 2 public extensions and an internal extension available via a private repository.
+
+```
+$zerofailedExtensions = @(
+    @{
+        Name = "ZeroFailed.Build.DotNet"
+        Version = "1.5.0"
+    }
+    @{
+        Name = "ZeroFailed.Build.Containers"
+        Version = "1.3.0"
+    }
+    @{
+        Name = "MyCustomExtension"
+        Repository = "MyPrivatePSRepository"
+    }
+)
+```
+
+#### Syntax for local development testing
+
+This shows how to reference an extension available via a local file path, which can be useful when testing or debugging your own extensions.
+
+```
+$zerofailedExtensions = @(
+    @{
+        Name = "MyCustomExtension"
+        Path = "~/MyCustomExtension/module/MyCustomExtension.psd1"
+    }
+)
+```
+
+
+## ZeroFailed Process Overview
+
+The diagram below provides an overview of how a ZeroFailed-based process interacts with the extensibility framework when it is executed.
 
 ![Extensibility Overview](./docs/assets/extensibility.png)

build.ps1

@@ -52,4 +52,4 @@ if ($MyInvocation.ScriptName -notlike '*Invoke-Build.ps1') {
 Import-Module "$here/module/ZeroFailed.psd1" -Force
 
 # Load the build configuration
-. $here/.devops/config.ps1
+. $here/.zf/config.ps1