From 28a85787bbdd4f1efd85df0777710386200a6e3a Mon Sep 17 00:00:00 2001 From: Tiffany K Date: Wed, 21 Mar 2018 14:41:01 -0700 Subject: [PATCH] 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 | 2 + docs/user-guide/FAQ.md | 4 +- docs/user-guide/commands.md | 105 ++++++++++++++++++++++++++++++++++ docs/user-guide/quickstart.md | 29 +++------- docs/user-guide/templates.md | 6 +- 5 files changed, 123 insertions(+), 23 deletions(-) create mode 100644 docs/user-guide/commands.md diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml index 52911ac8..51eb6198 100644 --- a/docs/_data/menu.yml +++ b/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" diff --git a/docs/user-guide/FAQ.md b/docs/user-guide/FAQ.md index 19ffbf94..1367208b 100644 --- a/docs/user-guide/FAQ.md +++ b/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 diff --git a/docs/user-guide/commands.md b/docs/user-guide/commands.md new file mode 100644 index 00000000..e1df6278 --- /dev/null +++ b/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 /@ +``` + +__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: foo@bar.com # 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._ diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index 3e20169a..187e47af 100644 --- a/docs/user-guide/quickstart.md +++ b/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 diff --git a/docs/user-guide/templates.md b/docs/user-guide/templates.md index c8f8d70e..7d943707 100644 --- a/docs/user-guide/templates.md +++ b/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: template_name@1.3.0 steps: - preinstall: echo pre-install @@ -65,6 +67,7 @@ Example: ```yaml jobs: main: + requires: [~pr, ~commit] template: template_name@1.3.0 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