summaryrefslogtreecommitdiff
path: root/yarns/branches-workspaces.yarn
blob: 96fbbd122b69701376f986d170c4d8ea9342fced (plain)
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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
Morph black box tests for system branches and workspaces
========================================================

Morph implements **system branches**, which are checked out and
manipulated by the user in **workspaces**. See
FIXME for more information.

Workspace creation
------------------

The first thing a user needs to do is create a workspace.

    SCENARIO    create and initialise a new workspace
    GIVEN       no workspace
    WHEN        the user initialises a workspace
    THEN        an empty workspace exists

The workspace directory may exist, if it is empty.

    SCENARIO    initialise an empty workspace directory
    GIVEN       an empty workspace directory
    WHEN        the user initialises a workspace
    THEN        an empty workspace exists

However, the directory must really be empty. It must not be
an empty, but initialised workspace.

    SCENARIO    initialise an existing, empty workspace directory
    GIVEN       no workspace
    WHEN        the user initialises a workspace
    AND         the user attempts to initialise a workspace
    THEN        morph failed

Likewise, if the directory exists, and is non-empty, but isn't an
existing workspace, initialising it should fail.

    SCENARIO    initialise a non-empty workspace directory
    GIVEN       a non-empty workspace directory
    WHEN        the user attempts to initialise a workspace
    THEN        morph failed

Checking out or branching system branches
-----------------------------------------

Once we have a workspace, we can check out a system branch.

    SCENARIO    check out an existing system branch
    GIVEN       a workspace
    AND         a git server
    WHEN        the user checks out the system branch called master
    THEN        the system branch master is checked out

Checking out a system branch should fail, if the branch doesn't exist.

    SCENARIO    checking out a system branch that doesn't exist
    GIVEN       a workspace
    AND         a git server
    WHEN        the user attempts to check out the system branch called foo
    THEN        morph failed

We can, instead, create a new system branch, off master.

    SCENARIO    branch off master
    GIVEN       a workspace
    AND         a git server
    WHEN        the user creates a system branch called foo
    THEN        the system branch foo is checked out

We can also branch off another system branch. However, we need to first
push the other branch to the git server, since Morph is not smart enough
to check for that locally.

    SCENARIO    branch off non-master
    GIVEN       a workspace
    AND         a git server
    WHEN        the user creates a system branch called foo
    AND         the user pushes the system branch called foo to the git server
    AND         the user creates a system branch called bar, based on foo
    THEN        the system branch bar is checked out

Query commands in workspaces
----------------------------

`morph workspace` writes out the fully qualified path to the workspace
directory, regardless of where the user is. There's a few cases.

    SCENARIO    morph workspace works at root of empty workspace
    GIVEN       a workspace
    WHEN        the user reports the workspace from the directory .
    THEN        the workspace is reported correctly

Also check it in the root of a system branch checkout, and inside
a git checkout inside that.

    SCENARIO    morph workspace works in system branch checkouts
    GIVEN       a workspace
    AND         a git server
    WHEN        the user checks out the system branch called master
    AND         the user reports the workspace from the directory master
    THEN        the workspace is reported correctly

We leak a little bit of the implementation here, to keep things simple:
the (mocked) git server the implementation sets up has the `test:morphs`
repository, which is the system branch root repository.

    WHEN        the user reports the workspace from the directory  master/test/morphs
    THEN        the workspace is reported correctly

However, running it outside a workspace should fail.

    SCENARIO    morph fails outside workspace
    GIVEN       no workspace
    WHEN        the user attempts to report the workspace from a non-workspace directory
    THEN        morph failed

`morph show-system-branch` should report the name of the system
branch, when run anywhere in the system branch checkout. As a special
case, if there is only one system branch checkout at or below the
current working directory, it will find it and report it correctly.

    SCENARIO    morph reports system branch
    GIVEN       a workspace
    AND         a git server
    WHEN        the user checks out the system branch called master
    AND         the user reports the system branch from the directory master
    THEN        the system branch is reported as master

    WHEN        the user reports the system branch from the directory master/test/morphs
    THEN        the system branch is reported as master

    WHEN        the user reports the system branch from the directory .
    THEN        the system branch is reported as master

However, if there's two system branches checked out below the
current directory, things should fail.

    SCENARIO    morph fails to report system branch with two checked out
    GIVEN       a workspace
    AND         a git server
    WHEN        the user checks out the system branch called master
    AND         the user creates a system branch called foo
    AND         the user attempts to report the system branch from the directory .
    THEN        morph failed

