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 package.json.

The .atomist directory

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

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

The only required file in the .atomist directory is the package.json. 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
mocha contains Mocha unit tests
node_modules contains source code for TypeScript typings and dependencies installed by NPM
package.json Rug project metadata within a standard NPM package.json file declaring the TypeScript dependencies, required
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/package.json file contains the Rug archive project metadata. The package.json file is a standard NPM package.json file. Typical contents for the package.json will look like:

{
  "name": "@my-org/my-rug-project",
  "description": "Atomist Rugs used in the end-user documentation",
  "version": "0.1.0",
  "author": "My Company",
  "repository": {
    "type": "git",
    "url": "https://github.com/atomist/my-rug-project.git"
  },
  "keywords": [
    "atomist",
    "rug"
  ],
  "homepage": "https://github.com/atomist/my-rug-project#readme",
  "bugs": {
    "url": "https://github.com/atomist/my-rug-project/issues"
  },
  "dependencies": {
    "@atomist/rugs": "^1.0.0-m.5"
  },
  "devDependencies": {
    "@types/mocha": "^2.2.40",
    "@types/power-assert": "^1.4.29",
    "espower-typescript": "^8.0.0",
    "mocha": "^3.2.0",
    "power-assert": "^1.4.2",
    "tslint": "^5.0.0",
    "typescript": "2.3.2"
  },
  "directories": {
    "test": "mocha"
  },
  "scripts": {
    "autotest": "supervisor -q -n exit -e ts -x npm -- run mocha",
    "lint": "tslint '**/*.ts' --exclude 'node_modules/**' -t verbose",
    "mocha": "mocha --compilers ts:espower-typescript/guess 'mocha/**/*.ts'",
    "test": "npm run mocha && rug test"
  },
  "atomist": {
    "requires": "[1.0.0-m.4,2.0.0)"
  }
}

You can see this is a standard NPM package.json file with the addition of the "atomist" section. In this example, the only parameter in the "atomist" section is "requires", which specifies the unique coordinates of the Rug archive: its group, name and version. Dependencies and extensions may also be declared:

Key Description
"requires" The Rug runtime version this project is being developed with. Version range is allowed
"dependencies" List of project dependencies in form group:artifact:version. Version ranges are allowed
"extensions" List of binary dependencies, e.g., Rug Extension types. Version ranges are allowed

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 .atomist.requires key in the package.json. 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.

"atomist": {
  "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.

"atomist": {
  "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 archives containing the Rugs being called as an entry in the object value of the .atomist.dependencies key. The fully-qualified name of a Rug archive is archive group and artifact name joined by a colon (:). The value of the dependency should be either an exact version or a version range using a Maven version range. Here is an example of a dependency on a specific Rug archive version.

"atomist": {
  "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 object value of the .atomist.extensions key. The fully-qualified name of the extension is comprised of the group ID and artifact ID joined by a colon (:). The value of the extension should be either an exact version or a version range using a Maven version range. Here is an example of a version-range extension dependency.

"atomist": {
  "extensions": {
    "com.atomist:travis-rug-extension": "[0.17.0,0.18.0)"
  }
}

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. You only need to specify the dependencies section to the minimum released version of the Rug language your project targets. The version value can be any version expression accepted by NPM.

"dependencies": {
  "@atomist/rugs": "^1.0.0-m.4"
}

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.