Managing Your Work

Team members are responsible for tracking and recording their work. This is reflected in two major practices: updating and closing issues, and journalling.

GitLab Issues

Updating issues

You should only be working on issues that have been assigned to you (typically during a team planning meeting).

You should update your issues to track the work you have done. Typically this means that you should add details to an issue to clarify the problem, and describe what steps you took to resolve it. This description does not need to be long but should be sufficient to explain what was done. In particular, you should document any impact your issue would have on other design elements. e.g., if your fix invalidated the configuration file, and required that file format to change, you should record that in detail.

If the issue is small, you may only have the opening comments and the closing comments. Add additional content only if it is useful.

Closing issues

When you have resolved an issue, you should

• Close the issue in GitLab, with detailed comments.
• Merge your feature branch back into main, and
• Commit your code changed.

Journaling

Each person on the team needs to maintain a development journal: a wiki page with entries describing what you did in each sprint.

• You should have one section per week e.g., Week 10.
• There should be entries for every time you work on the project. I would expect multiple entries per week.
• Entries should include a date, and a brief description of what you worked on.

A journal is a good practice even in small projects, since you will forget details over the course of project.

Source Code

This section describes practices related to managing source code.

Code comments

When writing code, you should add strategic code comments to explain the purpose of your code (not “what it does”, but “why is it done this way”). This does not need to be exhaustive, but it’s a good practice for complex and/or critical code.

Feature branches

For large features, you should be using Git feature branches so that your work is isolated from your teammates. This involves

• Creating a branch for a feature,
• Working on that feature until complete,
• Merging back to the main branch,
• Checking that all tests pass on main,
• Finally commiting your changes.

GitLab has a built-in workflow that automates the process of creating a branch. Clicking on this button in an open issue will automate creating a feature branch and associating it to the issue.

Code commits

You are expected to regularly commit your code to git.

It’s a good practice to write your code incrementally:

1. Write a unit test for the code you are going to write. This helps define your interfaces.
2. Write code to achieve what you wanted and which also makes your test pass.
3. Add more tests to cover a reasonable number of inputs.
4. Commit to git!
5. Iterate.

Your Git commit history should reflect the work that you did during the sprint, and a TA should easily be able to see what commit belongs to which issue. A good practice is to put your issue number in the commit message to make it easy to find later!