18 Team Coursework 1

Team Coursework 1: Dealing with Small Scale Code Changes

Coursework Lead: Tom Carroll

18.1 Key Information

Submission Deadline: 2023-10-27 18:00
You can obtain pre-deadline feedback throughout the coursework exercise, via the RoboTA Report.
You can receive verbal feedback after your Teamwork Interview.
Final Grades and Feedback to be released on or before: 2023-11-24 (within 15 University working days of the submission deadline; Days within Reading week are not counted as working days)
A summary of penalties can be found here

⚠️ Caution ⚠️

Please ensure that you synchronise your local repository properly, in order to use the patched codebase.

If you do not synchronise properly, you can create some serious problems for yourself, but also for your team. Please refer to the following Piazza post.

If you do not synchronise your local repository properly, and you push changes with the non-patched codebase, then your access to the repository may be removed in order to prevent further damage. You will need to contact Suzanne or Tom in order to restore access.

18.2 Overview

For this first team coursework exercise, your team has been provided with a Git repository hosted on the Department’s GitLab server. This repository contains a modified version version of the Stendhal code base. Once the coursework begins, the issue tracker of this repository will be populated with a number of issues describing “bugs” in the code that your team must fix by the coursework deadline.

We are not just asking you to fix the bugs. We are asking you to work like a professional software development team. You must ensure that all the issues you are fixing are covered by unit tests before you fix them, and you must use feature branches to protect the work of other team members from any mistakes you might introduce while working on your issue. You must keep a close eye on the quality of your development branches and release branches (with the help of a continuous integration server), and you should use basic Git techniques to ensure that only code changes that compile and pass the unit tests reach the released code.

Your team must then prepare a new release of the Stendhal code, correctly documenting all the changes you have implemented.

Your team is required to produce a video which demonstrates your work.

Your team will be interviewed face-to-face, giving you an opportunity to reflect on your teamwork.

The exercise will test your ability to:

make use of a simple Git workflow, based on feature branches, to allow multiple coders to work safely on a code base at the same time,
use an automated test suite to make code changes to a large body of code without causing regression,
write new tests to make bugs visible before you fix them,
use code reading techniques to locate the parts of a large software system that are relevant to a particular bug,
prepare a good quality release incorporating the work of multiple developers, and
present a professional demonstration of the work you have done, and reflect upon your team processes and how they can be improved.

18.3 Deliverables

Deliverables are contained in 3 parts:

GitLab repository:

Selected Bugs
Correct use of Git (including Branching and Tags)
Correct use of time estimation and other planning tools
Tests which make your selected bugs visible
Source code of your bug fixes

Blackboard Submission:

Video demonstration of work

You must familiarise yourself with the submission instructions, in order to submit your work in the proper way.

Interview:

Discussion with marker about your teamwork
Reflection on process

Please see the information about the interview for more information.

Work which is not submitted in the correct way will receive a mark of 0.

18.4 Step 0: Set up Git Config

It is important that you ensure your work is attributed to you in the proper manner; if you were a company employee, your boss would want to see that you are indeed completing your tasks. You would normally assert your authorship over commits with a company email address.

Brain is a Tech Lead at Acme Solutions, leading the development of the Taking Over The World Project. He wanted to find all commits authored by his Junior Dev, Pinky. He searches for all commits with the associated email address of pinky@acme.com, as per the company protocol on Git usage.

Last night, Pinky used his personal laptop to push some commits, and forgot to change the email address in his git configuration, meaning his commits were associated with _xX_pinky_the_lab_mouse_Xx_@.com. Pinky’s boss (rightfully) did not trust that these commits were authored by Pinky, who then faced disciplinary action.

It is very important that you use the correct email address to attribute your authorship over your commits!

⚠️ Caution ⚠️

Please make sure you set the user.name and user.email variables on all machines you intend to commit from. Your email needs to be your firstname.lastname@student.manchester.ac.uk address. No aliases will work - it has to follow that format.

It is your responsibility to ensure the correct email address is used, though the RoboTA report (viewable throughout the exercise) will attempt to inform you of such an issue.

The RoboTA report (which is available for pre-deadline feedback) will flag up to you if it detects an unexpected email address, but this should not be relied upon to determine that you have used the correct email address - that is your responsibility.