`morph show-branch-root` reports the URL (possibly aliases) of the
system branch root repository. It can be run inside a checkout, or
somewhere outside a checkout, where exactly one checkout exists below.

    SCENARIO    morph reports system branch root repository
    GIVEN       a workspace
    AND         a git server
    WHEN        the user checks out the system branch called master
    AND         the user reports the system branch root repository from the directory master
    THEN        the system branch root repository is reported as test:morphs

    WHEN        the user reports the system branch root repository from the directory .
    THEN        the system branch root repository is reported as test:morphs

However, it fails if run outside a checkout and there's no system
branches checked out.

    SCENARIO    morph fails to report system branch with none checked out
    GIVEN       a workspace
    AND         a git server
    WHEN        the user attempts to report the system branch root repository from the directory .
    THEN        morph failed

Editing components
------------------

`morph edit` can edit refs for a stratum only, or it can do that for
a chunk, and check out the chunk's repository.

First of all, we verify that that when we create a system branch,
all the refs are unchanged.

    SCENARIO    morph branch does not edit refs
    GIVEN       a workspace
    AND         a git server
    WHEN        the user creates a system branch called foo
    THEN        in branch foo, stratum strata/test-stratum.morph refs test-chunk in master

Edit the chunk. We make use of special knowledge here: `test:test-chunk`
is a chunk repository created in the mocked git server, for testing
purposes.

    WHEN the user edits the chunk test-chunk in branch foo
    THEN in branch foo, stratum strata/test-stratum.morph refs test-chunk in foo
    AND  the edited chunk test:test-chunk has git branch foo

Editing a morphology should not cause it to start having repo or ref
fields when referring to strata, when it didn't before.

    AND  in branch foo, system systems/test-system.morph refers to test-stratum without repo
    AND  in branch foo, system systems/test-system.morph refers to test-stratum without ref

Status of system branch checkout
--------------------------------

`morph status` shows the status of all git repositories in a
system branch checkout: only the ones that exist locally, not all the
repositories referenced in the system branch.

    SCENARIO    morph status reports changes correctly
    GIVEN       a workspace
    AND         a git server
    WHEN        the user creates a system branch called foo
    THEN        morph reports no outstanding changes in foo

    WHEN the user edits the chunk test-chunk in branch foo
    THEN morph reports changes in foo in test:morphs only

    WHEN        creating file foo in test/test-chunk in branch foo
    THEN        morph reports changes in foo in test:morphs only

    WHEN        adding file foo in test:test-chunk in branch foo to git
    THEN        morph reports changes in foo in test:morphs and test:test-chunk

    WHEN        committing changes in test:morphs in branch foo
    THEN        morph reports changes in foo in test:test-chunk only

    WHEN        committing changes in test:test-chunk in branch foo
    THEN        morph reports no outstanding changes in foo

`morph foreach`
--------------

`morph foreach` runs a shell command in each of the git repos in a system
branch checkout.

    SCENARIO morph foreach runs command in each git repo
    GIVEN a workspace
    AND   a git server
    WHEN  the user creates a system branch called foo
    AND   the user edits the chunk test-chunk in branch foo
    AND   running shell command in each repo in foo
    THEN  morph ran command in test/morphs in foo
    AND   morph ran command in test/test-chunk in foo

Explicit petrification
----------------------

We petrify branches explicitly (though this may later change so that
`morph branch` does it automatically). To test this, we create a branch,
petrify it, and verify that every ref looks like a SHA1. We then
unpetrify and verify that we have all the same refs as before.

    SCENARIO    morph petrifies and unpetrifies
    GIVEN       a workspace
    AND         a git server
    WHEN        the user creates a system branch called foo
    AND         the user pushes the system branch called foo to the git server
    AND         remembering all refs in foo
    AND         petrifying foo
    THEN        foo is petrified

Petrifying a morphology should not cause it to start having repo or ref
fields when referring to strata, when it didn't before.

    AND  in branch foo, system systems/test-system.morph refers to test-stratum without repo
    AND  in branch foo, system systems/test-system.morph refers to test-stratum without ref

Unpetrify must put the morphologies back in the same logical state they
were in before.

    WHEN        unpetrifying foo
    THEN        foo refs are as remembered

Unpetrifying a morphology should not cause it to start having repo or
ref fields when referring to strata, when it didn't before.

    AND  in branch foo, system systems/test-system.morph refers to test-stratum without repo
    AND  in branch foo, system systems/test-system.morph refers to test-stratum without ref

Generating a manifest works

    SCENARIO    morph generates a manifest
    GIVEN       a workspace
    AND         a system artifact
    WHEN        morph generates a manifest
    THEN        the manifest is generated