feat(911): Add source paths (#160)

* feat(911): Add source paths docs

* fix: Autofocus on search form

* fix: Formatting

* fix: Add sd-cmd to contributing doc

* fix: Source paths is only available for scm-github

* fix: Use new workflow

docs/_data/menu.yml

@@ -24,6 +24,8 @@
           url: "/user-guide/configuration/annotations"
         - title: "Secrets"
           url: "/user-guide/configuration/secrets"
+        - title: "Source Paths"
+          url: "/user-guide/configuration/sourcePaths"
     - title: "Metadata"
       url: "/user-guide/metadata"
     - title: "Environment Variables"
@@ -58,8 +60,6 @@
       subcategories:
         - title: "Domain Model"
           url: "/about/appendix/domain"
-        - title: "Execution Engines"
-          url: "/about/appendix/execution-engines"
     - title: "Contributing"
       url: "/about/contributing"
     - title: "Support"

docs/_layouts/main.html

@@ -90,7 +90,7 @@ <h4 class="modal-title" id="exampleModalLabel">Search</h4>
                     your search terms below.
                 </p>
                 <form role="form">
-                    <input type="search" class="form-control" id="search" placeholder="Search..." autocomplete="off">
+                    <input autofocus type="search" class="form-control" id="search" placeholder="Search..." autocomplete="off">
                 </form>
                 <div id="results" class="all-posts results"></div>
             </div>

docs/about/contributing.md

@@ -77,6 +77,7 @@ The **[screwdriver][api-repo]** repo is the core of screwdriver, providing the A
 
 The **[launcher][launcher-repo]** performs step execution and housekeeping internal to build containers. This is written in Go and mounted into build containers as a binary.
 
+* **[sd-cmd][sd-cmd-repo]**: A Go-based CLI for sharing binaries which provides a single interface for executing a versioned command (via remote binary, docker image, or habitat package) during a Screwdriver build
 * **[sd-step][sd-step-repo]**: A Shared Step allows people to use the same packages and commands in all build containers, regardless of build environment
 * **[meta-cli][meta-cli-repo]**: A Go-based CLI for reading/writing information from the metadata
 
@@ -203,6 +204,7 @@ The organization [screwdriver-cd-test][screwdriver-cd-test-org] contains various
 [scm-bitbucket-repo]: https://github.com/screwdriver-cd/scm-bitbucket
 [scm-github-repo]: https://github.com/screwdriver-cd/scm-github
 [screwdriver-cd-test-org]: https://github.com/screwdriver-cd-test
+[sd-cmd-repo]: https://github.com/screwdriver-cd/sd-cmd
 [sd-step-repo]: https://github.com/screwdriver-cd/sd-step
 [store-repo]: https://github.com/screwdriver-cd/store
 [template-main-repo]: https://github.com/screwdriver-cd/template-main

docs/user-guide/configuration/annotations.md

@@ -10,7 +10,7 @@ toc:
 # Annotations
 Annotations is a freeform key/value store, often used to configure build execution settings. Annotations may be used as a sandbox for [YAML anchors and aliases](http://blog.daemonl.com/2016/02/yaml.html).
 
-### Example
+#### Example
 ```
 shared:
     template: example/mytemplate@stable
@@ -19,6 +19,7 @@ shared:
             image: node:8
 
 jobs:
+    requires: [~pr, ~commit]
     main: *bar                  # Referencing the annotation anchor to use that config for main job
                                 # This will cause the main job to use a node:8 image
 ```

docs/user-guide/configuration/environment.md

@@ -10,7 +10,7 @@ toc:
 # Environment
 A set of key/value pairs for environment variables that need to available in a build. If an environment variable is set in both shared and a specific job, the value from the job configuration will be used.
 
-### Example
+#### Example
 ```
 shared:
     template: example/mytemplate@stable
@@ -19,7 +19,9 @@ shared:
         MYVAR: hello        # This will set MYVAR=hello in all builds
 jobs:
     main:
+        requires: [~pr, ~commit]
         environment:
             FOO: baz        # This will set FOO=baz in the build
-    main2: {}               # This will set FOO=bar in the build
+    main2:                  # This will set FOO=bar in the build
+        requires: [main]
 ```

docs/user-guide/configuration/index.md

@@ -33,6 +33,7 @@ You can access information about properties by hovering over the property name.
 <a href="#jobs"><span class="key">jobs</span>:</a>
       <span class="key">main</span>:
         <a href="#requires"><span class="key">requires</span>: <span class="value">[~pr, ~commit, ~sd@123:main]</span></a>
+        <a href="#sourcePaths"><span class="key">sourcePaths</span>: <span class="value">["src/app/", "screwdriver.yaml"]</span></a>
         <a href="#image"><span class="key">image</span>: <span class="value">node:6</span></a>
         <a href="#steps"><span class="key">steps</span>:
     - <span class="key">init</span>: <span class="value">npm install</span>
@@ -70,6 +71,10 @@ You can access information about properties by hovering over the property name.
             <h4>Requires</h4>
             <p>A single job name or array of jobs that will trigger the job to run. Jobs defined with "requires: ~pr" are started by pull-request events. Jobs defined with "requires: ~commit" are started by push events. Jobs defined with "requires: ~sd@123:main" are started by job "main" from pipeline "123". Jobs defined with "requires: [deploy-west, deploy-east] are started after "deploy-west" and "deploy-east" are both done running successfully. "Note: ~ jobs denote an OR functionality, jobs without a ~ denote join functionality.</p>
         </div>
+        <div id="sourcePaths" class="hidden">
+            <h4>Source Paths</h4>
+            <p>You can optionally specify source paths that will trigger a job upon modification. In this example, the "main" job will only run if changes are made to things under the "src/app/" directory or the "screwdriver.yaml" file. This feature is only available for Github SCM.</p>
+        </div>
         <div id="shared" class="hidden">
             <h4>Shared</h4>
             <p>Defines a global configuration that applies to all jobs. Shared configurations are merged with each job, but may be overridden by more specific configuration in a specific job.</p>

docs/user-guide/configuration/jobconfiguration.md

@@ -13,18 +13,20 @@ toc:
     - title: Shared Configuration
       url: "#shared"
 ---
-# Job configuration
+# Job Configuration
 Jobs are how you define what happens in every build. Every job configuration must consist of an `image` and a list of `steps`, or a `template`. It also defines trigger requirement for the job using `requires`. See [workflow](/user-guide/configuration/workflow) for detailed usage of `requires` to create pipeline workflow.
 
 #### Example
 ```
 jobs:
     main:
+        requires: [~pr, ~commit]
         image: node:6
         steps:
             - init: npm install
             - test: npm test
-    main2: 
+    main2:
+        requires: main
         template: example/mytemplate@stable
 ```
 
@@ -35,6 +37,7 @@ The `image` configuration refers to a docker image, e.g. an container from [hub.
 ```
 jobs:
     main:
+        requires: [~pr, ~commit]
         image: my-custom-registry.example.com/myorg/myimage:label
         steps:
             - step1: echo hello
@@ -48,6 +51,7 @@ Steps are the list of instructions you want to execute in your build. These shou
 ```
 jobs:
     main:
+        requires: [~pr, ~commit]
         image: node:8
         steps:
             - step_name: step_command --arg1 --arg2 foo
@@ -69,8 +73,10 @@ shared:
 
 jobs:
     main:
+        requires: [~pr, ~commit]
         image: node:6
     main2:
+        requires: [main]
         steps:
             - greet: echo hello
 ```
@@ -79,11 +85,13 @@ The above example would be equivalent to:
 ```
 jobs:
     main:
+        requires: [~pr, ~commit]
         image: node:6
         steps:
             - init: npm install
             - test: npm test
     main2:
+        requires: [main]
         image: node:8
         steps:
             - greet: echo hello

docs/user-guide/configuration/settings.md

@@ -26,12 +26,14 @@ shared:
 
 jobs:
     main:
+        requires: [~pr, ~commit]
         template: example/mytemplate@stable
 ```
 
 ```
 jobs:
     main:
+        requires: [~pr, ~commit]
         template: example/mytemplate@stable
         settings:
             email: [[email protected], [email protected]]
@@ -42,7 +44,7 @@ jobs:
 To enable emails to be sent as a result of build events, use the email setting.
 You can configure a list of one or more email addresses to contact. You can also configure when to send an email, e.g. when the build status is `SUCCESS` and/or `FAILURE`.
 
-### Example
+#### Example
 ```
         settings:
             email:
@@ -54,7 +56,7 @@ You can configure a list of one or more email addresses to contact. You can also
 To enable Slack notifications to be sent as a result of build events, invite the `screwdriver-bot` Slack bot to your channel(s) and use the Slack setting in your Screwdriver yaml.
 You can configure a list of one or more Slack channels to notify. You can also configure when to send a Slack notification, e.g. when the build status is `SUCCESS` and/or `FAILURE`.
 
-### Example
+#### Example
 
 This Slack setting will send Slack notifications to `mychannel` and `my-other-channel` on all build statuses:
 

docs/user-guide/configuration/sourcePaths.md

@@ -0,0 +1,31 @@
+---
+layout: main
+title: Source Paths
+category: User Guide
+menu: menu
+toc:
+    - title: Source Paths
+      url: "#source-paths"
+
+---
+# Source Paths
+Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git).
+
+
+_Note: This feature is only available for [Github SCM](https://github.com/screwdriver-cd/scm-github)._
+
+## Types of source paths
+You can either specify subdirectories and/or specific files as source paths. To denote a subdirectory, leave a trailing slash (`/`) at the end.
+
+#### Example
+In the following example, the job `main` will start after any SCM pull-request, _or_ commit event on files under `src/app/` or the `screwdriver.yaml` file.
+
+```yaml
+jobs:
+      main:
+            image: node:6
+            requires: [~pr, ~commit]
+            sourcePaths: ["src/app/", "screwdriver.yaml"]
+            steps:
+                - echo: echo hi
+```