Commits made from other accounts (or aliases of your university account) will NOT be considered to be part of your team’s submission for the exercise.
Any individual who does not use their correct email address for any of their commits will be deemed a non-contributing member and will be given a mark of 0

18.5 Step 1: Get It, Build It, Test It

Following the same process covered in the workshops, each team member should acquire their own local copy of the team repository, learn how to build and test it, and run the code as a locally hosted version of the game. Instructions for doing this are in chapter 20.

⚠️ Caution ⚠️

Please ensure that you synchronise your local repository properly, in order to use the patched codebase.

If you do not synchronise properly, you can create some serious problems for yourself, but also for your team. Please refer to the following Piazza post.

18.6 Step 2: Assign the Issues

There are a number of issues to the project’s issue tracker, each of which will describe a bug or problem with the code base that you are asked to fix.

Fisherman’s License Quiz is not Fair
Lying about Orbs
Ketteh Wehoh Has No Manners
Sheep Seller is not Helpful
Baelin is a bit Quiet
Supplies for Phalk
Pequod The Forgetful
Cheating on Zekiel’s Practical test

For each issue in this list, perform a minimal examination of the code base and decide as a team who will be responsible for fixing each bug.

You now need to use the issue tracker to assign each bug to the decided responsible person; every member of the team must be assigned as the responsible person for one issue. Whilst the coding (and commits) should be done by one person per issue, it is encouraged to discuss your work with your team mates.

If your team has the same number of members as there are issues, then you should plan to fix all the issues.

If your team has fewer members than issues:

you must select which issues to fix
leave any unselected issues unassigned, and remove them from the Coursework 1 Release milestone in your issue tracker. The automated marking system will mark only those issues that are associated with the milestone at the deadline.

⚠️ Caution ⚠️

Any individual who is not assigned respoinsibility for an issue in the proper way will be deemed a non-contributing member and will be given a mark of 0

ℹ️ Note ℹ️

Bugs vs Features

Every year, this exercise raises questions from students who are concerned that their assigned “bug” isn’t really a bug.

What is a software bug? The most widely accepted definition is that a bug occurs when the implemented behaviour of a system deviates from its specification. This contrasts with a feature, which is defined as new behaviour needed of the system, that is not currently described in the specification.

This sounds very clear and reasonable in theory. But in practice, the situation is complicated by the fact that most systems don’t have a written specification. Any specification that does exist is largely a collection of ideas and recollections in the heads of the people responsible for deciding what the system should do. Whether a particular software change is a bug or a feature is therefore in the eye of the beholder, and there is very little to be gained from trying to argue one way or the other.

The “bugs” we have set for this exercise are all either actual bugs from the Stendhal project issue tracker, variations on reported bugs from the issue tracker or bugs that we have invented that are closely analogous to the kinds of bugs being reported by users of the game.

Unfortunately, many of the bugs reported on the Stendhal issue tracker are too complex, and too difficult to write tests for, to be suitable for a beginning coursework exercise like this one. But we have tried to retain the form and spirit of “real” bugs in the issues we have assigned for the coursework. This also means that they are at a range of difficulty levels. If you were lucky/unlucky enough to be assigned an easy bug, consider pairing with someone else on your team who might be struggling with a harder one. You can’t do the work for them, but you can be a sounding board, and can help with exploring the code base to find the relevant parts of the code.

18.7 Step 3: Time Estimation

Each team member should make an estimate of how long it will take to fix the bug they are responsible for.

This estimate should be recorded using GitLab’s Time Tracking functionality: gitlab.cs.man.ac.uk/help/workflow/time_tracking.md

At this stage, it is not important that your estimate is correct. What is most important is that you make an attempt at estimating before starting to write code for the fix.

You must also set a Due Date for each issue in the issue tracker. This should be the date when the work on this individual issue should be completed by. Note that this should not be the deadline for the coursework. You need to complete your individual work on the issue in time to merge the work into the development branch and for the new release to be created.

You must now enter a comment to your issue in the issue tracker. Please use the following phrase, which will be searched for by RoboTA 🤖 the automated marking system:

    /estimate <time estimated>
    /due <due date>

