forked from UoMCS/softeng
-
Notifications
You must be signed in to change notification settings - Fork 0
/
softeng.Rmd
6279 lines (3590 loc) · 532 KB
/
softeng.Rmd
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
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: "Software engineering"
author: Suzanne Embury and the software engineering team. The text of this guidebook is licensed CC-BY-NC-ND and was last updated on `r format(Sys.time(), '%d %B, %Y')`
site: bookdown::bookdown_site
documentclass: book
bibliography: [software-engineering.bib]
biblio-style: apalike
link-citations: yes
description: "Second year software engineering course at the University of Manchester"
url: 'https\://software-eng.netlify.app/'
github-repo: dullhunk/softeng
twitter-handle: csmcr
# added via R4DS
knit: "bookdown::render_book"
#always-allow-html: yes
always_allow_html: true
# output: word_document
---
# Welcome {.unnumbered #welcome}
Welcome to (ref:coursecode): [software engineering at the University of Manchester](https://studentnet.cs.manchester.ac.uk/ugt/COMP23311/syllabus/).
<!-- this is the main branch-->
## Making better software {#better}
The development of software systems is a challenging process. Customers expect reliable and easy to use software to be developed within a set budget and to a tight deadline. As we come to depend upon software in so many aspects of our lives, its increasing size and complexity, together with more demanding users, means the consequences of failure are increasingly severe. The stakes for today’s software engineers are high!
```{r course-overview-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "(ref:openingcaption)"}
knitr::include_graphics("images/course-overview.png")
```
(ref:openingcaption) Course unit roadmap. This twelve week course will take you from small scale code changes (shown in grey), through to working with features (shown in orange) and on to larger-scale change (shown in yellow). We finish with an open source challenge in chapter \@ref(opening). The skills you will develop on this course are fundamental to modern software engineering.
Experience over the last few decades has taught us that software development failures are rarely caused by small scale coding problems. Instead, failures result from the difficulties of writing software that customers actually need, of keeping up with constantly changing requirements, of coping with the scale of large developments, of getting many different people with very different skill sets to work together, and of working with large bodies of existing code that no one on your team may fully understand. Being a good coder is an important part of being a good software engineer, but there are many other skills - including soft skills - that are needed too.
In this course unit, you will get the chance to expand and broaden the programming skills you gained in your first year course units by applying them in a more realistic context than is possible in a small scale lab, see figure \@ref(fig:course-overview-fig). Instead of coding from scratch, you will be working in a team to make changes to a large open source software system, consisting of thousands of classes and tens of thousands of files - and all without breaking the existing functionality.
You will fix bugs in the codebase and add new features, as well as performing larger scale refactorings to maintain or improve on non-functionality properties of the system. You will perform all this using an industry strength tool set. We will complement the hands-on experience-based learning with an understanding of the core concepts underlying current notions of software engineering best practice. Volunteer mentors from industry (see chapter \@ref(ourmentor)) will help you to put your learning into context, and to understand the key importance of being not just a good coder, but a good software engineer.
This course unit detail provides the framework for delivery in 20/21 and may be subject to change due to any additional Covid-19 impact. Please see Blackboard / course unit related emails for any further updates.
## Aims {#bilo}
This unit aims to help students appreciate the reality of team-based software development in an industrial environment, with customer needs, budget constraints and delivery schedules to be met. Through hands-on experience with an industry-strength development toolkit applied to a large open source software system, students will gain an appreciation of the challenges of green and brownfield software development, along with an understanding of the core software engineering concepts that underpin current best practice. Students will have the core skill set needed by a practicing software engineer, and will be ready to become productive and valuable members of any modern software team.
### Learning outcomes
On successful completion of this unit, a student will be able to:
* make use of industry standard tools for version management, issue tracking, automated build, unit testing, code quality management, code review and continuous integration.
* write unit tests to reveal a bug or describe a new feature to be added to a system, using a test-first coding approach.
* explain the value of code reviews, and to write constructive and helpful reviews of code written by others.
* make use of basic Git workflows to coordinate parallel development on a code base and to maintain the quality of code scheduled for release.
* explain the role of software patterns (design and architectural) in creating large code bases that will be maintainable over the long term.
* explain why code that is easy to test is easy to maintain, and make use of test code smells in identifying and correcting design flaws (design for testability)
* apply basic software refactorings to maintain or improve code quality
* explain the challenges inherent in cost estimation for software development, and create defensible estimates with the help of work breakdown structures
<!--codebase, documentbase, languagebase, wordbase-->
## Recommended reading {#recread}
The following books are recommended course texts, they are all available from the University of Manchester library if you clickthrough to the references:
1. [Pro Git](https://git-scm.com/book/en/v2) [@progit]
1. The pragmatic programmer : from journeyman to master [@pragmatic]
1. Effective unit testing : a guide for Java developers [@unittesting]
1. Clean code : a handbook of agile software craftsmanship [@cleancode]
1. The clean coder : a code of conduct for professional programmers [@cleancoder]
1. Beginning software engineering [@beginning]
These and any other references cited are listed in chapter \@ref(reading).
### Requirements {#prereq}
The compulsory pre-requisites for this course are the first year programming units:
1. [COMP16321: Programming 1](https://studentnet.cs.manchester.ac.uk/ugt/COMP16321/syllabus/)
1. [COMP16412: Programming 2](https://studentnet.cs.manchester.ac.uk/ugt/COMP16412/syllabus/)
### Overview of course {#courseo}
The following is an outline of the topics covered in COMP23111.
* Team software development
* Software project planning and issue tracking
* Greenfield vs brownfield software development
* Git best practices and common Git workflows
* Automated build tools and release management
* Automated unit, integration and acceptance testing
* Test code quality and test coverage tools
* Continuous integration and testing tools
* Best practices and tool support for code review, including source code quality tools
* Design patterns and common architectural patterns
* Design for testability
* Refactoring for code quality
* Safely migrating software functionality
* Basic risk management techniques
* Working with open source software systems
## Using the lab manual {#usingit}
We expect that the web-based version of this manual will be the one you'll use most at [software-eng.netlify.app](https://software-eng.netlify.app/). You can search, browse and link to anything in the manual. It was last updated on `r format(Sys.time(), '%d %B, %Y')`.
<!--However, if you'd prefer, the manual is also available as a single pdf file [softeng.pdf](https://software-eng.netlify.app/softeng.pdf) and an epub as well [softeng.epub](https://software-eng.netlify.app/softeng.epub). Having said that, the content is optimised for viewing in a web browser, so while the pdf and epub are OK, the web version is the best.-->
## Contributing to this manual {#contributing}
If you'd like to contribute this laboratory manual, we welcome constructive feedback. Once you're familiar with git and markdown you can [github.com/join](https://github.com/join) and:
* Raise new issues at [github.com/UoMCS/softeng/issues/new](https://github.com/UoMCS/softeng/issues/new)
* Click on the `Edit this page` link, which appears on the bottom right hand side of every page published at [software-eng.netlify.app](https://software-eng.netlify.app) when viewed with a reasonably large screen (not a phone)
* Contribute at [github.com/UoMCS/softeng/contribute](https://github.com/UoMCS/softeng/contribute) and help with existing issues at [github.com/UoMCS/softeng/issues](https://github.com/UoMCS/softeng/issues)
* Fork the repository, make changes and submit a pull request [github.com/UoMCS/softeng/pulls](https://github.com/UoMCS/softeng/pulls). If you need to brush-up on your pulling skills see [makeapullrequest.com](http://makeapullrequest.com/)
* From the command line, clone the repository and submit pull requests from your own setup:
````md
git clone https://github.com/UoMCS/softeng.git
````
Most of the guidebook is generated from [RMarkdown](https://en.wikipedia.org/wiki/Markdown), that's [all the `*.Rmd` files](https://github.com/UoMCS/softeng/search?l=RMarkdown). So markdown files are the only ones you should need to edit because everything else is generated from them including the `*.html` <!--`*.tex`, `*.pdf` and `*.epub`--> files.
## Acknowledgements {#teambury}
This course has been designed, built and written by [Suzanne Embury](http://www.cs.man.ac.uk/~embury/) at the University of Manchester with support from a team of academics, industry club members, support staff, graduate teaching assistants (GTAs) and summer students including (in alphabetical order):
Muideen Ajagbe, Mohammed Alhamadi, Aitor Apaolaza, Mercedes Argüello Casteleiro, Gerard Capes, Martina Catizone, Sarah Clinch, Peter Crowther, Anas Elhag Sukru Eraslan, Gareth Henshall, Duncan Hull, Caroline Jay, Nikolaos Konstantinou, Kamilla Kopec-Harding, Kaspar Matas, Chris Page, Dario Panada, Steve Pettifer, Liam Pringle, Julio Cesar Cortes Rios, Sara Padilla Romero, Viktor Schlegel, Stefan Strat, Sandra Sampaio, Jake Saunders, Federico Tavella, Mokanarangan Thayaparan, David Toluhi, Karl Tye, Jonas Verbickas and Markel Vigo.
Academic staff on the course for 2022/23 include:
* [Thomas Carroll](https://personalpages.manchester.ac.uk/staff/thomas.carroll/)
* [Suzanne Embury](http://www.cs.man.ac.uk/~embury/)
* [Duncan Hull](https://personalpages.manchester.ac.uk/staff/duncan.hull/)
* [Liping Zhao](https://www.research.manchester.ac.uk/portal/liping.zhao.html)
We'd also like to thank all the 2,000+ students who have done the course since its first iteration in 2016 and given us feedback on how to improve.
<!--2016, two cohorts of 250 = 500 plus 250 cohorts in 2017, 2018, 2019 and 2020-->
Thanks also to our [industrial mentors](https://www.cs.manchester.ac.uk/connect/business-engagement/industrial-mentoring/), the Institute of Coding (IoC) [instituteofcoding.org](https://instituteofcoding.org/) and the [Office for Students](https://www.officeforstudents.org.uk/) (OFS) for their ongoing support.
## Licensing {#license}
The *text* of this lab manual is published under the [Creative Commons Attribution-NonCommercial-NoDerivs 3.0 License](https://creativecommons.org/licenses/by-nc-nd/3.0/) (CC-BY-NC-ND) license see figure \@ref(fig:cc-by-nc-nd-fig)
```{r cc-by-nc-nd-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "(ref:captionccbyncnd)"}
knitr::include_graphics("images/by-nc-nd.png")
```
(ref:captionccbyncnd) The *text* of this guidebook is published under a [Creative Commons Attribution-NonCommercial-NoDerivs 3.0 License](https://creativecommons.org/licenses/by-nc-nd/3.0/) (CC-BY-NC-ND) license which means you can copy and redistribute the material provided that you provide full attribution, do not use the material for commercial purposes and you do not make any derivative works.
This license means you can copy and redistribute the written material provided that:
* You provide full attribution by linking directly to the original source
* You do not use the material for commercial purposes
* You do not make any derivative works
See the [full license](https://creativecommons.org/licenses/by-nc-nd/3.0/) (CC-BY-NC-ND) for details.
### Your privacy {#privacy}
This site is hosted on [netlify.com](https://www.netlify.com/), see the [netlify privacy policy](https://www.netlify.com/privacy/). This site also uses [Plausible Analytics](https://plausible.io/) to understand our audience better which is compliant with the General Data Protection Regulation (GDPR).
So now that we've dispensed with the formalities, you can start using this laboratory manual.
<!--boilerplate text and constants that gets re-used throughout-->
(ref:ideversion) `2020-03`
(ref:commit-were-using) `5450a33`
(ref:commit-message) `Organize imports`
(ref:repoURI) [https://gitlab.cs.man.ac.uk/COMP23311_2022/sliding_puzzle_<your-username>.git](https://gitlab.cs.man.ac.uk/COMP23311_2022/sliding_puzzle-your-username.git)
(ref:repo2URI) [https://gitlab.cs.man.ac.uk/COMP23311_2022/sliding_puzzle2_<your-username>.git](https://gitlab.cs.man.ac.uk/COMP23311_2022/sliding_puzzle2-your-username.git)
(ref:coursecode) COMP23311
<!-- todo update hanbook urls e.g. UGHandbook21:Academic_Malpractice to UGHandbook22:Academic_Malpractice etc-->
<!--
23311-TeamCwk1-S-Fixing Bugs 120 40
23311-TeamCwk2-S-Adding Features 120 40
23311-IndCwk1-S-Basic Git 10 10
23311-IndCwk2-S-Conflicts in Git 10 10
-->
(ref:infobox) ℹ️ **Note** ℹ️
(ref:cautionbox) ⚠️ **Caution** ⚠️
(ref:commentbox) **`#Comment`**
(ref:anotherref) here
<!-- Configuration for the exercise -->
(ref:totalmark) 10
(ref:percentage) 7
(ref:deadline) 6.00pm, Friday 7th October 2022
(ref:deadline2) 6.00pm, Friday 21st October 2022
(ref:feedbackdateindicwk2) 6.00pm, Friday 14th October 2022
(ref:numsteps) 9
(ref:piazzaforum) [piazza.com/class/l7j4na2gfwn2q8](https://piazza.com/class/l7j4na2gfwn2q8)
(ref:livehelpqueue) [gitlab.cs.man.ac.uk/comp23311_2022/COMP23311-Live-Help-Queue](https://gitlab.cs.man.ac.uk/comp23311_2022/COMP23311-Live-Help-Queue/)
(ref:mentors) Airbus, Airnode, Alphabet (Google), AND Digital, Apadmi, Apple, ARM, Auto Trader UK, Barclays, the BBC, Bet365, Beyond Trust, Biorelate, BJSS, Blaize, Bloomberg, Booking.com, Brightec, CERN, CDL Software, Codat, CodeThink, Code Computer Love, Cognizant, Couchbase, Cubic Motion (now Epic Games), DAI, DataCentred, Digital Bridge Ltd, Disney Streaming, EGN Digital, Farm Digital, Giant Digital, Goldman Sachs, IBM, Interact Software, Ivanti, Koder.ly, Matillion, MediaTek, Meta (Facebook), Microsoft, Moonpig, Morgan Stanley, Nandos, NCC Group, On The Beach, Peak.ai, Rental Cars, Sainsburys, Sage Group plc, Shout Platform Limited, Siemens (Mentor Graphics), SKY, Slalom, Spotify, SteamaCo, The Startup Factory, THG, ThoughtWorks, Tranzfar, UK Parliament, UL, Unipart Digital and Zuhlke.
<!--chapter:end:index.Rmd-->
# Expectations {.unnumbered #expectations}
While you are studying on this software engineering course, you are part of a team and a wider community:
* Your immediate team members
* The community of all second year students
Your learning community is supported by a group of graduate teaching assistants (GTAs), mentors and academic staff.
## Expectation engineering {#agile}
It's important that you know what we expect of you and what you'll get in return. That's what this page describes.
```{r xkcd-compiling-fig, echo = FALSE, fig.align = "center", out.width = "75%", fig.cap = "(ref:captionxkcdcompiling)"}
knitr::include_graphics("images/compiling.png")
```
(ref:captionxkcdcompiling) There are legitimate reasons for slacking off, such as compiling (and building) your code. Falling out with your team members, not returning their messages or just being busy doing other things are not legitimate reasons for letting your team down. [Compiling (xkcd.com/303)](https://xkcd.com/303/) by [Randall Munroe](https://en.wikipedia.org/wiki/Randall_Munroe) is licensed under [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/)
### Our expectations of you {#rtfm}
We need you to read ALL of the messages we send you via GitLab, Jenkins, Microsoft Teams, the Piazza forum, emails and in this guidebook. Before you ask for help, make sure you have Read The Friendly Manual(s). [RTFM](https://en.wikipedia.org/wiki/RTFM).
#### Getting help {#helpme}
Regardless of if you are attending live (in person) or remotely (online, login to Teams) the mechanism for getting help is the same, please don't send academic staff personal email or private messages on teams. Instead:
For live sessions (timetabled), team study and workshops you need to use the issue tracker:
* (ref:livehelpqueue)
*Outside* of live sessions use the piazza discussion board:
* (ref:piazzaforum)
Please note:
* During Team study sessions: we can discuss and help with coursework
* During Workshops: we will support workshop content only, **NO COURSEWORK** questions
Use the issue tracker in gitlab, rather than email, to manage communication in your team about your repository.
You can use whatever combination of OS and IDE you like but we can **only provide support** for students using Eclipse (ref:ideversion) on an Ubuntu Linux machine in the Kilburn building. We do not have the resources to test and support the myriad combinations of OS and IDE. Sorry!
#### Workshops vs. Team study {#workshops}
There are two main sessions:
1. Team study sessions
1. Workshops
Team study sessions are for you to get together as a team to work alongside each other. You can also get help from GTAs and staff on coursework. **Every team member** should be attending **every team study session**, you may also need to arrange to meet outside of the scheduled sessions so that you can collaborate together.
Each workshop has a specific theme that we need you to focus on. This means **we won't discuss coursework with you during the workshops**, otherwise we risk not getting through workshop material.
#### Physical vs online sessions {#online}
For the live (physical) sessions you'll need to be in the appropriate lab in the Kilburn building. For online sessions (e.g. some marking and mentoring) it is especially important that you turn up on time by being at a computer with access to:
* A working pair of headphones
* A working microphone that you can mute if you're somewhere noisy
* A webcam (ideally) but see section \@ref(cameras)
Please note, this may mean the best place to work is *not* necessarily the Kilburn building. Go and find a quiet spot, use your laptop (if you have one) or use your phone (there are [good mobile clients for Teams](https://www.microsoft.com/en-gb/microsoft-teams/download-app)) or work from home. It will really help if *at least* one of your team is at a desktop computer.
We have deliberately scheduled online activities so they aren't immediately after physical activities (like a lecture) so that you have time to get setup BEFORE the meeting starts.
### What your team expects of you {#urteam}
For this course to run smoothly your team will expect that you:
* Turn up to all the bi-weekly team study sessions, **especially the marking sessions**
* Participate in the all workshops
* Contribute to your team by:
+ Respecting your team members, no bullying. Assume good faith by default. It's your responsibility to make your team work. Team work makes the dream work.
+ Getting along with your team members. You may not like all of them (that's life) but your team members are crucial to your teams success. While you can get away with being a “lone wolf” coder on other course units, (see figure \@ref(fig:wolf-fig)), you are now expected to behave like a sociable engineer as part of a professional team
+ Encouraging people who might be slacking off to make contributions, see figure \@ref(fig:xkcd-compiling-fig)
+ Communicating with your team if you have difficulty contributing
+ Reporting issues where necessary, either to a GTA or academic member of staff
```{r wolf-fig, echo = FALSE, fig.align = "center", out.width = "99%", fig.cap = "(ref:captionlonewolf)"}
knitr::include_graphics("images/lonewolf.jpeg")
```
(ref:captionlonewolf) Normally a social pack animal, wolves sometimes act alone. While being a [lone wolf](https://en.wikipedia.org/wiki/Lone_wolf_(trait)) on other course units may be a reasonable strategy for studying, it won't work well for this one. Don't be a lone wolf because sociable teams usually make better software than loners. CC-BY-SA Image of Winter wolf by ForestWander.com on Wikimedia Commons [w.wiki/45Vj](https://w.wiki/45Vj)
What do you get in return for our expectations and those of your team?
### What to expect of GTAs {#gtas}
This course is supported by a team of Graduate Teaching Assistants (GTAs), they are here to help you. They have lots of other people to help too, so please treat them with respect. If you're waiting for support from a GTA, make sure you've Read The Friendly Manual, see section \@ref(rtfm).
Our GTAs have Read Their Friendly Manual to (the GTA wiki) so they will know how to help you, or can quickly find out how to. They won't give you the answer, but will be able to help you find your own way.
::: {.rmdcaution}
(ref:cautionbox)
The GTAs have scheduled marking sessions that we expect them to stick to. The second year timetable is incredibly crowded, and the team study sessions are the **ONLY TIMES IN THE WEEK** when we can guarantee that everyone in your team is available.
:::
### What to expect from mentors {#gomentors}
You have been assigned a mentor who will meet with you online for two one hour meetings, see chapter \@ref(mentoring). These meetings are a bit like code review meetings, they have access to your private code repository and can see what your team is up to.
Our mentors are all professional software engineers, who can give you advice on how to manage the process of making better software. so please treat them with the respect they deserve. They have volunteered to help by sharing their engineering wisdom with you and taken time out of their busy schedules to do so.
### What you can expect from academic staff {#academics}
The academic staff on this course include Suzanne Embury, Anas Elhag, Duncan Hull, Thomas Carroll and Sandra Sampaio. We're here to help but please remember, there are 400+ students on this course so we can't reply to every single personal email immediately.
::: {.rmdcaution}
(ref:cautionbox)
Please **don't email staff or GTAs** directly unless you have good reason too (e.g. personal issues).
Instead, please post issues on the forum at (ref:piazzaforum) where *everyone* can see the response or in the help queue (ref:livehelpqueue) within the workshop / team study sessions.
:::
Like you, we're often very busy and have other teaching (and research) commitments besides this course. We're here to ensure that the course runs smoothly and we aim to give feedback on coursework to you within the two week window.
### How your work gets assessed {#assessment}
The course is:
* 30% Written exam (in January)
* 70% Practical skills assessment (coursework)
The coursework is broken down as follows
1. 10%: Individual coursework 1, see chapter \@ref(gitting)
1. 10%: Individual coursework 2, see chapter \@ref(conflicting)
1. 40%: Team coursework 1, see chapter \@ref(dealing)
1. 40%: Team coursework 2, see chapter \@ref(working)
## Your camera {#cameras}
We would normally expect participants in small meetings (not large ones like lectures) to turn their cameras on but we understand that there are good reasons why people may not be willing/able to and won’t explicitly ask you to.
### Camera on? {#on}
There has always been a question around whether to turn cameras on during online meetings but it is even more obvious with online meetings becoming the norm rather than the exception. There is a direct benefit in using cameras in small, personal meetings where many of us make use of visual cues to aid the flow of conversation – at the very least it’s easier to identify who is talking. Additionally, it can help people get along – people might feel more ‘listened to’ if they can see somebody listening and your team will find it easier to remember names etc if they have a face to match the names to.
### Camera off? #{#off}
There are lots of legitimate reasons why you might turn your camera off. Most obviously, if you don’t have access to a camera. But you may also be in an environment which you prefer others not to see, you may have anxiety around the issue, or your connection might be too slow. There are many other perfectly reasonable reasons for you not to put your camera on and you should not feel pressured to do this. If you simply say “Sorry, I can’t turn my camera on today” then nobody will ask any further and they should never explicitly ask you to turn it on.
### Being appropriate {#being}
You should already be treating online meetings like physical ones e.g. turning up on time, being prepared, listening, engaging etc. Similarly, if people can see you then you should ensure you are wearing appropriate clothes (wearing clothes is the absolute minimum here!) and in an appropriate place (the bathroom is probably not appropriate) as you would for a physical meeting.
### Respecting others {#respecting}
If other people have decided to turn their cameras on then we ask that you show them respect by not recording anything without their explicit permission. We won’t touch on the legality of this as we believe that basic respect for each other should be enough to prevent any issues. You will take part in larger meetings where recording may be standard and in such cases this should be made explicit.
(Thanks to Giles Reger and Sarah Clinch for the text above)
<!--chapter:end:001-expectations.Rmd-->
# Weekly timetable {.unnumbered #timetabling}
The weekly schedule for autumn 2022 is shown in table \@ref(tab:schedtable), based on [timetables.manchester.ac.uk](https://timetables.manchester.ac.uk/), see also [manchester.ac.uk/discover/key-dates](https://www.manchester.ac.uk/discover/key-dates/) key dates.
* Other than the introductory lecture in week 1, there are no lectures. Instead we have workshops which are more like labs and may contain mini-lectures
* Workshops are on Wednesdays at 9am and Thursdays at 2pm / 3pm depending on your lab group
<!--* [bit.ly/Tuesday-3pm-workshop](http://bit.ly/Tuesday-3pm-workshop)
* [bit.ly/Tuesday-4pm-workshop](http://bit.ly/Tuesday-4pm-workshop)
* [bit.ly/friday-1pm-workshop](http://bit.ly/friday-1pm-workshop)-->
* Team study sessions are on Tuesdays and Thursdays at 10am.
For online activities, everything is on Microsoft Teams.
<!--Because of constraints on the number of private channels in Teams, the year is arbitrarily split into two spaces:
1. [bit.ly/software-engineering-A](https://bit.ly/software-engineering-A)
1. [bit.ly/software-engineering-b](https://bit.ly/software-engineering-b)-->
Microsoft Teams is, as the name suggests, where you'll meet your team, details will appear here once teams have been assigned.
## Which lab should I go to {#campus}
You need to meet with your team in the team study sessions, these are assigned in week 1.
<!--
* **Teams 1-30**: 1.8 & 1.10
* **Teams 31-44**: LF31
* **Teams 44-56**: Tootill-->
The weekly schedule is shown in \@ref(tab:schedtable).
```{r schedtable, echo = FALSE}
io_table <- tibble::tribble(
~ "Week no." , ~ "Subject", ~ "Deadlines",
"**1**: 26th Sept" , "Automated build and test, see (ref:weekone)", "",
"**2**: 3rd Oct" , "Reading large codebases, see (ref:weektwo)", "IndCwk1, Fri 7th Oct, 6pm",
"**3**: 10th Oct" , "Debugging, see (ref:weekthree)", "",
"**4**: 17th Oct" , "Cost estimation, see (ref:weekfour)", "Mentoring week 1, IndCwk2, Fri 21st Oct, 6pm",
"**5**: 24th Oct" , "Test first development, see (ref:weekfive)", "TeamCwk1, 28th Oct, 6pm",
"**6**: 31st Oct" , "Reading week see (ref:weeksix)", "",
"**7**: 7th Nov" , "Git workflows, see (ref:weekseven)", "",
"**8**: 14th Nov" , "Software refactoring, see (ref:weekeight)", "Mentoring week 2",
"**9**: 21st Nov" , "Design for testability, see (ref:weeknine)", "",
"**10**: 28th Nov" , "Design patterns, see (ref:weekten)", "TeamCwk2, 5th Dec, 6pm",
"**11**: 5th Dec" , "Risk management and practice exam, see (ref:weekeleven)", "",
"**12**: 12th Dec" , "Open source challenge, see (ref:weektwelve)", "",
)
knitr::kable(io_table, caption = "The weekly schedule for this twelve week course, please note we are using the week numbering from the [timetables.manchester.ac.uk](https://timetables.manchester.ac.uk/) where week zero is welcome week, and week one is the first teaching week", booktabs = TRUE)
```
## Automating {#week1}
Events in the week starting 26th September:
1. **Team Study Tuesday**: Work on individual coursework 1 described in chapter \@ref(gitting)
1. **One off lecture** to introduce the course unit at 3pm on Friday 30th September, Lecture Theatre A, Engineering Building A [timetables.manchester.ac.uk](https://timetables.manchester.ac.uk/)
1. **Workshop**: Automated build and test with Duncan Hull
1. **Team Study Thursday** Work on individual coursework 1 described in chapter \@ref(gitting)
<!--1. **Coursework deadlines**: Individual individual coursework 1 can be pre-marked (automatically) if you submit by **6pm Tuesday 28th September** and finally marked when submitted by **6pm on Friday 1st October**-->
## Reading {#week2}
Events in the week starting 3rd October:
1. **Team Study Tuesday**: Individual coursework 2 starts, see chapter \@ref(conflicting). Meet your team on Teams
1. **Workshop**: Reading large code bases with Thomas Carroll
1. **Team Study Thursday** Working on coursework
1. **Coursework deadlines**: Individual coursework 1
## Debugging {#week3}
Events in the week starting 10th October:
1. **Team Study Tuesday**: Working on team coursework
1. **Workshop**: Debugging codebases with Thomas Caroll
1. **Team Study Thursday** Working on team coursework
1. **Coursework deadlines**: see blackboard
## Estimating {#week4}
Events in the week starting 17th October:
1. **Team Study Tuesday**: Working on team coursework
1. **Workshop**: Cost estimation with Duncan Hull
1. **Team Study Thursday** Meet your team mentor on Teams
## Testing {#week5}
Events in the week starting 24th October:
1. **Team Study Tuesday**: Working on team coursework
1. **Workshop**: Test first development with Thomas Carroll
1. **Team Study Thursday** Working on team coursework
1. **Coursework deadlines**: TeamCwk1 due
## Pausing {#week6}
Events in the week starting 1st November (reading week). Take a break if you're ahead, or catchup if you've fallen behind.
1. There are no activities in reading week
## Workflowing {#week7}
Events in the week starting 7th November:
1. **Team Study Tuesday**: Team study
1. **Workshop**: Git workflows with Suzanne Embury
1. **Team Study Thursday** Team study
## Refactoring {#week8}
Events in the week starting 14th November:
1. **Team Study Tuesday**: Team study
1. **Workshop**: Refactoring with Thomas Carroll
1. **Team Study Thursday** Second mentoring session
## Testing {#week9}
Events in the week starting 21st November:
1. **Team Study Tuesday**: Working on team coursework
1. **Workshop**: Design for testability Thomas Carroll
1. **Team Study Thursday** Working on team coursework
## Patterning {#week10}
Events in the week starting 28th November:
1. **Team Study Tuesday**: Working on team coursework
1. **Workshop**: Design patterns with Liping Zhao
1. **Team Study Thursday** Working on team coursework
1. **Coursework deadlines**: TeamCwk2 due end of the week
## Managing {#week11}
Events in the week starting 5th December:
1. **Team Study Tuesday**: Marking sessions
1. **Workshop**: Risk management and practice exam with Liping Zhao
1. **Team Study Thursday** Marking sessions
## Challenging {#week12}
Events in the week starting 12th December:
1. **Team Study Tuesday**: Marking sessions
1. **Workshop**: Open source challenge with Liping Zhao
1. **Team Study Thursday**
1. **Coursework deadlines**:
## Tools {#tooling}
We'll be using the following tools:
### Microsoft Teams {#msfteams}
* Team study sessions take place on Microsoft Teams, login using your `@student.manchester.ac.uk` email address at [teams.microsoft.com](https://teams.microsoft.com/) or [download a native teams client](https://www.microsoft.com/en-gb/microsoft-teams/download-app) everthing else is in the guidebook at [software-eng.netlify.app/](https://software-eng.netlify.app/)
* Teams is also the place to go for livestream if you're following the workshops online
### Blackboard {#blackboard}
* Other course materials (slides and videos) can be found on at [online.manchester.ac.uk](https://online.manchester.ac.uk/)
### GitLab {#gitlab}
* GitLab issue tracker [gitlab.cs.man.ac.uk](https://gitlab.cs.man.ac.uk/)
<!--hacky way to get chapter references in tables-->
(ref:weekone) see section \@ref(week1)
(ref:weektwo) see section \@ref(week2)
(ref:weekthree) see section \@ref(week3)
(ref:weekfour) see section \@ref(week4)
(ref:weekfive) see section \@ref(week5)
(ref:weeksix) see section \@ref(week6)
(ref:weekseven) see section \@ref(week7)
(ref:weekeight) see section \@ref(week8)
(ref:weeknine) see section \@ref(week9)
(ref:weekten) see section \@ref(week10)
(ref:weekeleven) see section \@ref(week11)
(ref:weektwelve) see section \@ref(week12)
<!--chapter:end:002-timetabling.Rmd-->
# (PART) Weekly Workshops {-}
# Building and testing {#building}
## Introduction {#Introduction}
In this workshop, we will be building and testing a system called Marauroa. We will look at some essential processes for working on an existing team-developed software system. We'll be assuming that, after this workshop, you are capable of carrying out the following tasks for yourself, without needing much guidance:
* Acquire the right version of the source code on which to work.
* Create an executable version of the source code using an automated build tool.
* Test the system, prior to making changes.
* Use a test suite to find functional regression in the system.
* Run a piece of software consisting of multiple distributed subsystems.
In this, and some later workshops, we'll be working with the code of the *Marauroa games engine* for constructing online multi-player games.
Marauroa is an open-source *framework* and engine for developing games. It provides a simple way of creating games on a portable and robust server architecture. Marauroa manages client-server communication and provides an object-orientated view of the world for game developers. It further handles database access in a transparent way to store player accounts, character progress and the state of the world.
You should already have begun to practice some of these skills, through the GitLab Access Check activity.
In this workshop, we will build on that activity to carry out these basic skills on a large open-source software system. During the workshop, you will:
1. Use an IDE to clone a local copy of the Marauroa repository.
1. Build executable versions of the client and server components, using the Ant build tool.
1. Run the test suite provided for Marauroa
1. Use a code coverage tool to assess the strength of the test suite.
1. See how the test suite can help us pinpoint errors in the code.
You may work at your own pace, but you should try to complete step 4 by the end of the workshop if you can. You will need to finish the exercise in your own time if you don't manage it in the workshop, as you'll need to use these techniques for the team coursework. **If you are not up-to-speed with them, then you could slow your team down.**
## Acquiring Marauroa {#acquiring}
First, you'll need to acquire a local copy of the Marauroa Project.
### Run the IDE {#runide}
The Department provides a range of Integrated Development Environments (IDEs) for use by students. You are welcome to use any of these IDEs to carry out the work for this workshop. However, we are only able to provide technical support for Eclipse, specifically (ref:ideversion). If you do want to use one of the other IDEs, we will do our best to help should you get stuck, but we can't guarantee to be able to fix all problems. At the bare minimum, you should feel confident that you can do all the tasks listed in the introduction in your chosen IDE before you finalise the decision.
The instructions that follow assume you are using (ref:ideversion) the Department of Computer Science Linux image or the Linux Mint VM provided by the Department.
You can start Eclipse from the Applications menu (under Programming) or the command line, by issuing the command:
````md
/opt/eclipse-2020-03/eclipse &
````
### Select the Workspace {#selectw}
Eclipse calls a folder containing one or more Eclipse projects a `workspace`. At start-up, Eclipse will ask you which workspace you want to use for the session. You can either accept the default location or use the File Browser to locate or create a different one. A sensible standard location is something like:
~/EclipseWorkspace
If you choose to create a new workspace, Eclipse will show the Welcome View when it loads. Uncheck the box at the bottom right of the window (labelled `Always show Welcome on start up`) and close it down, as we do not need this view for this workshop. (You can get it back whenever you want by selecting the `Welcome` option from the `Help` menu.)
### Organise Workspace {#organisew}
You'll need to organise your main Eclipse workspace window and you should now see a window that looks something like figure \@ref(fig:firstview-fig).
```{r firstview-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Your main eclipse window should look something like this"}
knitr::include_graphics("images/1.3.2firstView.png")
```
If you used the same workspace you created for the individual coursework exercises, you'll see the project for that in the Package Explorer view. If you used a new workspace, it will be empty like the one shown above.
This is the standard layout for working on Java projects. The central empty space is where we will use the various Eclipse editor tools and views to work on individual files. It is empty at the moment, as we are not working on any specific file. Around it are a number of other views. We'll talk about the main ones and what they tell us later.
I find this screen rather cluttered, and would immediately delete all the views I don't need regularly, to free up space for the ones I do, and move the views I do use to more convenient locations. You might want to do the same. You can experiment with moving the views around by clicking and dragging on their tabs. Delete any views you don't think you'll need, but **make sure you keep the Package Explorer view, the Outline view and the Problems view open**, as we'll be making use of those very soon.
Note that you can always get any views you delete back again, using the `Window` > `Show View` menu option.
### Create a New Project by Cloning {#newproj}
Next, we're going to pull down (git clone) the public Marauroa source code into a local repository where we can work on it. You've already had experience working with Git from the command line. In this course unit, we ask you to use your IDE for (at least) your basic interactions with Git and GitLab. This will help you to understand the strengths and weaknesses of both approaches if you are not already familiar with them.
The first step is to ask Eclipse to import the Marauroa project for us, from a public Git repository.
Select the `File` > `Import` menu option. Then choose `Git` > `ImportFromGit` shown in figure \@ref(fig:eclipseImportProjectFromGit-fig)
```{r eclipseImportProjectFromGit-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Your main eclipse window should look something like this"}
knitr::include_graphics("images/1.4.eclipseImportProjectFromGit.png")
```
You can either double-click on `Projects from Git`, or single-click on it and press `Next`.
A dialogue box appears showing the two ways in which you can import a project from Git. We're going to **clone a project from a URI**, so select that option shown in figure \@ref(fig:eclipseCloneFromURI-fig)
```{r eclipseCloneFromURI-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Your main eclipse window should look something like this"}
knitr::include_graphics("images/1.4.eclipseCloneFromURI.png")
```
Next, we need to tell Eclipse which URI to clone from. The team behind Marauroa have set up their own Git server, which we'll connect to anonymously. Enter the following into the URI field:
````md
git://git.code.sf.net/p/arianne/marauroa
````
Eclipse **Should fill in the rest of the fields automatically**. If it doesn't, it's likely that something went wrong when copying the link from this PDF: try typing it instead. Check that your dialogue looks like figure \@ref(fig:enterMarauroaURI-fig) before proceeding.
```{r enterMarauroaURI-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Your Import Projects from Git dialogue box should look like this"}
knitr::include_graphics("images/1.4enterMarauroaURI.png")
```
If everything looks okay then select `Next`.
::: {.rmdnote}
**Does your Clone Attempt Fail With An Error?**
If so, the Arianne project Git server may be temporarily down. If you can't clone using the URI given above, you can try using this GitHub repository URI instead:
````md
https://github.com/arianne/marauroa.git
````
:::
Eclipse will now communicate with the remote Git repository specified in the URI. It will ask us which branches we want to work with locally, that is, which branches we want to create local remote tracking branches for. Note that this is not the same as asking us which commits we want to include in our clone. A standard Git clone will always include all the commits in the cloned repository, regardless of which branches we select here. And it is not asking us which remote branches we want to have in the repository. Again, a standard Git clone will include all the remote branches by default. The question Eclipse is asking here applies only to the question of which tracking branches should be created in the clone.
We're not going to be making any serious changes to the Marauroa code base in this workshop, so we will just ask for a remote tracking branch to be created for the `master` branch of the repository, see figure \@ref(fig:selectMarauroaBranches-fig). If you need to remind yourself how branching works, you might like to visit (or revisit) [learngitbranching.js.org](https://learngitbranching.js.org/).
```{r selectMarauroaBranches-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Take a look at the list of branches contained in the project, by scrolling up and down the list. You'll see that the Marauroa project uses separate branches to describe specific releases, as well as other development branches. Another common approach is to have a single release branch and to use tags to distinguish specific releases on that branch."}
knitr::include_graphics("images/1.4selectMarauroaBranches.png")
```
Make sure that the `master` branch is selected, and press `Next`.
::: {.rmdcaution}
(ref:cautionbox)
**Master or Main?**
Historically, the default name for initial branch in a git repository was `master`. The initial branch was called "master repository" with other copies serving as "slave repositories".
Note that as of 2021, the use of `master` has now been deprecated. We're using it in this course unit, but by default, new projects using git will call the initial branch `main` not `master` to avoid problematic [master/slave terminology](https://en.wikipedia.org/wiki/Master/slave_(technology)).
See [about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) for more details on the switch.
:::
As in the GitLab Access Check activity, we need to tell Eclipse where we want the cloned repository to be stored before it can issue the Git command to create it see figure \@ref(fig:configureLocalStorageMarauroa-fig)
```{r configureLocalStorageMarauroa-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Cloning from git dialog box"}
knitr::include_graphics("images/1.4configureLocalStorageMarauroa.png")
```
You can use the default location suggested, or you can use the Browse button to use the file selector to create a new directory in a different location. Here, I've followed the standard convention of putting the repository inside my personal `git` folder.
When you have selected your preferred location, select `Next`.
Eclipse now issues the commands to clone the project.
The next step is to import the Marauroa project from your local Git repository into Eclipse, so you can start to work on it.
::: {.rmdnote}
**What is a project in this context?**
One of the confusing things about IDEs when we first start to use them is the notion of a `project`. When we code from the command line, we tend to organise our work in directories. Sometimes these directories relate to specific tasks we are carrying out (like coding up the solution to a lab exercise) and sometimes they relate to the structure of the code we are creating (like different directories for source code and object code, or libraries or documentation).
We use directories for all these purposes when we code in an IDE as well, but in order to be able to support us well, the IDE needs to know the *root* directory of a piece of software that we are building. That way, it can perform useful tasks for us, like automatically setting the `classpath` for us, and automatically compiling code and reporting on errors while we type. This root directory is typically referred to as a *project*. IDEs use the concept of a project as a means of recording metadata about the project. For example, Eclipse will remember that a specific project is a Java project, and will then know to apply the set of tools appropriate to Java projects, and not (for example) tools relating to Ruby or Python.
:::
As in the GitLab Access Check activity, we have to tell Eclipse which wizard to use to import the project for us. Since the Marauroa team uses Eclipse, we can use the wizard that looks for existing Eclipse projects in the repository, see figure \@ref(fig:wizardImport-fig) If we were loading a project built in another IDE, we would need to use one of the other wizards.
```{r wizardImport-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Cloning from git dialog box"}
knitr::include_graphics("images/1.4wizardImport.png")
```
Click on `Next` when the correct wizard has been chosen.
Eclipse will now scan the local Git repository looking for anything that it recognises as an Eclipse project. It looks through all the folders, searching for the metadata files that Eclipse creates and stores in the root directory of a project. In this case, it finds just one (called `newmarauroa`) see figure \@ref(fig:eclipseSelectProjectsToImport-fig)
```{r eclipseSelectProjectsToImport-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Import projects from a git repository and the newmarauroa project"}
knitr::include_graphics("images/1.4eclipseSelectProjectsToImport.png")
```
Since there is just one project in the repository, we have an easy decision here. Click on the `newmarauroa` project to select it, and then click on `Finish` (finally!).
Eclipse can now import the project into your workspace. When that is done, you'll be taken back to the main Eclipse work screen (strictly speaking, we're taken back to what Eclipse calls the 'Java Perspective'). You should see that a project has appeared in the Package Explorer view, and that the Problems view has now been populated with information see figure \@ref(fig:finallyImportedProject-fig)
```{r finallyImportedProject-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Import projects from a git repository and the newmarauroa project"}
knitr::include_graphics("images/1.4finallyImportedProject.png")
```
### Checkout a Specific Commit
Although we asked for the `master` branch to be checked out locally when we cloned the repository, we are actually going to be working with a different commit, one that is not pointed to by `master`. This is partly to make sure everyone in the workshop uses the same commit for the exercise, even if `master` gets updated between the creation of these notes and the running of the workshops. But it is also to give you confidence in working with non-head commits (that is, commits that are not pointed to by a branch or tag).
For this activity, we are going to work with the commit with the short SHA of (ref:commit-were-using).
The easiest way to check out a commit, branch or tag from within Eclipse is to use the History View. To open it, right-click on the `newmarauroa` project name in the Package Explorer view. Select `Team` > `Show in History` from the menu that appears. The History View shown in figure \@ref(fig:historyTab-fig), should now be visible in the bottom panel of your Eclipse window. You may wish to double-click on the view tab to expand it, so that the contents are more easily seen.
```{r historyTab-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "In this view, you should now see the most recent part of the network of the Marauroa project repository. You can scroll down to see the full commit log. As you can see, the history is significantly more complex than the simple repository we looked at in the GitLab Access Check. Marauroa has been under development since 2003, and its history reflects its age. Note that your view of the repository may be a little different than that shown in the screenshot. We are working with a live repository, and new commits are being made on a regular basis."}
knitr::include_graphics("images/1.4historyTab.png")
```
Look for the commit with SHA (ref:commit-were-using). It should have the (not terribly helpful) commit message (ref:commit-message). Right-click on it, and select `Checkout` from the menu that appears.
At this point, Eclipse will warn you that you are in a `detached HEAD` state shown in figure \@ref(fig:detachedHEAD-fig)
```{r detachedHEAD-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "(ref:captiondetach)"}
knitr::include_graphics("images/1.4historyTab.png")
```
(ref:captiondetach) A warning of the detached HEAD state which reads: “You are in the `detached HEAD` state. This means you don't have a local branch checked out. You can look around but it's not recommended to commit changes. The reason is that these commits would not be on any branch and would not be visible after checking out another branch.”
This just means that we have checked out a commit that is not pointed to by any current branch or tag. The `HEAD` in Git is the currently checked-out commit. Eclipse (and Git) are warning us about this because any changes we make and commit from this point will also not be pointed to by any branch or tag (unless we create one specifically). In fact, they will be unreachable from any branch or tag, and so will be treated by Git as if they had been deleted. They will be scheduled for garbage collection, the next time that takes place. We're not going to commit any changes for this exercise, so we don't care whether the `HEAD` commit is detached or not. We can safely ignore this warning for now.
::: {.rmdnote}
**Checkout and Detached Heads**
If you're interested to learn more about checking out a detached head, you could read this article: [What's a "detached HEAD" in the Git FAQ](https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit)
:::
Press `OK` and double-click on the History View tab, to shrink the view back to its original size and location, now that we have finished working with it.
### Explore your Project {#explore}
You now have your own copy of the Marauroa project source to play with and look around a little. Take a few minutes to look around and explore what is inside it before moving on to the next step. Look at the way the contents of the project are organised into folders. Can you guess the contents of each folder from its name?
Explore some of the folders. Can you find some Java class files? What clues did you use to track them down?
Notice the icon that Eclipse has placed next to the project name. Quite a lot of information is packed into this small symbol. The folder symbol indicates that this is a project. The small J just above it indicates that this is a Java project. The small orange drum under the J indicates that this project is under version control. Eclipse also tells us the name of the Git repository the project is stored under, and which branch or commit of the project we current have checked out, in the text following the project name: `[marauroa (ref:commit-were-using)]` (or similar). Finally, the small yellow road sign with the exclamation mark in the middle tells us that when Eclipse used its internal builder on the Java code in the project, it encountered some compiler warnings.
You might be surprised to see that the Marauroa team have released code that produces compiler warnings. Let's take a look at what the warnings are, using the Problems view. You'll notice that this view has already been populated with some information about the project, without us having to ask for it to be generated. IDEs will commonly provide services like this, performing key analyses of the project source and letting you know about problems without you having to explicitly request it. After all, if we have introduced a compilation error, we want to know about it as soon as it happens, and not much later when we finally remember to ask Eclipse to compile the code.
Because the Marauroa team have configured this project as a Java project, Eclipse already knows how to find the Java source files, and it uses its internal Java build tool to compile them. In fact, it will recompile every time we make even a small change to the code, as well as when we import new code. From the Problems view, we can see that this automatic compilation produced no compiler errors (good!) but 158 compiler warnings (eek!).
If you have time, you can take a few minutes to explore the compiler warnings generated, by clicking on the small triangle beside the warning `Warnings` in the Problem view. Take a look and see if you think these are serious problems or whether the Marauroa creators were making a reasonable decision not to fix them.
**STEP 1 of 4 COMPLETED**
You've now completed the first step, and have a code base to explore. But, that is only the beginning. Please proceed to the next step, where we'll look at how to **use the automated build scripts** provided by the Marauroa team to build an executable version of the Marauroa engine.
## Building the Marauroa Engine
If we are going to make changes to an existing body of code, we have to be able to create an executable version of it. There is no point in making changes to source code if we can't actually run the new version of the code.
In this step, you're going to be introduced to the Apache Ant automated build tool, which is the tool chosen by the Marauroa team for use on their project. You'll learn how to use it to create executable code from the source we've just downloaded.
::: {.rmdnote}
**Note:** we will not cover a full tutorial on the use of the Ant tool in this workshop --- nor indeed in any workshop to follow in the semester. One of the key skills we need when working with large existing software systems is *the ability to keep moving forward* even when we don't have much of a clue about what is going on. We have to accept that we will never know everything there is to know about the tools used by the system, or the source code of the system, or any other aspect of the system.
:::
For our purposes today, you just need to know how to run an Ant script to create an executable project. We'll take a look at the build script, to get an idea of how it works, but there will be a lot that we ignore or skip over very briefly. Becoming comfortable with this approach is one of the skills you need to develop over the course of this semester. (Many of you will already possess this skill, of course!)
### Locate and Examine the Build Script
Open up the `newmarauroa` project in the Package Explorer (if you have not already done so), and scroll down until you see a file called `build.xml`. This is the default name for Ant build scripts. Double-click on it, to get Eclipse to load the file into an Editor view, so that we can see its contents shown in figure \@ref(fig:buildfile-fig)
```{r buildfile-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "An XML build file"}
knitr::include_graphics("images/2.1buildFile.png")
```
If the filename wasn't already enough of a clue, you'll see from this that Ant build scripts are XML files. XML tags are used to define the things that the file knows how to build, and the steps involved in building them, as well as key configuration information, such as class paths (shown in the screenshot above).
Notice that the Outline view has also now been populated. This very useful view gives a high-level summary of the contents of a file, by listing its main components as a tree view. In the case of a Java file, the Outline view shows the classes defined by the file, and their members (fields and methods). In the case of XML files, like our build file, the Outline view shows the hierarchy of tags defined by the files.
We can use the Outline view to run Ant builds, by right-clicking on the XML tags that represent descriptions of how to build things. But an even more useful view is the **Ant View**. This is a view that has been created with knowledge of how the Ant build tool works, and added into Eclipse as a plugin. Open it by selecting `Window` > `Show View` > `Ant` from the top-level menus.
Now open `build.xml` from the view by clicking on the `Add Buildfiles` icon in the view toolbar. It looks like an ant with a green plus on its left shown in figure \@ref(fig:antAddBuildfile-fig)
```{r antAddBuildfile-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "An XML build file"}
knitr::include_graphics("images/2.1antAddBuildfile.png")
```
This will open a new dialogue that allows you to select a Buildfile. Select `build.xml` and click `OK` shown in figure \@ref(fig:selectBuildfile-fig)
```{r selectBuildfile-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Buildfile Selection"}
knitr::include_graphics("images/2.1selectBuildfile.png")
```
Notice that the Ant view has been populated. Instead of listing all the top-level XML tags, this view knows just to list the **build targets**. These are the things the Ant script knows how to build. The user of the script can request which target she or he wishes to build.
Scan down the targets and see if you can guess from the name what each one builds. Hint: `dist` here stands for `distribution`.
Let's take a look at the definitions of some of the targets. Right-click on the name of any of the targets, and select `Open In` > `Ant Editor` from the context menu that appears. You will see that the contents of the `build.xml` editor window are changed, so that the definition of the target we have clicked on is displayed. For example, in figure \@ref(fig:jarallTarget-fig), we've clicked look at the `jar-all` target and take a look.
<!--Redo in Ant View-->
```{r jarallTarget-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "The jar-all target"}
knitr::include_graphics("images/2.1jarallTarget.png")
```
We can get a rough idea of what this definition is telling us. First, note the `depends` attribute in the target tag. This states that before we can build the jar file for the project, we must have built the `compile` target. This makes sense as we need to have compiled Java code before we can create a Jar file.
These dependencies between targets are one of the key strengths of build tools such as Ant. We can describe individual steps in the build process, and state the other steps that they depend on. At build time, Ant will examine all the targets and their dependencies and find an order of execution that means that no target is built before the targets it depends on.
It's important to note, again, that you don't need to understand everything about the Ant build file to be able to make some educated guesses about what it is doing. We don't need a detailed understanding just now. We are just looking for easy-to-absorb clues as to what the various targets do.
::: {.rmdnote}
**A Note on Automated Build**
At this point, you might be wondering why we are bothering with this complicated build script when the Eclipse internal Java builder already seems to be doing a good job of compiling all the Java classes for us, without us needing to do anything at all.
The answer is that there is typically more to turning source code for a non-trivial system into deployable software than just compiling the Java code. The Eclipse internal builder creates class files for all the Java files. But when was the last time you downloaded an app or application and what you got was a folder full of class files?
Quite what *deployment* means differs from application to application. Simple Java applications may simply be wrapped up into a jar file, but even then we often need to supply a shell script for setting the class path and executing the main method of the entry point class. If we are building a Web application then deployment typically means packaging up the components of the application in a `*.war` file (web archive file) and copying it into a particular directory (the one used by the container manager our web server provides). Or, we might need to prepare a zip archive of files, or to package up the files ready for use by an install tool.
As these examples show, the steps needed to deploy a system are often very simple, but they are also quite fiddly and fussy. One wrong keystroke and we end up with something unusable. Explicitly documenting the deployment steps in an automated build script make the deployment process quick, easy and reliable for anyone on the development team to carry out, even the newest team member. That is very important, as it means that tests can be run on the deployable form of the system (even if it is not, at that point, deployed in the live environment). As we have seen, the closer our test environment can be to the live environment, the more chance there is that we'll find errors before they reach the customer rather than afterwards.
:::
### Build the System Using the Build Script {#buildscript}
Now that we have seen something of the build script, we are going to use it to build the whole Marauroa distribution. That is, **we are going to ask Ant to build the "dist" target**.
Right-click on the target we want to build and select *RunAs* from the menu. You'll see that the IDE recognises the file we have clicked on as an Ant Build target and offers the option of running it as an Ant build.
::: {.rmdnote}
**Note**: you can build a target from both the Outline view and the Ant view in the same way
:::
Select the first of the two Ant Build options. The second takes you to a wizard, but we don't need that at this stage.
A Console tab will appear (figure \@ref(fig:consoleOut-fig)) in the bottom section of the Eclipse window, showing the output that Ant is sending to the standard output and standard error streams while it works. Double click on the tab of the Console view, and take a look at what Ant is doing.
```{r consoleOut-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Console output"}
knitr::include_graphics("images/2.1consoleOut.png")
```
The console output shows the various targets that Ant creates, as it works through the dependencies specified in the build script. The targets are shown at the left of the window, followed by a colon (init and compile, in the above screenshot).
Beneath the target, the names of the tasks invoked are shown, in square brackets.
The most important part of the output, of course, is shown at the end, when the process finishes:
```{r endconsoleOut-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Console output"}
knitr::include_graphics("images/2.2endConsoleOut.png")
```
We can see here that the build was successful. We have built the executable version of the code, just by right-clicking on a target! Building Marauroa would be a lot more work if we had to carry out all these steps ourselves, manually, every time the code changes, and the chances of getting a step wrong would have been much higher. This shows one of the strengths of automated build tools. The Marauroa team have encapsulated their expertise in building their games engine into this build script file. It now becomes possible for anyone, with or without expertise in Ant, or Marauroa, to build the system in the same way.
In other words, the build tool has made the build process *repeatable*. A source of potential error in working with the code (and in deploying to the user) has been removed.
Take a moment to look through the full console output from the build command we have just run. Look for the actions the build script is taking that are vital to creating a deployable product, but which are not about compiling individual class files.
### Examining the Results of the Build {#examining}
We'll finish this step by taking a brief look at what the build process has achieved.
Right-click on the `newmarauroa` project name and select Refresh from the drop-down menu. Eclipse knows about any file changes you make using Eclipse tools (such as the Java editor or the internal Java builder) and can update the view of the project you see through its GUI automatically for you. But Ant is not part of Eclipse. It is a separate tool that Eclipse is running for us. When an Ant script creates new files and folders, or moves things about, Eclipse doesn't know anything about it, and so the view of the project it shows to us can get out of date. The Refresh menu option tells Eclipse to go and look at the directory structure and files in the project directory, and to update the GUI to show the effects of any changes.
When you refresh, several new folders should appear: build, build-archive, dist and javadocs.
Take a few moments to look at the contents of these folders, and see if you can form any hypotheses as to their role in the deployment process. If we were going to share the Marauroa engine we have just built with a friend, what would we need to do?
**STEP 2 of 4 COMPLETED**
You have now completed the build step of the process. Now we need to find out whether the engine we have built does what we expect it to. Next, we will learn how to run the automated test suite that the Marauroa team have created.
## Testing the Marauroa Engine
Having created an executable version of the system, the next step is to check whether it is working correctly. In this part of the activity, we'll take you through the process of running the automated test suites created by the Marauroa team. You saw one way to run JUnit tests in Eclipse in the GitLab Access Check activity. But there we just had one test class with just a few test methods to worry about. The Marauroa test suite is much larger than this, and we need a different approach.
We'll take a first look at how these suites are organised and implemented in this step, though this is a topic we'll be coming back to in future workshops, too.
### Finding Out What Tests There Are to Run
Before we run the tests, it is helpful first to take a high-level look at the test suites provided by the developers of the system we are working with. One way to do this is to look at the source folders in the project. The source code for any large project, nowadays, is typically split into two halves: the production code (the part that the user will use and the customer will pay for) and the test code (the part that the development team use to work out whether they are delivering the right thing). It's important not to get these two parts of the code mixed up, and therefore it is common practice to split test code off into its own folders (and sometimes its own packages).
Another source of useful information about the test suites is the Ant build script. Although called a ``build`` script, we have seen that these scripts do a lot more than just compiling code. Their task is not just to create an executable version of the system, but to create a verified executable that is ready for the user to take away and use. Therefore, these scripts more normally follow a three-step process:
1. build
1. test
1. deploy
The Marauroa build script is unusual in that the target that produces the distribution doesn't also run the tests. But it (the build script) does contain instructions for running the test suites.
Take a look at the targets in the build script. We can see that there is one called `test`. That sounds promising. Let's take a look at figure \@ref(fig:showTestTargetInBuildScript-fig)
```{r showTestTargetInBuildScript-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "(ref:captionshowtestcaption)"}
knitr::include_graphics("images/3.1.1showTestTargetInBuildScript.png")
```
(ref:captionshowtestcaption) We can see that this target is dependent on another target, called `compile-tests`. That makes sense as we would expect to have to compile the test (and production) code before we can run the tests.
Let's take a quick look at that target before we look at the rest of the `test` target shown in figure \@ref(fig:compileTestsTargetJustCode-fig)
```{r compileTestsTargetJustCode-fig, echo = FALSE, fig.align = "center", out.width = "100%", fig.cap = "Testing targets"}
knitr::include_graphics("images/3.1compileTestsTargetJustCode.png")
```
The target in figure \@ref(fig:compileTestsTargetJustCode-fig) depends on the `compile` target. In other words, the Marauroa team are saying here that if you want to compile the test code, then you have first to compile the production code that it tests (which makes sense, because the test code will make use of lots of classes and methods from the production code).
In the description of the `compile-tests` target, we can see two calls to `javac`, and a couple of file copy commands. The `javac` commands are compiling code in the folder specified by the ``$\{src-test\}`` property and the ``functional_tests`` folder.
A string of the form ``\$\{something\}`` in an Ant script is a reference to the value of the property called ``something``. They can be defined in the Ant script itself (using the `property tag`), but the `src-test` property has its value set in the ``build.ant.properties`` file, which the build script imports. If we look in that file, we can see that this property is set to the path to the ``tests`` folder.
So, we can see from this small section of the build file (without bothering to look any further) that there are two kinds of tests in the Marauroa system: functional tests and another kind of test. It is a fairly safe bet that this other kind of test are unit tests.
::: {.rmdnote}
**Forgotten what unit tests and functional tests are?**
This was covered in COMP16412. Unit tests are short snappy tests that (strictly speaking) just test the behaviour of a single code unit. In Java, we normally think of individual classes as the units for unit testing. Functional tests are tests of the major functions that the system offers, and will typically involve the execution of many classes working together.
In practice, it's quite hard to write true unit tests, and many of the tests in the `test` folder will in fact be *integration tests*, i.e., tests that assess the behaviour of a small number of units, working together.
:::
Now that we understand something of what is happening in the dependent tasks, we can go back to the `tests` target. Its body contains a couple of tasks that appear to be calling a tool called `jacoco`.
[JaCoCo](https://www.eclemma.org/jacoco/) is a test coverage tool. We'll look at what it does in more detail later in this activity, but for now all you need to know is that it is a tool that runs the tests, and works out what proportion of the production code statements are executed by the tests.
We can also see a call to a `junit` Ant task embedded in the `jacoco` task definition. That must be where the tests are actually run. It is run inside a `jacoco:coverage` task, suggesting that JaCoCo will be collecting the coverage information while JUnit is running the test suite.
The other target is called `jacoco:report`. The name suggests that it has the job of taking all the coverage logs gathered from running the tests, and producing a coverage report from that information.
### Run the Tests
Now that we know a little about what is happening inside the test-related targets, we'll run them. Just as we did with the `dist` target when building the code, we're going to right-click on the `test` target, and select `Run As` > `Ant Build`.
Please try that now.
<!--image but with ANT VIEW-->
As before, you should see a log of what Ant is doing appearing in the Console view. (Note that this time, the compile target and its predecessor targets are run but seem to do nothing. This is because Ant knows that the production code source hasn't changed since these targets were last built. So, there is no point wasting any time recompiling them, when we can just use the object files that were created the last time.)
<!--The final part of the console output should look like this:
\includegraphics[width=\textwidth]{{{3.2.2consoleOutputFromTestTargetEnd}}}
From the output, the target seems to have run to completion. The build was successful so no tests seem to %have failed. The whole process (the console output informs us) takes 32 seconds. (The elapsed time, of %course, was almost certainly a little longer than this.)-->