summaryrefslogtreecommitdiff
path: root/yarns/branches-workspaces.yarn
blob: 642beadd7768b697c6c77524e56f4ed19f741fcf (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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
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 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

Temporary Build Branch behaviour
--------------------------------

Morph always builds from committed changes, but it's not always convenient
to commit and push changes, so `morph build` can create temporary build
branches when necessary.

    SCENARIO morph makes temporary build branches for uncommitted changes when necessary
    GIVEN    a workspace
    AND      a git server
    WHEN     the user checks out the system branch called master

The user hasn't made any changes yet, so attempts to build require no
temporary build branches.

    GIVEN the workspace contains no temporary build branches
    AND   we can build with local branches
    WHEN  the user builds systems/test-system.morph of the master branch
    THEN  the morphs repository in the workspace for master has no temporary build branches

Similarly, if we need to build from pushed branches, such as when we're
distbuilding, we don't need temporary build branches yet, since we have
no local changes.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we must build from pushed branches
    WHEN  the user builds systems/test-system.morph of the master branch
    THEN  the morphs repository in the workspace for master has no temporary build branches
    AND   no temporary build branches were pushed to the morphs repository

If we actually want to be able to push our changes for review, we need to
use a different branch from master, since we require code to be reviewed
then merged, rather than pushing directly to master.

    WHEN the user creates a system branch called baserock/test

When we start making changes we do need temporary build branches, since
the chunk specifiers in the strata now need to refer to the local changes
to the repository.

    WHEN the user edits the chunk test-chunk in branch baserock/test

If we don't need to build from pushed branches then we have temporary
build branches only in the local clones of the repositories.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we can build with local branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   no temporary build branches were pushed to the morphs repository

If we do need to build from pushed changes, then the temporary build
branch needs to be pushed.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we must build from pushed branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   temporary build branches were pushed to the morphs repository

NOTE: We're not checking whether the test-chunk repo has changes since
it's currently an implementation detail that it does, but it would
be possible to build without a temporary build branch for the chunk
repository.

Now that we have the chunk repository available, we can make our changes.

    WHEN the user makes changes to test-chunk in branch baserock/test

When we have uncommitted changes to chunk repositories, we need
temporary build branches locally for local builds.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we can build with local branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has temporary build branches
    AND   no temporary build branches were pushed to the morphs repository
    AND   no temporary build branches were pushed to the test-chunk repository

As before, we also need temporary build branches to have been pushed

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we must build from pushed branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has temporary build branches
    AND   temporary build branches were pushed to the morphs repository
    AND   temporary build branches were pushed to the test-chunk repository

Now that we've made our changes, we can commit them.

    WHEN the user commits changes to morphs in branch baserock/test
    AND  the user commits changes to test-chunk in branch baserock/test

For local builds we should be able to use these committed changes,
provided the ref in the morphology matches the committed ref in the
chunk repository.

However, since we do not currently do this integrity check, as it requires
extra tracking between edited morphologies and the local repositories,
it's easier to just require a temporary build branch.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we can build with local branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has temporary build branches
    AND   no temporary build branches were pushed to the morphs repository
    AND   no temporary build branches were pushed to the test-chunk repository

For distributed building, it being committed locally is not sufficient,
as remote workers need to be able to access the changes, and dist-build
workers tunneling into the developer's machine and using those
repositories would be madness, so we require temporary build branches
to be pushed.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we must build from pushed branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has temporary build branches
    AND   temporary build branches were pushed to the morphs repository
    AND   temporary build branches were pushed to the test-chunk repository

We can now push our committed changes.

    WHEN the user pushes the system branch called baserock/test to the git server

We now don't need temporary build branches for local builds.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we can build with local branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has no temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has no temporary build branches
    AND   no temporary build branches were pushed to the morphs repository
    AND   no temporary build branches were pushed to the test-chunk repository

Nor do we need temporary build branches for distributed builds.

    GIVEN the workspace contains no temporary build branches
    AND   the git server contains no temporary build branches
    AND   we must build from pushed branches
    WHEN  the user builds systems/test-system.morph of the baserock/test branch
    THEN  the morphs repository in the workspace for baserock/test has no temporary build branches
    AND   the test-chunk repository in the workspace for baserock/test has no temporary build branches
    AND   no temporary build branches were pushed to the morphs repository
    AND   no temporary build branches were pushed to the test-chunk repository

    IMPLEMENTS WHEN the user makes changes to test-chunk in branch (\S+)
    chunkdir="$(slashify_colons "test:test-chunk")"
    cd "$DATADIR/workspace/$MATCH_1/$chunkdir"
    sed -i -e 's/Hello/Goodbye/g' test-bin

    IMPLEMENTS WHEN the user commits changes to (\S+) in branch (\S+)
    chunkdir="$(slashify_colons "test:$MATCH_1")"
    cd "$DATADIR/workspace/$MATCH_2/$chunkdir"
    git commit -a -m 'Commit local changes'
    

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