18.8 Step 4: Set Up Branches

You must use separate feature branches for each issue, to protect your team mates from being affected by your changes until they are complete, quality checked and ready for use. The next step, therefore, is to set up the branch for the issue you are responsible for fixing.

The branch names to use are as follows:

Bug	Branch Name
Fisherman’s License Quiz is not Fair	`FISHERMAN_QUIZ`
Lying about Orbs	`LYING_ABOUT_ORBS`
Ketteh Wehoh Has No Manners	`MEET_KETTEH`
Sheep Seller is not Helpful	`SHEEP_SELLER`
Baelin is a bit Quiet	`BAELIN_QUIET`
Supplies for Phalk	`SUPPLIES_FOR_PHALK`
Pequod The Forgetful	`PEQUOD_FORGETS`
Cheating on Zekiel’s Practical Test	`ZEKIELS_TEST`

You must create each feature branch starting from the development branch of your team repository, and not from some other feature branch.

⚠️ Caution ⚠️

Failure to use the exact branch names specified will mean that the marking system is unable to find your branch. You would receive a mark of 0 for the incorrectly named branches.

18.9 Step 5: Write Tests to Make Your Bug Visible

Before getting started on the fixes, each team member must ensure that the bug they are responsible for is visible in the test suite (the code under the test folder). That means that the presence of the bug must be flagged up by at least one failing test. To do this, you may need to modify an existing test to make the unwanted game behaviour visible or (if the behaviour containing the bug is not currently tested at all) you’ll need to create a new test class from scratch. It is important that you locate any new test cases sensibly in the Stendhal code base, so that other developers familiar with the organisation of the code will be able to find it easily. You’ll also need to work out how to use the test objects that the Stendhal team have provided, to set up the a game (or partial game) in the state needed to make the issue visible.

Once your test(s) make the bug visible, you must commit your changes, with a suitable commit message.

You should keep track of how long you spend on this step, to the nearest hour. (Note this is the actual number of hours spent on the task, not the elapsed time between when you started on it and when you finished it.)

When the step is completed, add a comment to your issue in the issue tracker, telling us how long this was.
Please use the following phrase, which will be searched for by RoboTA 🤖 the automated marking system:

    Issue now visible in the test suite.
    /spend <time spent>

where <time spent> is replaced with the amount of time you spent on this task, expressed in a form that the GitLab issue time tracking facility can understand, as per instructions here: gitlab.cs.man.ac.uk/help/workflow/time_tracking.md.

Capturing this fine-grained level of time tracking data is not a usual part of a software process. We ask you to do it for this exercise so that you can gain an idea of how long these kinds of tasks take you personally. This will help you in the future in creating defensible and realistic estimates for your work.

18.10 Step 6: Design and Implement Your Bug Fix

Once you have one or more tests that fail because of the presence of the bug, you can make changes to the production code (the code under the src folder) to fix it.

This step can be considered complete when the changes you have made in steps five and six are committed to your feature branch, and when the following conditions are all true when the feature branch is checked out:

All the tests you wrote/modified to make the bug visible pass.
No other tests in the Stendhal test suite fail.

As in step 5, you should keep track of how long you spend on this step, to the nearest hour. When the step is completed, add a comment to your issue recording this. Please use the following phrase, which will be searched for by the automated marking system:

    Issue resolved.
    /spend <time spent>

You may push your feature branch to your team repository at any point during steps 5 and 6, to make your progress visible to your team and to preserve a record of it on the Department GitLab server. You do not have to wait until the issue is completely fixed.

Once you have pushed your feature branch to your team’s remote, the continuous integration server will run the automated build and test processes, to determine the health of the code on your branch.

18.11 Step 7: Merge with Your Team’s Development Branch

⚠️ Caution ⚠️

Please ensure that you synchronise your local repository properly, in order to use the patched codebase.

If you do not synchronise properly, you can create some serious problems for yourself, but also for your team. Please refer to the following Piazza post.

