COM1001 Introduction to Software Engineering – 20th April, 2020
Team Software Project:
Instructions for the Spring Semester
Structure, Deadlines & Deliverables
In the spring semester each team will implement a web system according to the particular stories they collected from their client in the autumn semester. Because each team has a different client, the requirements/stories for each team will be slightly different. The system will be delivered to the client over two iterations, as per an agile software development strategy.
You will demonstrate progress on implementing and testing the system to the client at the end of each iteration, and the client will feed back to you (and us, so that we can assess your work) as to whether the system meets their expectations as described to you in the autumn semester. In particular, following the first iteration, your client may request further changes based on what they’ve seen and in addition to changes to the original set of user stories. The end of the second iteration marks the finalisation of development on the project and its delivery/handover to your client.
We cover the technical aspects behind the development of the system during lectures and labs in weeks 1–6. Please see the MOLE/blackboard site for lectures (including resources), labs and forum.
The schedule and deadlines for the project are as follows:
Iteration
Deadline
Semester
Weighting
First
Fri, 24th April, 16:00 (week 7)
20%
Second
Fri, 22nd May, 16:00 (week 11)
80%
Demo Video
Fri, 29th May, 16:00 (week 12)
The following artifacts will be assessed as following:
Iteration 1:
• Exemplar code (see Section 1.1)
• Client demonstration
Iteration 2:
• Exemplar code (section 1.1)
• Client demonstration
• Code committed to the team’s repository (section 1.2)
• A Team Report, also committed to the team’s repository (see Section 1.3)
• An Individual WebPA report, submitted via MOLE (see Section 1.4).
• A Video Demonstration of your software (see Section 1.5)
• Exemplar Code
For both iterations, you will submit a short document containing ‘your best code’. The document is limited to 3 sides for iteration 1 and 4 sides for iteration 2.
This exemplar code allows you to show off your ability and receive specific feedback. You should choose your code to represent different aspects of your solution. At least 80% of the code should be ruby code; you may also include some html/css/javascript.
You must use source code colouring, line numbers and name each listing. Take a screen shot and paste it in the document, e.g.
Listing A days_in_month.rb
Please note:
• You should use an alphabetic listing, so that feedback can refer A.11 (i.e. listing A, line 11).
• You should not (typically) include a whole file listing.
• Show the folder and filename to allow the marker to see more detail if necessary.
• You may choose to ‘fold’ parts of your code.
• Standard code quality applies, e.g. appropriate comments should be included – that typically say what the code does, not how it does it (except when it’s necessary).
• Do not include pointless comments – e.g. puts “begin” # output “begin” to the console
• Code should, when possible, explain itself and not need many comments.
• I recommend you do not use code colourizing within the document – it frequently creates issues when opened for marking – a screen shot works much more reliably.
The exemplar code needs to be submitted by adding it to your team’s repository. So that I can find your report and read it, you must produce it in PDF format. You must name it as ‘exemplar-code.pdf’ and place it in the root directory of your repository:
• Iteration 2 – Code Committed to the Team Repository
At the end of iteration 2, we will also be looking at the last commit to the team’s Git repository before the deadline and assessing the amount of work you have completed, the folder structure and its quality. Code will be checked out to Codio for running and checking – it is strongly recommended that you develop on Codio – and at the least it is essential that you deploy often to Codio – this is the required deployment platform.
Ensure all the necessary files are committed to your repository by the deadline/s, otherwise you will not receive the mark you deserve. Late submission will doubtless mean we will not be able to obtain copies of them to assess. (Do not send files after the deadline that you forgot to commit, or instructions to log into your Codio box to fish them out)
Please note the following important points in regard to the use of the Git repository:
1. Team repository — no other. Ensure you’re committing to your team repository (refer to the relevant lab in week 1) — not your personal repository from last semester, or another Git repository.
2. All members should be making regular commits. In marking your work, I will be checking that you have been making regular commits — not just one or two commits or a sudden rush of commits just before the deadline.
In order to mark your work, I need to be able to properly install and deploy your application. Therefore:
3. Ensure that your Gemfile is up to date. If I cannot run your application due to missing gem information, this will severely negatively affect your mark.
4. Attempt a clean install before your final commit. Finally, I would advise that you attempt a clean install of your system before the final commit (testing your deployment instructions that you will write in your team report), so that you are sure that I will be able to deploy it myself. If the clean install does not work, then clearly you have some dependency problems or other issues that need to be rectified before submission.
Because of all of the above, I suggest your team organises itself with a ‘soft’ deadline 1–2 hours (or more) before the hard deadline of 4pm. After your soft deadline, make final checks to ensure everything is committed and deploys properly. If you’ve forgotten anything, you’ll still have time to correct the mistake. Don’t use the period after the soft deadline to make further tweaks or do more implementation and testing — that defeats the point!
1.3 Team Report
The team report needs to detail the following information:
1. Details on how to run and access your system, including:
(a) The exact command(s) needed to start your system — I need to know how to start your application in order to assess it.
(b) The following standard usernames must be used (this is not meant to be secure…):
Username: Password:
admin admin
user user
role1 role1
role2 role2
role3 role3
role4 role4
You should include a brief description of what the ‘role1-4’ users mean for your system, e.g. role1 might be a ‘power user’ (this is not a recommendation).
(c) Any other special details particular to your application, that I will need to know in order to deploy, run and assess it.
2. Resubmission of your stories, with changes annotated and highlighted. Changes to stories are allowed at any time, and can happen for a variety of reasons — for instance: responses to autumn semester feedback, changes made by the client, or changes made due to technical reasons (e.g., something promised in the stories was not actually feasible, or could not be made to work as originally planned). You should highlight any changes (so that it is clear to me what has changed), and annotate the change with the reason for the alterations (so that it is clear to why it has changed). I strongly recommend that you use bold or green highlight for additions, and strikethrough or red highlight for deletions. Note that failure to adequately annotate and highlight your stories will result in reduced marks.
3. The stories you planned to tackle in each iteration. You should document which stories you planned to tackle in each iteration, along with an account of who did what. You should aim to split the workload as evenly as possible across the two iterations. Trying to deliver everything in the first iteration defeats the point of an agile methodology — the client may well change their mind on aspects of the project once they have seen it for the first time, leaving you will a lot of re-engineering to do.
4. Your burndown chart, showing progress over all of your stories over each iteration. You need to include a burndown chart of your progress in developing your stories. This means you need to keep an accurate log of how your project has been advancing over time.
5. Testing and test coverage. A brief paragraph about how you went about testing, e.g. unit testing and manual. You need to show the output from your tests, most likely as screen shots. The report should contain details of how to execute the tests you have written on the system. Your tests should be named or described for their purpose and you should report why you used different types of testing for different aspects of the system where appropriate. If you have had to resort to manual tests, e.g. for browser interaction, full documentation of these tests should be present, including identifying the purpose of tests and the expected results and any failures. Note: It is better to show failed tests than to delete them – especially in iteration 1.
The team report needs to be submitted by adding it to your team’s repository. So that I can find your report and read it, you must produce it in PDF format. You must name it as report-second-iteration.pdf and place it in the root directory of your repository. If you fail to follow these instructions, then you will lose marks.
1.4 Individual WebPA Report
Each team member is required to enter their assessment of their team members via WebPA on MOLE.
The Iteration 1 Web PA has been removed in response to Covid 19.
Iteration
Available
Close
2
Mon, 18th May (week 11)
Fri, 29th May, 16:00 (week 12)
To fill in the assessment you will find a link to WebPA on the module’s MOLE page, entitled “Iteration 2: Peer and Self Assessment”. As with last semester, you will need to rate yourself and your team members on the following criteria:
1. Attendance and punctuality (to group meetings, sessions with clients, etc.).
2. Ability to work effectively with other team members.
3. Contribution to content and organisation of project deliverables.
4. Quality of contributions.
5. Timeliness of contributions.
Your final individual mark is formed from a scaling factor that is applied to your overall team mark. The scaling factor is determined by your own self and peer assessment, and those returned by your team mates. It’s therefore important to complete your WebPA assessment by the deadline.
N.B. The final Web PA scaling will affect individual iteration 1 and iteration 2 marks.
1.5 Video Demonstration of Your Software
You need to create a video presentation of your software, to be uploaded to YouTube.
The video should last no more than 5 minutes. It should involve a personal introduction by each member, where each member says their name, any particular roles or responsibilities they’ve held and what their technical contribution has been to the project. This section can be shot on a mobile phone or any device of reasonable quality.
The video should then go into a screen cast demonstrating the operation of the software. There are plenty of freely available screen capture programs for this purpose. The demo should show the software being started and run with the appropriate command line commands. It should then walkthrough the main features of the software. It should close by demonstrating the system being tested with your automated tests.
You may use any video editing tools available to you, including those freely available on the web.
By the deadline, you need to email the URL of your video to me (a.stratton@sheffield.ac.uk) and your team supervisor (Rayna Dimitrova r.dimitrova@sheffield.ac.uk, Harsh Beohar h.beohar@sheffield.ac.uk, Islam Elgendy i.elgendy@sheffield.ac.uk or Areeb Sherwani a.sherwani@sheffield.ac.uk.
The subject line should be “COM1001 video for Team XX”, where XX is the number of your team.
Team Supervision Meetings
It is important that all team members are present at each meeting, barring exceptional circumstances. We’ll be taking a register: if you cannot make a session, let one or more of your teammates know. If you persistently miss meetings, your tutor will be informed and you will be reported to the faculty for non-engagement with your studies.
Client Meetings
You will notice from the schedule on the course website that in the weeks involving the deadlines for iterations and following there are slots reserved for “Client Demonstrations”. In these meetings, you will demonstrate the current state of your software to your client. For this, you should prepare a 10 minute demonstration of your software.
Prepare the demonstration of your software, in its current state, if iteration 1, by rehearsing beforehand. The best demonstration will involve all or as many team members as possible saying and demonstrating something.
Let your client try out the system – you should send the codio url to access your web application to the client – they can then share their screen with you. They will give you feedback and, if it’s the first iteration, they may request changes to be made for the second iteration.
Client meetings are scheduled to take on Wednesday 29th April (Week 8) Iteration 1, and Wednesday 27th May (Week 12) Iteration 2. All meetings will take place online through your team’s Blackboard collaborate at the same times as the supervisory meetings detailed on MOLE/Blackboard.
Blackboard Collaborate Team ‘room’
In blackboard, under Users and groups
• click on groups:
• You will find your Team there – click on your team (please let me know if you are in the wrong team – mistakes happen). You will notice that your team contains:
• Your team supervisor
• The demonstrators
• Your clients
• You can then choose the Collaborate option under ‘Group Tools’
• Here you can view recordings (if you make any – the demonstration would be good to record…) and ‘Join Room’ (top right).
• When Collaborate starts – you will need to enable audio (and video).
• The bottom right ‘arrows’ allow you to open a panel – the middle option allows you to share content – you can then Share your application screen. I recommend ‘Entire window’ since it’s just simpler.
• This will allow you to demonstrate to your client – and also you can ‘chat’ and send the ‘live’ ruby url for the client to use.
N.B. The Client can have access if you Choose (from Codio) Project->Settings and then choose ‘Public’ (about three down). You must make this private after the client has left – this is not secure – anyone with the url will have access to your application and your source code – YOU HAVE BEEN WARNED.
Team Planning
You should schedule stories to implement according to your client’s priorities. However, your implementation plan may also be necessarily constrained by the order in which technical material is covered in lectures and labs. So check out the lecture schedule and plan the stories you plan to implement in for each checkpoint/iteration accordingly. As stated above, do not try to deliver everything in the first iteration — teams will be marked down if they do this.
With all this in mind, here is a suggested week-by-week list of pointers for your team that you can use to check your plan of action:
Week
Suggested Activities
1-3
Study the lecture notes and practice lab class material on web application development in Sinatra. Reflect on last semester’s feedback on your stories — are there any changes that need to be made? Start to think in your team about which stories that will be implemented first, and who will do what.
Ensure each member can access the team repository and that you’re all set up on Slack and Twitter. Implementation should be underway now.
You should be constructing the basic views for the system, thinking about the forms that need to be writing and writing the controller code to handle them.
It’s time to start thinking about how you will unit test your application, including how you will ‘separate your concerns’ and make use of test driven development. Do you have units to test? If not, can you refactor some of the core functionality of your system so that it’s testable?
4
Think about which stories may require a database and how those may be tackled before the first iteration. Design your tables to reduce redundancy and duplication.
5
It’s time to write the tests, both automated and manual, for the code that has been written, and ensure that it is working correctly.
6
Write tests to cover as much of your implemented stories as possible. As you incorporate more stories into your implementation, ensure that you are testing as you are implementing, as opposed to leaving it a long time afterward. Start finalizing the code for your as the first iteration is due next week.
Easter Vacation
7
Collate your exemplar code and create a document containing colourised code (as pictures). Prepare and rehearse your team demonstration of your system for your client meeting.
8-9
Team meeting this week! Polish that presentation. Following the meeting, decide, as a team, how you’re going to make changes as a result of client feedback and any new requests.
10
Time to meet up and make sure that everything integrates well and is consistent. Check your code style, appropriate commenting, tests, etc. Get the final parts of the system implemented and tested.
11
The second iteration deadline is Friday. Time to finish up on implementation and testing. Prepare your final team report.
12
Prepare and rehearse your demonstration of your software to be delivered to your client at your final client meeting. You also need to produce your video demonstration for assessment purposes. Don’t forget to complete the WebPA peer and self assessment by Friday
Marking Criteria
The following table details the criteria against which your team’s work will be marked. You will receive a mark sheet containing a table, with marks and feedback against the aspects detailed below. Each aspect is marked out of 100. The overall mark is the average of each of the marks for each aspect.
Note: 2 indicates for iteration 2 only, 1+2 indicates for both iterations (highlighted in grey).
Aspect (iterations)
Indicative Criteria
Exemplar Code (1+2)
and
Code in Team repository (2)
The quality of your code, including good coding principles, such as useful variables names, code comments, etc. The extent to which your code defends against simple common vulnerabilities. The basic organisation of your code into units, and its overall structure.
Overall Product
(1+2)
Iteration 1: The amount of work completed to date, and the extent to which you are on track to delivering a good quality product. Iteration 2: The completeness and quality of your final system. The extent to which it implements the client’s requirements, how usable it is, how polished it is, the extent to which it crashes and/or throw errors. Additionally (both iterations): The strength of the feedback from your client.
Documentation and Deployment
(2)
The quality of your team report, the extent to which it details all the requested information, including changes to stories, basic information about using your system etc. The extent to which it was easy and straightforward to deploy and get your system running — on the basis of your instructions and the implementation of your deployment process — from Git checkout to the commands needed to start the application.
Testing
(2)
The quality of your automated tests. The extent to which you have justified the level of coverage that you have obtained. The extent to which you have used and documented manual tests.
Video Demonstration
(2)
The quality of your video demonstration. Is it within the specified time limit. Does it properly (and completely) introduce each team member and their responsibilities/contribution to the system. The extent to which it demonstrates the key features of the system. The extent to which it demonstrates the system being tested with automated tests.