General Project Instructions

Part of the perspectives course consists of a programming project that you will pursue together with a couple of your fellow students. This project starts in the second period (HT2).

In addition to this page, there is also a separate lecture explaining the project. The information given in the lecture slides on Lisam is also important, and much of it will not be repeated here!

Why a project? Why now?

The TDDE25 programming project is important for several reasons.

• It gives you direct hands-on experience in using programming to solve interesting problems at an early stage in your university education.

• It is sufficiently large to let you produce a very interesting final "product", in contrast to ordinary short lab exercises.

• It lets you use your own creativity in extending the initial, mandatory part of the project.

• It allows you to practice working without constant guidance and to take personal responsibility for what you do, how you do it, and how much you learn.

Though this course is comparatively early in your studies, the project part does not start until the second period, when your first programming course has been completed. We therefore expect you to be able to enthusiastically dive head first into the world of software development, to work hard and spend a great deal of time on the project, to write a lot of code, to try different approaches to solving problems, to make mistakes, to learn and recover from those mistakes, and to show us what you have learned.

During 2023, all students participate in the Capture the Flag programming project.

How to pass the course (important!)

The only grades given for the project are U (Fail) and G (Pass).

The requirements for passing this course include:

• Participating in project discussions and development together with your group
• Participating in weekly progress report sessions, as described below.
• Finishing the mandatory part of the project according to the project-specific instructions linked above
• Demonstrating your project to your assistant during the final progress report session
• Handing in the final code together with any documentation that may be described in the project-specific instructions

If you reach the end of the course period without satisfying these requirements, or you miss the mandatory demo or presentation, you will also be able to finish this course and receive course credits in the re-exam periods in March and August the following year.

Please be aware that labs and projects are supposed to be finished during the course. As stated above, we will definitely extend this default deadline up to August next year, but we can't guarantee that you will be able to hand in "kompletteringar" later than that! It may be possible, but this depends on circumstances we can't necessarily control.

Project Groups

For this project, you will be working in groups of 3 students. A change in 2023 is that you will be able to form groups yourselves, finding two partners to work with and signing up in Webreg. However, you will also still be able to sign up on a separate list from which we randomly generate groups. Further information and details will be sent on the course mailing list in mid- to late October!

This usually results in around 50 groups. These groups are then divided into what the scheduling software calls "Storgrupp 1" through "Storgrupp 5". Each such group of about 30 students has its own lab assistant. Once everything have been set up, you will be able to see who your assistant is both in Webreg and in the TimeEdit schedule.

In addition to the assistants, Cyrille Berger (cyrille.berger@liu.se) has the ultimate responsibility for the current Capture the Flag project and its definition, while Jonas Kvarnström (jonas.kvarnstrom@liu.se) has overall responsibilities for the course, including to a certain extent the project part.

Setting Up and Using Version Control

After the project groups have been finalized and before the project starts, we set up Git projects for all groups in GitLab. Using version control is mandatory – here, in most companies, and in most open source or commercial projects.

When this happens, you will get an email notification from the LiU GitLab server.

Please check in (and push) your code often! Do this at least every day, but preferably many times per day.

Working Together in Groups of 3

Working together in groups of 3 is not necessarily trivial. Here are some instructions that you will need to keep in mind.

Work individually on some parts of the project.

When working in groups of two, as in TDDE24, it may be natural to keep working together at all times. In groups of three, you will definitely have to divide some aspects of the project among you and work on them individually. Otherwise you may not finish in time, and more importantly, you may not learn as much!

For example, maybe two project members work on one feature together while a third works on another.

(Not enough computers? During scheduled labs we generally have additional computers available. For example, we may have 20 computers for 12 groups, and you should ask students not taking this course to leave so that your group can have two computers – or ask the assistant to help you with this.)

Keep everyone up to date, and explain what you have done.

Working alone on a specific feature does not mean working in a vacuum. Everyone must have working knowledge of every part of the project and must be able to explain what others' code does and why. Spend the time to discuss the code you write, so that everyone understands what the others have written and designed! This is not wasted time: Seeing and understanding what others write helps you learn, which will be rewarded in evaluations.

