yaml triggers doc

docs/preview/yamlgettingstarted-authz.md

@@ -2,11 +2,10 @@
 
 ## Create definition on push
 
-The ability to create a definition on push, is currently only supported for Git repos in VSTS.
+The ability to create a definition on push, is currently only supported for Git repositories in VSTS.
 
-The ability to create a definition on-push is currently only supported for Git repos in the
-same VSTS team project as the build definition. The ability to create a definition from a push,
-requires whoever pushes the commit to have authorization to create a definition.
+The build definition will be created in the same VSTS team project. Whoever pushes the commit must
+be authorized to create a definition.
 
 For details about creating a definition on-push, refer [here](yamlgettingstarted-definition.md).
 
@@ -26,10 +25,10 @@ when saving the definition using the web UI or REST API.
 
 The ability to authorize resources on push, is currently only supported for Git repos in VSTS.
 
-This feature is only supported for pushes to the file `.vsts-ci.yml` in the root of the repo,
-and in the default branch (specified on the repo options in source control). A push to the file
-will cause the definition to be updated. When the YAML file is changed, the person who pushed
-the branch update is considered to be the person updating the definition (regardless of commit author).
+This feature is only supported for pushes to the file `.vsts-ci.yml` in the root of the repo.
+A push to the file will cause the definition to be updated. When the YAML file is changed, the
+person who pushed the branch update is considered to be the person updating the definition
+(regardless of commit author).
 
 Note, resource authorization is currently append only. Removing a resource from the YAML
 file will not remove it's authorized status. A future update will provide a way to

docs/preview/yamlgettingstarted-definition.md

@@ -2,9 +2,8 @@
 
 ## When using a Git repo in your VSTS team project
 
-Push a YAML file `.vsts-ci.yml` to the default branch (typically master) in the root
-of your repository. A definition `<REPO_NAME>/<REPO_NAME> CI` will be created with a
-continuous integration trigger for the default branch.
+Push a YAML file `.vsts-ci.yml` to the root directory of your repository. A definition
+`<REPO_NAME>/<REPO_NAME> CI` will be created, and a CI build will be triggered.
 
 Note, the definition will only be created if whoever pushes the branch update has
 permission to create a definition.
@@ -21,6 +20,7 @@ located anywhere within your repo.
 
 ```yaml
 queue: Hosted VS2017
+
 steps:
 - script: echo hello world
 ```

docs/preview/yamlgettingstarted-triggers.md

@@ -0,0 +1,96 @@
+# YAML getting started - YAML triggers (not yet available, for discussion only)
+
+## Simple CI trigger syntax
+
+On push, the YAML file from the branch that was updated, is used to determine whether
+to queue a CI build.
+
+For example, if master is updated, the trigger defined in master will be used. If a different
+branch is updated, the YAML file from that branch will be used to determine whether to queue a
+build.
+
+```yaml
+trigger:
+- master
+- releases/*
+```
+
+## CI is opt-out
+
+When not specified, the default trigger for build would be all branches.
+
+For build this behavior makes sense. Especially when we start supporting on-push defintion creation from any branch. And on-push resource authorization from any branch.
+
+For release, CI trigger would likely be opt-in? However with YAML, release will be tightly coupled with a repository. So opt-out CI behavior might also make sense for release? Or opt-out, but the default for RM only includes master?
+
+```yaml
+trigger: false | none # Turn off CI
+```
+
+## Full CI trigger syntax
+
+```yaml
+trigger:
+  batch: bool | number
+  branches:
+    include: []
+    exclude: []
+  paths:
+    include: []
+    exclude: []
+```
+
+## Schedules (future; needs cleanup)
+
+```yaml
+schedules:
+- schedule: name
+  whenUnchanged: bool
+  days: # Also supports a string instead of an array: "<DAY>" or "All" or "Weekdays"
+  - sun
+  - mon
+  - tues
+  - wed
+  - thurs
+  - fri
+  - sat
+  timeZone: EST # Defaults to account time zone? Do we know that info? We might need to maintain a mapping for this abbrev, it is not in system.timeZoneInfo.
+  times:
+  - 03:00 am
+  - 03:00 pm
+  branches:
+    include: []
+    exclude: []
+```
+
+## Triggers on resources (future)
+
+```yaml
+resources:
+  repositories:
+  - name: tools
+    trigger: # Need a property to hang trigger info on
+      branches:
+        include: []
+        exclude: []
+      # ...polling, etc
+
+  builds:
+  - name: otherDefinition
+    trigger: true # Simple build trigger
+
+  - name: otherDefinition2
+    trigger: # Build trigger with branch/tag filters
+      branches:
+        include:
+        - releases/*
+        exclude: []
+      tags:
+        include: []
+        exclude: []
+
+  packages:
+  - name: somePackage
+    feed: someFeed
+    trigger: true # Packages too
+```

docs/preview/yamlgettingstarted.md

@@ -28,6 +28,8 @@ YAML builds require the latest agent. When a YAML build is queued, your agent wi
 
 [Multiple phases](yamlgettingstarted-phases.md)
 
+[Triggers](yamlgettingstarted-triggers.md)
+
 ## Misc
 
 [Resource authorization](yamlgettingstarted-authz.md)