-
-
Notifications
You must be signed in to change notification settings - Fork 46
/
interface.clj
161 lines (131 loc) · 6.42 KB
/
interface.clj
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
(ns polylith.clj.core.api.interface
"If we want to build tooling around Polylith or e.g. use `poly` functionality in our
`build.clj` file, then we can use the [clj-poly](https://clojars.org/polylith/clj-poly) library
and get access to some of the functionality that is included in the `poly` command line tool.
The difference between the `clj-poly` library and the `poly` tool is that the latter is AOT compiled
into Java bytecode, while the library is just a normal Clojure library (source code that is zipped
into a jar file). This is good, because now we can expect the same behaviour from both.
We can use the `poly` tool as a library by including the `clj-poly` library
as a dependency to a project's `deps.edn` file, e.g.:
```clojure
:aliases {:dostuff {...
:extra-deps {...
polylith/clj-poly {:mvn/version \"0.2.19\"}}
```
...or by selecting a [sha](https://github.com/polyfy/polylith/commits/master) from
the polylith GitHub repo, e.g.:
```clojure
...
polylith/clj-poly {:git/url \"https://github.com/polyfy/polylith.git\"
:sha \"3b3e4ceac31d27f9a87862286f1ba01a3e4705ef\"
:deps/root \"projects/poly\"}
```
As an example, the `clj-poly` library is first specified in the
[build](https://github.com/polyfy/polylith/blob/5ff79341e7dc3fc6a486584c6c2f2f46cb577d6e/deps.edn#L120)
alias in polylith's `build.clj` and then used in
[build.clj](https://github.com/polyfy/polylith/blob/9e79264981b0c5be6e6cb70c93a540a82c489510/build.clj#L83).
If you need more access than is exposed by the API at the moment, just reach out to the
Polylith team in [Slack](https://clojurians.slack.com/messages/C013B7MQHJQ)
and we will try to help out.
All other code that is not part of the public API, is used at your own risk,
and may change in a breaking way between `clj-poly` versions."
(:require [polylith.clj.core.api.core :as core]
[polylith.clj.core.api.test :as test]
[polylith.clj.core.version.interface :as version])
(:refer-clojure :exclude [test])
(:gen-class))
(def api-version
"The version of the different types of APIs, stored in a hash map with these keys:
```clojure
:api The version of this API.
:test-runner The version of the test runner.
:ws The version of the workspace structure.
```
Each key stores a map with two keys:
```clojure
:breaking Increased by one if a breaking change + :non-breaking is set to zero.
:non-breaking Increased by one if a non-breaking change.
```
When a new version of the [clj-poly](https://clojars.org/polylith/clj-poly) library is released to Clojars,
any of the three APIs may change version, but the ambition is to never break `:api` and `:test-runner`.
The exception is if we make a major changes to the workspace structure, e.g. add support for multiple workspaces.
With `:ws` it's different, and we know that the workspace structure will change over time, so pay extra
attention every time you bump `clj-poly` and have a look at the [versions](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/versions) page,
which lists all the changes for different versions.
Examples of a breaking change of the workspace structure:
```
- If an attribute changes name.
- If an attribute is deleted.
- If an attribute starts to store its data in a breaking way.
```
Any changes that only add functionality/attributes, will increase the `:non-breaking` number by one.
If you use a SNAPSHOT version, then you can check [next-release.adoc](https://github.com/polyfy/polylith/blob/master/next-release.adoc)
to get a summary of all the changes that have been made since the last stable/final release."
{:api version/api-version
:test-runner version/test-runner-api-version
:ws version/workspace-version})
(defn check
"The value of ok? is set to true if no error messages, e.g.:
```clojure
{:ok? true
:error-messages []}
```"
[]
(core/check))
(defn test
"Runs tests. If since is not given, then \"stable\" will be used.
How to also include project tests since latest release (run tests incrementally).
```clojure
(test :project \"since:release\")
```
How to run all tests since previous release for the 'myproject' project.
```clojure
(test :all \"since:previous-release\" \"project:myproject\")
```
The arguments can come in any order."
[& args]
(test/test args))
(defn projects-to-deploy
"Returns the projects that have changed (directly or indirectly) since the _last stable point in time_,
and is primarily used to know which projects to build and deploy.
If called with:
```clojure
(projects-to-deploy \"release\")
```
...it will execute the equivalent to this under the hood:
```
poly ws get:changes:changed-or-affected-projects since:release skip:development
```
...which returns all changed or affected projects, except `development`, since the last release.
If `since` is passed in as `nil` then `stable` will be used."
[since]
(core/projects-to-deploy since))
(defn workspace
"Returns the workspace or part of the workspace by passing in either
a key that can be found in the `:tag-patterns` keys in `workspace.edn`
optionally prefixed with `previous-`, or a git SHA, as the first argument,
and a list of keywords, strings, or numbers as the second argument.
`:keys` and `:count` are also valid keys to pass in.
Examples:
```clojure
;; Returns the whole workspace structure, equivalent to: poly ws since:stable
(workspace nil)
;; Returns the whole workspace structure, equivalent to: poly ws since:release
(workspace \"release\")
;; Returns the interface namespace name, equivalent to: poly ws get:settings:interface-ns
(workspace nil \"settings\" \"interface-ns\")
```
Passing in `since` is only needed if we access things under the `:changes` top key
or `:bricks-to-test` and `:projects-to-test` under `:projects`.
Avoid using things under `:configs`, if they can be found in e.g. `:settings`,
`:components`, `:bases`, `:projects`, or elsewhere.
Note that since version `0.2.18` we only publish `clj-poly` to Clojars and not the old `clj-api`."
[since & keys]
(core/workspace since keys))
(comment
(projects-to-deploy nil)
(projects-to-deploy "release")
(workspace nil)
(workspace "release")
(workspace "stable" "settings" "interface-ns")
#__)