Divide the tasks equally, regardless of experience.

Even when you work individually on different tasks, everyone still has to do all types of work. Most importantly, everyone must write a significant amount of code.

Never take over another group member's job.

Everyone must let the other group members do their part. Don't take over their jobs, even if you feel you can do something faster. We will evaluate you individually!

If you are inexperienced, you must still try, and you must make sure you get your share of coding time. Be active, and be proud of what you learn!

If you are experienced, you must also work hard. If the basic project isn't challenging, then challenge yourself by spending time elaborating it, inventing and designing new functionality, and exploring new aspects of programming. No project is so simple it cannot be expanded into something that you can learn from.

No group member is allowed to take over the project. Leave a third of the basic functionality to each participant – however inexperienced they may be, they are not helped by having someone else do their job. The product we aim to produce consists of knowledge and skills, not the project code.

In fact, less experienced members should write more code. More experienced members who want to write more code can devise their own extensions to be implemented in parallel, as long as this does not impede the other members' progress.

If you help someone, give hints – don't do their job. And even if you tell them how to solve a problem, it should be their hands on the keyboard, not yours.

Stay active, even if you are having problems!

Saying "I didn't get anywhere this week" or "I didn't know how to continue so I haven't done anything" is obviously not sufficient, not here and not when you finish your education and get a job.

Be active and proactive! Try to find more information about the problem, from different sources. Try again. Think, abstractly, but also write code and experiment with programming.

Ask the assistant – and ask in a way that provides the necessary information so the assistant can understand what the problem is, when it arises, and what you have already tried.

How will you work together?

In addition to the general instructions above, you as a group have to come to an agreement about how you will work together. You should discuss this openly at the beginning of the project!

In some courses a group contract is set up and signed – we might do this as well in 2023, in which case you will be informed about the details when it is time. Even without a group contract, simply bringing up these issues in an honest discussion can help you avoid a lot of misunderstandings and problems later in the course.

Some topics to consider:

• When will you do the work? Will you meet (physically or virtually) during all of the scheduled lab times, and work together as recommended? When will you do the rest of the work that won't fit into the scheduled labs? Remember that a lot of work needs to be done outside of scheduled hours.

• What will you aim for? Do you aim to go as far as possible with your project, or do you just want to pass the course? If you have different aims, how will you reconcile this so that some of you can add more functionalities without "leaving others behind"?

• How would you like to work in the project, in general? What makes you like working together? What do you think would be problematic, given your own experience?

• Will you be splitting off some parts of the project into tasks that individual members can take care of separately? How will you then make sure everyone knows "everything" within the project? Or will you work together, and only together?

• If someone doesn't show up, how will you deal with this?

• What do you need to learn for the project, as individuals or as a group?

Project Tasks

The specific programming project instructions for Capture the Flag specifies what you need to do in order to complete this particular project.

Make sure that you read those instructions carefully! It may be tempting to just go ahead and write a lot of code, but you need to read carefully in order to understand exactly what is expected of you.

Lab Sessions and Supervision

There will generally be two 4-hour labs booked every week. The intention is to ensure that you get the time to work with your project for longer periods of time without interruption. Lab assistants will only be present/available for half of this time! (The alternative would have been to book two shorter labs each week... But that would give you exactly the same amount of lab assistance, and make it harder for you to find times to work together!)

At these sessions, you can ask the assistants about issues that have come up since the previous supervised lab. You must also use them to discuss your current progress and results with the assistant. Even if you have nothing in particular to discuss, you should be present during most of the supervised labs so that the assistant can see your progress and perhaps give you some tips. If you skip this, you risk failing the course due to insufficient feedback.

Continuous Examination: Progress Reports

Progress discussions every week!

Every week, you need to meet your assistant at some point, in order to discuss your current progress.

We strongly prefer if all group members participate at the same time, since this is both more efficient and allows us to get a full and balanced picture of what is happening within the group. However, we do allow you to have this progress discussion individually in case of difficulties such as some group members being sick or travelling. (Otherwise, group members who kindly agreed to help others by waiting until later in the week could miss their own discussion if they then got sick.)

