1 | # Atomist Concepts
|
2 |
|
3 | ## Overview
|
4 |
|
5 | Atomist enables powerful development automation.
|
6 |
|
7 | This starts with the **Atomist Cortex**: a rich, interconnected model
|
8 | of the things that matter to your team, such as your projects, their
|
9 | source code, builds, deploys and the communication channels around
|
10 | them. The Atomist service keeps the Cortex up to date as events occur.
|
11 |
|
12 | Atomist enables you to write **[event handlers](EventHandlers.md)** to
|
13 | react to events affecting the model--with access to the full
|
14 | context--and write commands informed by it
|
15 | (**[command handlers](CommandHandlers.md)**). It also
|
16 | manages [secrets](Secrets.md) to ensure that automations always have
|
17 | access to the correct credentials, whichever user invoked them.
|
18 |
|
19 | ## Changing the World
|
20 |
|
21 | Atomist enables three key ways of interacting with the world:
|
22 |
|
23 | - Changes to code or configuration, made by *editing*
|
24 | projects. See [Project Operations](ProjectOperations.md).
|
25 | - API calls to systems such as GitHub or Travis (or arbitrary
|
26 | code). See [Secrets](Secrets.md).
|
27 | - Notifications to people or teams, typically via Slack, benefiting
|
28 | from Atomist's ability to relate Slack and other identities (such
|
29 | as GitHub identities).
|
30 |
|
31 | For example, Atomist makes it possible to implement scenarios such as:
|
32 |
|
33 | Scenario | Automation type | Implementation
|
34 | ---------|-----------------|---------------
|
35 | When a commit breaks the build, send a DM in Slack to the developer who made the offending commit to alert them | Event handler | Subscribe to a build with a failed status, specifying a GraphQL query that retrieves the commit, committer, person and Slack ID (if available) of the person. Use this library to send the user a DM.
|
36 | When a PR causes an JSON file to be ill-formed, set a failed status on it | Event handler | React to a PR, looking at the last commit and using this project's support to clone the repo using the token managed by Atomist as a secret. Attempt to parse the content; if it fails, use the GitHub status API (with the same token) to set a status.
|
37 | Look for all imports of a given module across all projects in an organization | Command handler | Extend this project's convenient `EditorCommandSupport` class to look into the contents of all repos in the present team.
|
38 | When there's a new release of a library, create a branch in all Maven or `npm` projects depending on that library. For each build, if it succeeds, raise a PR on the branch. If it fails, create an issue in the repository warning of the problem. | Event handler | React to a tag with a non-snapshot semantic version. Look for all projects using the library (see above) and edit them to create the branch. Write a separate event handler that reacts to the builds of these branches.
|
39 |
|
40 | Because automations are written in TypeScript (or JavaScript), you can
|
41 | use normal programming practices to pull out common behavior for
|
42 | reuse.
|
43 |
|
44 | ## Atomist Clients
|
45 |
|
46 | Code in automations is written in Atomist clients, which interact with
|
47 | the Atomist service primarily by [GraphQL](http://graphql.org/).
|
48 |
|
49 | Clients can be written in any language, but we recommend our Node.js
|
50 | client (this project), which makes things much easier.
|
51 |
|
52 | Each client is itself a server, which hosts automations that can be
|
53 | invoked via the Atomist bot or when events occur. A client can host
|
54 | any number of automations, and can be hosted wherever the author likes:
|
55 | locally during testing, inside a corporate firewall, or on a public
|
56 | cloud or PaaS.
|
57 |
|
58 | ### Development Process
|
59 |
|
60 | The following is a summary of the steps to create new automations:
|
61 |
|
62 | 1. Create a `node` project that depends on the client (this) library.
|
63 | 2. Add event handlers and command handlers.
|
64 | 3. Deploy your automations by running the project. It will
|
65 | automatically register with the Atomist server.
|