feat: Add sd-cmd documentation (#158)

* fix: Fix TOC for FAQ

* fix: Update workflow with requires keyword

* feat: Add commands documentation

docs/_data/menu.yml

@@ -30,6 +30,8 @@
       url: "/user-guide/environment-variables"
     - title: "Templates"
       url: "/user-guide/templates"
+    - title: "Commands"
+      url: "/user-guide/commands"
     - title: "FAQ"
       url: "/user-guide/FAQ"
 - title: "Cluster Management"

docs/user-guide/FAQ.md

@@ -23,8 +23,8 @@ toc:
       url: "#how-do-i-delete-a-pipeline-permanently"
     - title: How do I fix "Build failed to start" error message?
       url: "#how-do-i-fix-build-failed-to-start-error-message"
-    - title: How do I re-run a job's build?
-      url: "#how-do-i-re-run-a-jobs-build"
+    - title: How do I rollback?
+      url: "#how-do-i-rollback"
 ---
 
 # Frequently Asked Questions

docs/user-guide/commands.md

@@ -0,0 +1,105 @@
+---
+layout: main
+title: Commands
+category: User Guide
+menu: menu
+toc:
+    - title: Commands
+      url: "#commands"
+    - title: Using a command
+      url: "#using-a-command"
+    - title: Creating a command
+      url: "#creating-a-command"
+    - title: Finding commands
+      url: "#finding-commands"
+    - title: More links
+      url: "#more-links"
+---
+# Commands
+
+Screwdriver commands are executables which can either be a group of [commands](https://en.wikipedia.org/wiki/Command_(computing)) in a script or a binary that people can use to replace a step definition in a [screwdriver.yaml](./configuration).
+
+## Using a command
+
+To use a command, define a `screwdriver.yaml` that uses the `sd-cmd` cli with the format:
+
+```
+$ sd-cmd exec <namespace>/<name>@<version> <arguments>
+```
+
+__Input:__
+
+- `namespace/name` - the fully-qualified command name
+- `version` - a semver-compatible format or tag
+- `arguments` - passed directly to the underlying format
+
+__Output:__
+
+All debug logs about the command lookup and execution are stored in `$SD_ARTIFACTS_DIR/.sd/commands/namespace/name/version/timestamp.log`
+
+Example:
+```yaml
+jobs:
+    main:
+        requires: [~pr, ~commit]
+        steps:
+            - exec: sd-cmd exec foo/bar@1 -baz sample
+```
+
+Screwdriver will download that binary or script from the Store, make it executable, and run it with the `-baz sample` arguments directly:
+```
+$ /opt/sd/commands/foo/bar/1.0.1/foobar.sh -baz sample
+```
+
+## Creating a command
+
+Publishing and running commands must be done from a Screwdriver pipeline.
+
+### Writing a command yaml
+
+To create a command, create a repo with a `sd-command.yaml` file. The file should contain a namespace, name, version, description, maintainer email, format, and a binary config with a path to file.
+
+Example `sd-command.yaml`:
+
+```yaml
+namespace: foo # Namespace for the command
+name: bar # Command name
+version: 1.0 # Major and Minor version number (patch is automatic)
+description: |
+  Lorem ipsum dolor sit amet.
+maintainer: [email protected] # Maintainer of the command
+format: binary # Format the command is in (binary)
+binary:
+    file: ./foobar.sh # Path to script or binary file
+```
+
+### Writing a screwdriver.yaml for your command repo
+
+To validate your command, run the `command-validate` script from the [screwdriver-command-validator](https://github.com/screwdriver-cd/command-validator) npm module. This means the build image must have NodeJS and NPM properly installed to use it.
+
+To publish your command, run the `sd-cmd publish` command in a separate job. `-f` stands for file.
+
+Example `screwdriver.yaml`:
+```yaml
+shared:
+    image: node:6
+jobs:
+    main:
+        requires: [~pr, ~commit]
+        steps:
+            - install: npm install screwdriver-command-validator
+            - validate: ./node_modules/.bin/command-validate -f sd-command.yaml
+    publish:
+        requires: [main]
+        steps:
+            - publish: sd-cmd publish -f sd-command.yaml
+```
+
+## Finding commands
+
+To figure out which commands already exist, you can make a `GET` call to the `/commands` endpoint. See the [API documentation](./api) for more information.
+
+## More links
+- [Design specifications](https://github.com/screwdriver-cd/screwdriver/blob/master/design/commands.md)*
+
+_*May be out of date._

docs/user-guide/quickstart.md

@@ -3,7 +3,7 @@ layout: main
 title: Quickstart
 category: User Guide
 menu: menu
-toc: 
+toc:
     - title: Getting Started with Screwdriver
       url: "#getting-started-with-screwdriver"
       active: true
@@ -46,22 +46,7 @@ Now that we’ve setup our app, we can start developing. This app demonstrates h
 
 ### screwdriver.yaml
 
-The `screwdriver.yaml` is the only config file you need for using Screwdriver. In it, you will define all your steps needed to successfully develop, build and deploy your application.
-
-#### Workflow
-
-The `workflow` describes the order that the jobs execute. The "main" job, which is created by default, is always
-executed first, followed by jobs listed in this workflow block.
-
-Here, we have defined a job named "second_job", which
-will run after the "main" job.
-
-```yaml
----
-# Workflow list definition
-workflow:
-  - second_job
-```
+The `screwdriver.yaml` is the only config file you need for using Screwdriver. In it, you will define all your steps needed to successfully develop, build and deploy your application. See the User Guide -> Configuration section for more details.
 
 #### Shared
 The `shared` section is where you would define any attributes that all your jobs will inherit.
@@ -75,8 +60,11 @@ shared:
   image: buildpack-deps
 ```
 
-#### Jobs
-The `jobs` section is where all the tasks (or `steps`) that each job will execute is defined. All pipelines have "main" implicitly defined. The definitions in your screwdriver.yaml file will override the implied defaults.
+### Jobs
+The `jobs` section is where all the tasks (or `steps`) that each job will execute is defined.
+
+### Workflow
+The `requires` keyword denotes the order that jobs will run. Requires is a single job name or array of job names. Special keywords like `~pr` or `~commit` indicate that the job will run after a PR is merged or code is committed, respectively.
 
 ### Steps
 The `steps` section contains a list of commands to execute.
@@ -90,15 +78,16 @@ The "run_arbitrary_script" executes a script. This is an alternative to a Makefi
 
 ```yaml
 # Job definition block
-# "main" is a default job that all pipelines have
 jobs:
   main:
+    requires: [~pr, ~commit]
     # Steps definition block.
     steps:
       - export: export GREETING="Hello, world!"
       - hello: echo $GREETING
       - set-metadata: meta set example.coverage 99.95
   second_job:
+    requires: [main] # second_job will run after main job is done
     steps:
       - make_target: make greetings
       - get-metadata: meta get example

docs/user-guide/templates.md

@@ -33,6 +33,7 @@ Screwdriver takes the template configuration and plugs it in, so that the `screw
 jobs:
     main:
         image: node:6
+        requires: [~pr, ~commit]
         steps:
           - install: npm install
           - test: npm test
@@ -50,6 +51,7 @@ Example:
 ```yaml
 jobs:
     main:
+        requires: [~pr, ~commit]
         template: [email protected]
         steps:
             - preinstall: echo pre-install
@@ -65,6 +67,7 @@ Example:
 ```yaml
 jobs:
     main:
+        requires: [~pr, ~commit]
         template: [email protected]
         steps:
             - install: echo skip installing
@@ -112,14 +115,15 @@ Example `screwdriver.yaml`:
 shared:
     image: node:6
 jobs:
-    # the main job is run in pull requests as well
     main:
+        requires: [~pr, ~commit]
         steps:
             - install: npm install screwdriver-template-main
             - validate: ./node_modules/.bin/template-validate
         environment:
             SD_TEMPLATE_PATH: ./path/to/template.yaml
     publish:
+        requires: [main]
         steps:
             - install: npm install screwdriver-template-main
             - publish: ./node_modules/.bin/template-publish