The primary time for the progress discussion is during the first lab in each week, which is often on a Monday. In general, this is always the time you should aim for, except for the first week.

There are two separate reasons for these discussions. First, it gives us a chance to provide comments and guidance relative to your current progress, which gives you a better chance of passing the course at the first attempt. Second, it serves as a form of individual examination allowing you to show to the assistant that you are making progress and should pass the course. Some form of individual examination is always required by the rules and regulations, and this is one of the least intrusive forms we can use.

Submitting a progress report document

The day before your progress discussion, you must send in a short progress report document according to the template below.

The progress report document is individual and must be sent to your assistant in an email the day before the progress session. Send the report in plain text in the email, so that the assistant can easily see it without opening an attached document. You can use Swedish or English.

What should be in the progress report document?

The format should be as follows. Be careful to follow the template so that assistants can more easily organize the up to 39 reports they must handle each week.

Subject: TDDE25 progress report {Your LiU ID},
         group {Your complete group ID},
         week {Calendar week number}

What have you personally done in the project since the last report?
{Your answers in Swedish or English}

How many hours did you personally spend during each day?
{Your answers in Swedish or English, for each day separately}

How do you think the collaboration has worked?
{Your answers in Swedish or English}

Explanations:

1. Note that the important part of the group ID is the index of your 3-person group. For example, "SG1-05" is a complete group number; don't forget to include the "05".

2. What have you personally done in the project since the last report? You can discuss:

   • Code that you have implemented
   • Problems you have had, solutions you have tried
   • Bugs you have fixed
   • Information you have gathered
   • And so on...

   Relate this to specific milestones or tasks in the project description, and please be reasonably detailed. This will be part of how you show that you have personally done enough to pass the course!

   If you have worked closely with others in your group, you can explain this – but still explain what your particular contribution was, and what role you took, during this teamwork.

3. How many hours did you personally spend during each day since the last report? This is partly for your own immediate benefit (giving you a better idea of where you are spending the most time), partly for the long term (in case of conflicts within the group, which are rare but do happen), and partly a basis for discussing your progress.

4. How do you think the collaboration has worked? Are you getting a chance to write code? Is everyone present? Do you agree on what should be done and how? This is your chance to bring up potential problems at an early stage. Doing this is not disloyal -- it is just a way of letting the assistant know that the group as a whole may need some help.

Sending in this information in advance lets the assistant spend less time taking notes during your discussion.

What will we discuss?

During the progress discussion, you will demonstrate and discuss your current progress with their assistant. We only have 2-3 minutes per group member, so use this time wisely, and be well prepared! (Groups who are not currently reporting will of course continue working on their projects.)

The following topics are examples of what may be discussed. All members must be able to answer questions about any part of the project, including code they did not write. One member might be asked to answer all questions during one session!

1. What is the current state of your project?

   The reports should already have given the assistant a good idea about where you are and what the problems were, in some detail.

   During the session you instead give a brief demonstration of what you have done by running the code you have written so far. Don't worry too much about being able to give a "perfect" demo of all features – we need to see how far along you are, but we are just as interested in seeing what difficulties you have as in seeing what works perfectly. See this as an opportunity for feedback. At the same time you should have something that actually runs, not just some code that won't start. Keep track of "working" revisions in Git so that you can bring back a stable working version if necessary.

   Be prepared: decide what you want to show, and test it before the session.

2. How did you reach the current state of your project?

   Which parts were easy and which parts were difficult? Which difficulties have you encountered in the last week? How have you resolved them, or how are you planning to resolve them?

3. How do you intend to continue?

   What do you think you will do in the following week (which milestones, which subproblems, which issues to resolve, what progress is expected)? Do you foresee any new problems?

If there is no progress in terms of tasks and milestones, simply saying "we didn't get anywhere" isn't sufficient: Explain clearly what you wanted to do, how you tried to do it, what happened, and why this direction was not appropriate. This does not represent progress in producing a product, but it can definitely represent progress in learning about programming!

