Projects

A key design goal for Rug was to respect your own tooling as much as possible so that every project could be a working Atomist project, and every Atomist project remains a working project. Therefore, Atomist files reside unobtrusively within your existing projects. Specifically, Atomist files reside in a directory named .atomist at the root of your project’s source code hierarchy. Any project that has a .atomist directory at its root with a valid manifest.yml.

The .atomist directory

A typical Rug project will have a .atomist directory that looks something like the following.

.atomist
├── build/
├── editors/
├── generators/
├── handlers/
├── manifest.yml
├── node_modules/
├── package.json
├── reviewers/
├── target/
├── templates/
├── tests/
└── tsconfig.json

The only required file in the .atomist directory is the manifest.yml. The table below explains each entry.

Entry Description
build contains CI build scripts and configuration
editors contains Rug editors
generators contains Rug generators
handlers contains Rug command and event handlers
manifest.yml Rug archive metadata and dependencies declarations, required
node_modules contains source code for TypeScript typings and dependencies installed by NPM
package.json standard NPM package.json file declaring the TypeScript dependencies
reviewers contains Rug reviewers
target contains files generated by the Rug CLI during building and packaging
templates contains templates used by Rugs
tests contains Rug tests
tsconfig.json TypeScript compiler options useful for IDE TypeScript tooling

The tsconfig.json is not used by the Rug CLI when compiling TypeScript.

Metadata

The .atomist/manifest.yml file contains the Rug archive project metadata. The manifest.yml file is a standard YAML file. Typical contents for the manifest.yml will look like:

artifact: rug-editors
group: atomist-rugs
version: "0.15.0"
requires: "[0.12.0,1.0.0)"
dependencies:
extensions:
Key Value
artifact unqualified name of the Rug archive
group group of the Rug archive, typically the same as the GitHub owner
version semantic version of the Rug archive
requires version(s) of rug this Rug archive is compatible with
dependencies a sequence of other, fully-qualified Rug archives on which this Rug archive depends
extensions a sequence of Rug extensions (JVM JARs) on which this Rug archive depends

Dependencies

A Rug project can have four different types of dependencies:

  1. Rug runtime dependency
  2. Other Rug archives
  3. Rug extensions
  4. TypeScript types

Runtime

The Rug runtime dependency is specified using the requires key in the manifest.yml. The value of the requires key is a string that specifies either an exact Rug runtime version or a version range using the Maven version range. The following would cause the Rugs in the project to only executed by Rug runtime version 0.13.0.

requires: "0.13.0"

In contrast, the following specification could run under any version of the Rug runtime from 0.13.0, inclusive, up to, but not including, version 1.0.0.

requires: "[0.13.0, 1.0.0)"

When deciding on which version to use, the highest available version satisfying the range constraints will be used.

Archives

Rugs in one project can call Rugs in other archives as long as the calling Rug’s project declares a dependency on the archive of the Rug being called. Dependencies on other Rug archives are declared by listing the fully-qualified name of the Rug archive containing the Rug being called as an entry in the sequence value of the dependencies key. The fully-qualified name of a Rug archive is archive group and artifact name joined by a colon (:). You can optionally specify the version of the Rug archive dependency by appending a colon and the version to the full-qualified name. Here is an example of a dependency on a specific Rug archive version.

dependencies:
  - atomist-rugs:rug-editors:0.14.0

Extensions

Rugs in a project can use Rug extensions not in the Rug core if they declare a dependency on the extension. A dependency on a Rug extension is declared by listing the fully-qualified name of the Rug extension as an entry in the sequence value of the extensions key. The fully-qualified name of the extension is comprised of the group ID and artifact ID joined by a colon (:). You can optionally specify the version of the Rug extension dependency by appending a colon and the version to the full-qualified name. Here is an example of a specific-version extension dependency.

extensions:
  - com.atomist:travis-rug-extension:0.9.1

TypeScript types

While developing Rugs, and to fully benefit from the static typing support of the TypeScript language, your project should declare a dependency on an appropriate version of the Rug TypeScript typings in .atomist/package.json. The package.json file is a standard Node package file. You only need to specify the dependencies section to the minimum released version of the Rug language your project targets. Below are the complete contents of a valid package.json file.

{
  "dependencies": {
    "@atomist/rug": "0.13.0"
  }
}

The .atomist/package.json file does not impact the runtime of your Rug, which is driven by the value of the requires key in .atomist/manifest.yml. The former only exists to support a nice development experience from your favorite IDE or editor.

Basic Rug Project

A very basic Rug project can be generated using the Rug project generator. Instructions running the generator using the Rug CLI can be found in the project’s README.