1.2.1 • Published 4 years ago

@atomist/sdm-local v1.2.1

Weekly downloads
56
License
Apache-2.0
Repository
github
Last release
4 years ago

Slalom: Local Software Delivery Machine

A software delivery sdm.machine helps you write and deliver code that is up to your own standards, at scale. This project runs a software delivery sdm.machine locally on your sdm.machine, responding to your commands and your commits.

For instance:

  • Every time you make a commit, perform a build in the background, and tell you if it fails.
  • every time you make a commit, fix trivial linting errors.
  • at your command, perform common code changes that you program (such as upgrade a library). It can do this across all the repositories you have checked out, and tell you if this causes any build failures.
  • at your command, create a new project by copying and modifying a working project you already have.

For more information on software delivery machines (SDM), see Rod Johnson's blog Why you need a Software Delivery Machine. This video shows an SDM in action. The blogs and videos show an SDM that connects to Atomist's cloud service. This repository contains a local software delivery sdm.machine that works on your development sdm.machine and responds to your commits, performing whatever actions you decide should happen in response to new code.

The SDM framework understands code and delivery flows. Further description is in the Atomist sdm library project.

This project is purely open source and can be used without the Atomist service. However, the code you write it can run unchanged to benefit your entire team if you do connect to the Atomist service, as the SoftwareDeliveryMachine API is identical between local and cloud SDMs.

Usage

Overview

You customize an SDM to work with the code you care about: fix formatting errors (with commits), perform code reviews, run tests, publish artifacts, etc.

It also responds to your commands: to create new projects, edit code in existing projects, or other actions you program into it.

The instructions here will take you through

  • Initializing your local SDM
  • Seeing it react to a push
    • then changing how it reacts to your push
  • Creating a new project with a generator
    • then changing it to work from a project of your choice
  • Changing code with an editor
    • then making your own code editor
  • Running a command
    • then making your own commands

Later, when they've proven useful, you can elevate your push reactions, generators, editors, and commands into the cloud for your whole team to use with Atomist.

Here is an architecture diagram (TEMPORARY: linking to the raw image of files doesn't work in private repos)

Setup

To create your local SDM, you need to:

  • have an SDM. Start by cloning the seed-sdm. (TODO: create a command in this repo to do this)
  • provide configuration for local mode. This is safe to commit, because it will not change the functionality in your SDM unless your environment sets ATOMIST_MODE=local or you start the SDM with --local.
import { ConfigureOptions } from "@atomist/sdm-core";

const Options: ConfigureOptions = {
    ...,
    local: {
        // defaults to your home directory
        repositoryOwnerParentDirectory: process.env.SDM_PROJECTS_ROOT || "/Users/me/my-code",
        mergeAutofixes: true,
        preferLocalSeeds: true,
    },
}

export const configuration = {
    ...,
postProcessors: [
    configureSdm(createMachine, Options),//  <---- add this
    ...
],
}

The SDM works on projects that must be git repositories.

To find projects on your filesystem, the SDM looks in directories group by owner (on GitHub, the owner is an organization or user; on BitBucket, the owner is a user or a BitBucket Project), and it looks for each owner directory under one parent directory.

The directory structure looks like this:

$SDM_PROJECTS_ROOT
├── owner1
│   ├── repo1
│   └── repo2
└── owner2
    ├── repo3
    └── repo4

3) Send commit events from your repositories to your SDM. See "Configure existing projects" below. TODO: test this. how does it know

4) TEMPORARY for Atomists: currently Slalom isn't published on npm, so you have to:

  • clone this repository. In its directory:
  • npm install
  • npm run build
  • npm link
  • Then over in your SDM repo, run npm link @atomist/slalom. Any time you npm install again, you'll have to re-link Slalom. Also, IntelliJ won't like you because it isn't in the package.json, so it won't recognize references to it. This won't be an issue once this project is public.

Startup

TODO: we need to install the atomist CLI.

Start your SDM in local mode by setting an environment variable and then invoking the atomist CLI. ATOMIST_MODE=local atomist start. The SDM will run in the background, listening for commands and events. This terminal will display logs.

Trigger commands with @atomist <command> in another terminal. Try @atomist say hello! Your SDM will send messages right back to where you ran the command.

Events are triggered by git postCommit hooks. Messages from events don't come back to wherever you made the commit. Instead:

See messages from events

In order to see messages from events (not interspersed with logs), activate a message listener in another terminal:

slalom listen

Configure Existing Projects

If you already have repositories cloned under your $SDM_PROJECTS_ROOT, configure them to activate the local SDM on commit.

Add the Atomist git hook to the existing git projects within this directory structure by running the following command:

slalom add-git-hooks

Success will result in output like the following:

2018-06-06T11:23:58.003Z [m:85087] [info ] Adding extension pack 'WellKnownGoals' version 0.1.0 from Atomist
2018-06-06T11:23:58.051Z [m:85087] [info ] Searching under child directory [spring-team] of /Users/rodjohnson/temp/local-sdm
2018-06-06T11:23:58.052Z [m:85087] [info ] Searching under child directory [undefined] of /Users/rodjohnson/temp/local-sdm
2018-06-06T11:23:58.053Z [m:85087] [info ] Searching under child directory [x] of /Users/rodjohnson/temp/local-sdm
2018-06-06T11:23:58.074Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/spring-team/danger-mouse
2018-06-06T11:23:58.076Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/spring-team/fiddlesticks
2018-06-06T11:23:58.077Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/spring-team/foo
2018-06-06T11:23:58.078Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/spring-team/losgatos1
2018-06-06T11:23:58.079Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/spring-team/spring-rest-seed
2018-06-06T11:23:58.080Z [m:85087] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/x/y

Running slalom add-git-hooks is only necessary for pre-existing cloned directories and directories that are cloned using git rather than the local SDM.

Reacting to commits

A software delivery sdm.machine reacts to code changes. For instance, when you commit to a Spring Boot application, it can start the app up locally, while running tests. When you commit to a Node library, it can publish a snapshot to npm, while running tests, and while fixing any formatting errors and performing automated code review and identifying sensitive changes.

Make a commit in any repository within $SDM_PROJECTS_ROOT, and the SDM will run immediately.

Commits to managed repos generate Atomist push events.

Adding to your SDM

The API is identical to the API of a cloud-connected Atomist SDM.

Adding projects

Further projects can be added under the expanded directory tree in three ways:

Normal git Clone

Cloning any git project from anywhere under $SDM_PROJECTS_BASE and running slalom add-git-hooks to add git hooks to it.

Symbolic Link

Go to the correct organization directory, creating it if necessary. Then create a symlink to the required directory elsewhere on your sdm.machine. For example:

ln -s /Users/rodjohnson/sforzando-dev/idea-projects/flight1

Then run slalom add-git-hooks and the linked project will be treated as a normal project.

Import Command

The easiest way to add an existing project to your SDM projects is: run the import command to clone a GitHub.com repository in the right place in the expanded tree and automatically install the git hook:

slalom import --owner=johnsonr --repo=initializr

This is the recommended way, as it will run Atomist onboarding events for a new repo.

Output will look as follows:

018-06-06T11:27:27.068Z [m:85220] [info ] Adding extension pack 'WellKnownGoals' version 0.1.0 from Atomist
2018-06-06T11:27:27.116Z [m:85220] [info ] Adding GitHub project johnsonr/initializr
Cloning into 'initializr'...
warning: redirecting to https://github.com/johnsonr/initializr/
2018-06-06T11:27:33.349Z [m:85220] [info ] addGitHooks: Adding git post-commit script to project at /Users/rodjohnson/temp/local-sdm/johnsonr/initializr

Only public repos are supported.

Running Commands

slalom show skills

Type in intents as follows:

slalom create spring

No parameters beyond the command name are required. However, command-specific parameters may be provided in options syntax.

Architecture

This project consists of three parts:

  • An Atomist SDM running in its own process, in a special local mode
  • A command line.
  • git hooks inserted in those projects you wish to use the local SDM with.

Advanced Setup

Mapped Parameters and Secrets

Environment variables

  • SLACK_TEAM
  • SLACK_USER_NAME

Required Ports

The following ports are required:

  • 2866: The default port for your Automation client
  • 6660: The default port for listening to all Atomist messages
  • Port range above 10000: Used for routing messages back to command line.

Roadmap

  • Decide how to get build results from external tools in (if we wish to)
1.2.1

5 years ago

1.2.0

5 years ago

1.1.0

5 years ago

1.0.10

5 years ago

1.0.9

5 years ago

1.0.8

5 years ago

1.0.7

5 years ago

1.0.6

5 years ago

1.0.5

5 years ago

1.0.4

5 years ago

1.0.3

5 years ago

1.0.2

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-RC.2

5 years ago

1.0.0-RC.1

5 years ago

1.0.0-M.5

6 years ago

1.0.0-M.4

6 years ago

1.0.0-M.3

6 years ago

1.0.0-M.2

6 years ago

1.0.0-M.1

6 years ago

0.1.21

6 years ago

0.1.20

6 years ago

0.1.19

6 years ago

0.1.18

6 years ago

0.1.17

6 years ago

0.1.16

6 years ago

0.1.15

6 years ago

0.1.14

6 years ago

0.1.13

6 years ago

0.1.12

6 years ago

0.1.11

6 years ago

0.1.10

6 years ago

0.1.9

6 years ago

0.1.8

6 years ago

0.1.7

6 years ago

0.1.6

6 years ago

0.1.5

6 years ago

0.1.4

6 years ago

0.1.3

6 years ago