What if I can't come, or I miss the report or session?

If you miss sending in your personal report on the day before your discussion with your assistant, the assistant cannot prepare properly. Then you, personally, cannot have a progress discussion on that day – the same of course applies if you miss the actual lab session due to illness or for other reasons.

If you are lucky, maybe there is another session in the same week where you can have the discussion instead. Otherwise, you have a problem in terms of showing us that you should pass the course.

Missing a report submission and/or progress discussion one week is OK.

If you miss it a second time, you will get another chance to complete the course by filling in a longer report template. This is not a punishment but simply an alternate means of examination, which will cover the questions that could otherwise have been asked at the weekly progress report session. The longer report must be handed in by Wednesday the week after the missed report/session. The assistant may add additional requirements for examination purposes. (You may of course choose to send in immediately after the first time, to keep your "margin" of one possible missed submission or discussion intact!)

If you miss a report and/or session more than twice, the longer reports will not be sufficient: We do need regular opportunities to talk to you and ask additional questions, and this should be done during the actual report sessions. In this case you must email the project coordinator Jonas Kvarnström, who will discuss the issue with your assistant and the senior advisor. Include an explanation of why this happened.

In most cases, missing more than twice leads to you having to implement additional extensions on your own, without your other group members. This is another way in which we can determine that you, individually, have passed the project requirements.

Requesting Assistance

Throughout the project we expect you to encounter a large variety of problems that need to be solved. For each problem you need to do your best to strike a good balance between trying to find a solution on your own and asking your assistant for help.

If you immediately ask the assistant, you lose an opportunity to practice independent problem solving and to develop your own skills. Therefore you should generally start by discussing within the group, searching the web for information, discussing with other groups, and using whatever other channels are appropriate depending on the problem or question you have.

On the other hand, you lose too much valuable time if you spend days trying to solve a single problem on your own, and for some problems (in particular when it comes to unclear instructions) it may be obvious that asking the assistant is better.

Assistants will primarily be available during the scheduled lbas. They may also reply to emails throughout the period but will not necessarily be at their computers at every moment. If you don't receive a reply to an email, you might have to wait and ask your question during the next scheduled lab time instead.

If you do send questions by mail, make sure that you include all relevant information about the problem itself, how you have already tried to solve it, and why the solutions did not work or did not seem appropriate. If you don't provide enough information you will receive questions instead of answers! Learning how to describe an issue in a useful way is also important for your education.

Final Demonstrations

During the last demo session ("redovisning"), you will demonstrate the final version of your project. Spend some time polishing the software accordingly – this is your final chance to give a good impression! As usual, participation is mandatory for all project members.

The fact that the project is final does not mean that every milestone in the project description must be achieved – in fact we try to specify too many tasks for you to have a reasonable chance to finish them all, and/or leave projects very open-ended. Discuss your progress with your assistant continuously so that you can see if you are on the right track or if you have to do more. Aim to have all features implemented early and then "freeze" the list of features, so that you can spend a full week making sure all the features you already have are functional and polished.

If you have finished everything early, you can choose to make your final demonstration during the last regular weekly progress report session. Earlier final demonstrations are not accepted.

Final Hand-In

The final project code, and any documentation, must be handed in by the deadline 2024-01-07. Feel free to hand in the code earlier, but we will not be grading or submitting results until 2024!

To hand in, you must first make sure that all the required code and documentation is committed and pushed to Gitlab. Then you simply create an issue in our central TDDE25 issue tracker, which is similar to what you have done in TDDE24.

The issue is how you indicate that you consider yourselves finished. Don't forget the issue, or your assistant won't know you want your project to be graded!

As stated earlier, you will also be able to finish this course and receive course credits in the re-exam periods in March and August the following year. Note that we can't guarantee that you will be able to hand in "kompletteringar" later than that! It may be possible, but this depends on circumstances we can't necessarily control. For example, if we change the project type for 2024, and you have not finished your project by August 2024, you may have to participate in a new project from scratch.