The next step is to merge your work with the development branch. The Stendhal team use the master branch as their development branch, and we ask you to continue to follow this convention in this coursework⁷ For this coursework exercise, we ask you to perform merges in your local repository and push them to the team repository. In later exercises, we will make use of Merge Requests on GitLab to help you manage the merging process, but for this exercise you should not create any merge requests (there is a mark penalty for doing so). Your goal for this coursework exercise is to demonstrate that you understand the basics of merging, by carrying out the steps yourself. When you have demonstrated that, we will move on to using merge requests.

Before merging your work into the development branch on your team’s repository, you need to check that your code changes are not going to introduce any unexpected problems. To do this, first, fetch any changes from your team’s repository, and merge them into your local repository, to make sure you are working from the most up-to-date version of the code base. (If your whole team is following the workflow correctly, this step should be trivial.

A team activity taking you through this process will be covered in the team study sessions.

Next, check out the master branch and merge your feature branch into it (following the same approach we covered in the GitLab Access Check activity).

Do not push the master branch to your team’s remote repository at this stage. (You may, of course, push the feature branch.)

Check that the code base that results from this merge compiles, and that the full test suite passes. If you encounter any problems, you’ll need to reset the master branch back to the commit it was on before the merge. This will have the effect of undoing the merge you just made.

Fix the problem in your feature branch and start this step again. (Of course, if the problem turns out to be caused by code one of your team members has committed to your team repository, you’ll need to stop development and work with that team member to fix their feature branch and re-merge it, before coming back to start this step again for your own feature branch.)

Once you are confident you have a clean merge, you can push the changes to the master branch to your team repository. (You may wish to fetch commits from your team repository again before doing this, if a certain amount of time has elapsed since you started work on this step.)

If, at this point, you get a clean development branch build from the continuous integration server and the bug cannot be replicated when the game is run from the development branch, you can close the issue in the issue tracker.

18.12 Step 8: Push to your Team’s Development Branch

As in steps 5 and 6, you should keep track of how long you spend on this step, to the nearest hour. When the step is completed, add a comment to your issue telling us this. Please use the following phrase, which will be searched for by the automated marking system:

    Feature branch merged into development branch.
    /spend <time spent>

⚠️ Caution ⚠️

Do not push broken code to your team’s development branch

If, by the deadline, you have a feature branch that contains compile errors or has failing tests, you should push it to the team repository for marking, but you should not merge it with your development branch. Your team will get more marks for not merging broken code than you will get for allowing broken code to reach the development branch or release tags.

Leave issues for unmerged feature branches open. The team needs to know that this issue has not yet been fixed, so they can return to it in a future release should customer interest in fixing it become pressing.

Note that it is your team’s collective responsibility to ensure that the status of issues in your issue tracker accurately reflects the state of the code base. If a team mate has marked an issue as completed, but you notice that the tests are failing for the merge, you should reopen the issue, giving a description of the problem as a comment in the issue. Similarly, if a team mate has fixed a bug but forgotten to close the issue, you can check with them and close the issue for them.

18.13 Step 9: Prepare The Release

The final technical step is to prepare the release. Although several team members may contribute commits for this process, a single team member should take responsibility for carrying it out. This team member should create an issue for this task called:

    Prepare release 1.43uom

This issue should be associated with the coursework 1 milestone, and assigned to whichever team member is taking responsibility for carrying out the release task.

Choose the commit on the development branch which will form the basis for the release. This commit should include all the changes for the issues that have been correctly fixed by the team during the coursework and have been merged successfully with the development branch. These are the issues that will be included in the release.

If we look at the previous releases created by the Stendhal team, we notice that a number of changes are made in each case. Notably:

The version number of the software is updated in the build.ant.properties file (and the change is propagated to other relevant files, through the build process - you should check this manually, to be sure).
Any new authors are added to the doc/AUTHORS.txt file
A description of the changes included in the release is added to the doc/CHANGES.txt file.

You will need to make these changes for your release too. You can add them directly to the development branch (or you can use a release branch⁸ and merge with the development branch when complete, if you wish).

When you have created a commit that contains all the code and documentation you want to release, you should mark this by adding a tag at that commit. The tag must be called:

    VERSION_01_RELEASE_43_UOM

This is the version of the code that we will consider to be your released code, when we are marking. So, it is important that you place it at the right place. You can create the tag locally and push it, or you can use the GitLab web interface to create the tag once the final release commit has been pushed.

18.14 Step 10: Prepare Your Video

You are now done with the technical work. Now you must create your video demonstration.

In your video, you must demonstrate every issue that has been selected.

The video must follow the format given below:

The video must begin with video footage of each team member introducing themself and describing, very briefly, their role in the team.
For each issue selected, the person who had responsibility for this issue must:
- Explain the issue
- Show in-game footage demonstrating the issue
- Show in-game footage, demonstrating that the issue is fixed
- Show and explain test code used to expose the issue in the test suite
- Show and explain code used to fix the issue

To create your video, you might find the following software useful (these are only suggestions and shold not be taken as a requirement or endorsement to use them):

OBS (For screen recording)
Shotcut (For very basic video editing: there is a low barrier-of-entry here, when compared to other video editing software)
Powerpoint / Libre Office Impress / Keynote (for creating slides)
Zoom (for creating a video meeting and recording to allow all team members to speak)

Note that all team members must make an appearance in the video, showing their face and their voice.

Your video must not exceed 20 mins in length. In cases where a video is longer than 20 minutes, the video will be stopped at 20 minutes; any content after this point will not be considered for your mark.

⚠️ Caution ⚠️

Any team member who does not appear in the video, and has not registered a legitimate reason with SSO or a member of the course team, will receive an automatic 50% penalty on their mark for the exercise.

Team members who appear in the video will be unaffected by this penalty.

18.15 Submission of Your Team’s Work

Your submission is in two parts: your video file and the GitLab repository.

18.15.1 Submission of Video

Once you have prepared your video, one of your team should upload it to the Submission point on blackboard.

18.15.2 Submission of GitLab Repository

The remaining submission of work for this coursework exercise is through your team’s GitLab repository. All you have to do is make sure the contents of your issue tracker and Git repository are ready to be marked by the deadline. There is nothing else you have to submit. Once the deadline is passed, you will temporarily lose developer role access to the repository and won’t be able to make further changes to the code or commit graph.

18.16 Interview

In weeks commencing 2023-11-06 and 2023-11-13, your team will be assigned an interview slot, to take place some time within a timetabled lab session.

In this interview, your team will meet with a GTA marker, and you will have a disussion about your teamwork during the task.

The general topics will be as follows:

Discuss how you used the toolset during the task
Discuss how you organised your workload across the team
Discuss what monitoring steps you’ve taken to keep the work of the team on track for the deadline.
Reflect on the team exerise:
- what went well?
- What will you take forwards into the next team exercise?
- What will you do better next time?

Please note that this is a discussion and not a presentation - you will not be allowed to use slides, and the discussion will be lead by the GTA marker. Please be prepared to demonstrate the running of Stendhal, as well as to display and discuss your Git graph.

You will receive verbal feedback at the end of the interview.

18.17 Marking

Assessment takes four forms:

Pre-deadline annotation of commits. Each week, your assigned GTA will look at your commits and add annotations to tell the automated marking code which parts of the exercise each commit contributes to. You should take note of these annotations and let your GTA know if you believe the annotation is incorrect.
Post-deadline marking of your team process and the changes you have made to the code base.
Marking based on your video demonstration
Marking base on your interview

Once the deadline is passed, you will temporarily lose developer role access to the repository and won’t be able to make further changes to the code or commit graph. At this point, we will clone your team repository and the automated marking process will finalise as many of the marks as it can. When the GTAs have completed the remaining marking process, the marks will be uploaded to Jenkins and your final mark plus feedback will be visible in your team’s RoboTA build.

You’ll get developer access back once the next coursework exercise begins.

18.18 Getting Feedback

There are several ways that you will receive feedback on this assignment:

BEFORE SUBMISSION: A “live” marking scheme for the exercise can be found on the CI server used for this course unit. You can obtain this by visiting the CI server: https://ci.cs.manchester.ac.uk/jenkins/ The marking scheme gives details of how the marks will be awarded, but also gives an interim mark for your team based on the work completed so far. Of course, only some parts of the marking can be automated.
DIRECTLY AFTER YOUR INTERVIEW:You will receive verbal feedback from your GTA Marker on your teamwork
AFTERWARDS: The complete marking report will be released, incorporating marks from your code, the video, and the interview.

18.19 Coursework Extensions

Since this coursework is a team exercise, no extensions will be given, and there is no option to submit your work late. Team members who experience substantial difficulties in completing their work due to illness or other legitimate reasons will need to complete a Mitigating Circumstances form so that this can be taken into account later. The marking process is sufficiently flexible to take into account non-contributing team members without significantly affecting the team mark for other members.

If you are not going to be able to carry out the work for your issue by the deadline set for your team, you must inform the other team members in plenty of time. This will allow them to make decisions about what to include in the release, so as not to be penalised for the work you have not been able to do.

18.20 Non-Contributing Team Members

Every team member is expected to contribute some meaningful code to the team’s repository. You should declare the work you intend to deliver as you contribution by assigning an issue to yourself in the issue tracker. Commits on feature branches should be made by the team member recorded as responsible for the commit in the issue tracker.

A meaningful commit is one that contributes code changes to either test or production code that moves the team’s repository closer to the fix for an issue in some way. Adding white space, rewording comments or moving lines about are all examples of code changes that will not be considered to represent a meaningful contribution to the exercise. Similarly, a merge commit is not by itself considered to be a contribution to the solution.

⚠️ Caution ⚠️

Any student who has no assigned work in the issue tracker or who has not made at least one meaningful commit to their team repository, from their Department GitLab account, during the period covered by the exercise, will automatically receive a mark of 0 for the whole exercise.

This applies even if you decide to work in pairs on the issues. Sitting and watching someone else make a commit, even if you are telling them what to type, does not count as a commit from you. The commit must be made from your own GitLab account.

If a team includes non-contributing members, the marking scheme will be adjusted to take this into account. This means it is not necessary for contributing team members to pick up additional work, to fix issues that have been assigned to non-contributing members. Instead, everyone should concentrate on fixing their own issue, and on including it safely into the release. The team mark will be adjusted to take into account issues not fixed by team members who are non-contributing.

18.21 Partially Contributing Team Members

If a team member contributes something, but does much less than others or contributes their work in a way that causes problems for the rest of the team, the team as a whole can choose to reduce the mark of that student. For this to happen, you must:

Send an e-mail to the student as soon as the problem is noticed, pointing out the difficulties they are causing for the team, and asking them to say what they can do to resolve matters. CC this e-mail to Anas or Duncan, so we have a formal record of the communication.
Set a deadline for the team’s work that is sufficiently far ahead of the actual deadline, so you have time to chase people who don’t deliver.
Before the team interview, send an e-mail to Anas/Duncan and the offending team member letting them know that the team will propose a reduced mark for them at the interview.
At the interview, raise the issue with the TA, who will document the circumstances on your marking form, along with details of the proposed mark reduction. If the affected team member agrees, the proposed reduction will be applied at that point.
If team agreement on the mark reduction cannot be reached, the whole team will need to meet with Anas or Duncan to agree a way forward.

Note that this process is not necessary for team members who have not assigned themselves any issues or made any commits in your team repository, as they will automatically receive a mark of 0 in this case.

Mark reductions apply to individual team members only. There is no effect on the mark of the rest of the team. Teams are asked to try to resolve problems within the team if possible, before making mark reductions, but this option is there as a measure of last resort for those teams who need it.

18.22 Plagiarism

This coursework is subject to the University’s policies on plagiarism. Details can be found on the School web pages at:

studentnet.cs.manchester.ac.uk/assessment/plagiarism.php?view=ug

Note that committing the work of other people from your GitLab account counts as plagiarism, and action will be taken when it is detected.

18.23 Summary of Penalties

Throughout this document, there are detailed several circumstances where a penality will be applied to a student’s or teams mark. For ease of reference, a list of these is presented:

Description	Penalty	Section
Individual uses incorrect email address on all of their commits	Student receives mark of 0	Section 18.4
Individual does not contribute a meaningful commit to project	Student receives mark of 0	Section 18.20
Individual is not assigned an issue in the proper way	Student receives mark of 0	Section 18.6
Individual does not appear in video	Student receives a 50% penalty	section 18.14

17 Individual Coursework 2

19 Team Coursework 2