Our workflow

In past years, it has been hard to track what kind of work is going on at which point in time. To address this, we have decided to integrate the team's workflow more with our primary tool: GitHub. However, before we can go into detail on this, we need to discuss the general workflow.

How work is structured and defined

Roughly speaking, work is structured into three tiers:

1. Projects
2. Tasks
3. Subtasks

Projects are broad high level goals that are ultimately defined by the requirements for the pod to be functional. For example, one ofthe project is GUI. While a project should be understood by the other tech heads, it doesn't have to be as implementation oriented. Some projects, like Quality Assurance, are not tied to a particular section of code, but rather on the entire code base in general. Generally speaking, projects should take one or two semesters.

Tasks are then the building blocks of a project. They define what, in more or less rough terms, needs to be done to meet the project requirements. Everyone on the Software team should be able to understand what every individual task aims to achieve. There are a wide variety of possible tasks, e.g. Make sensors work with the Cruising state, Modernise code base, ... Roughly speaking, finishing a tasks should be a matter of weeks, not months.

Subtasks are the smallest unit of work. They should consist of specific changes that need to be made. They don't need to be easily understandable to each member of the Software team, but all members working on the same project should know what is being referred to. A subtask should rarely take more than a week to complete.

Who does what

Similar to the work itself, the Software team is also structured into three tiers:

1. Head of Software
2. Project Managers
3. Developers

Let's do this the other way around:

Developers do what you would expect them to: they come up with solutions to specific problems within a project and implement them. This implies all the aspects that come with code changes, i.e. code reviews, documentation and testing.

Project Managers are highly encouraged to do everything that every other developer is doing as well. It is up to them to decide how much they want to be involved in the low level development process. On top of that, they are responsible to oversee the completion of one or more projects. This means that they are required to define tasks and subtasks, distribute them amongst the team members and aid in sovling problems that will inevitably arise. Project Managers should always be aware what every member is working on and give relevant updates to the Head of Software. While PMs may not write as much code themselves, they should be more involved in code reviews than other members as they are likely to be more aware of the bigger picture.

The Head of Software is mainly responsible for the overall direction the Software team is taking. This means they will define (and redefine) projects and assist the PMs in setting the tasks that need to be finished. They will also give input on which aspects of each project should be prioritised, if necessary.

Note for 2022: I'm going to try and be as involved as possible with the actual code that is being written. Don't hesitate to contact me if you have any implementation-specific questions as this is what I'm truly interested in.

How we track our progress

Meetings

Meetings are a great place to discuss problems and opinions with other members of the Software team. However, to allow us to focus on these aspects over pure information, we expect everyone to be prepared. This includes updating the slides and reading everyone else's updates beforehand.

Technical Committee

The Head of Software will attend Technical Committee meetings once a week to discuss the progress that is being made in the Tech team as a whole. Relevant updates will be given in the Software meetings.

Software

At least once a week, we will have meetings with the entire Software team. This will be the time for the Head of Software and the PMs to present their updates to the rest of the team. These updates should be kept relevant for the audience. Discussions are mainly to gather opinions and ideas from all the members as well as to point out problems that have been encountered.

Project

Every project should have meetings twice a week to define subtasks until the next meeting, discuss the work that has been done on the subtasks from the previous meeting and address problems that have arisen.

GitHub

Issues

An issue can address anything that is potentially wrong with the code base. This can be anything from naming, over configuration to high level design issues. We encourage everyone to open an issue if they notice something noteworthy. However, there may be cases in which the Head of Software or the PMs decide that an issue is not relevant. In that case, they will leave a comment and close the issue. Reasons for that include:

1. Duplication. To avoid this, please have a look at the issues that have been opened before.
2. Non-issue. Sometimes members will consider things problematic that were designed that way for a specific reason. This is expected and should not stop members from mentioning such things in the first place. Opening issues and resolving them like this will give everyone more insight into our workflow.
3. Solution. Once an issue has been fixed in the code base, it can be closed.

Pull requests

A pull request should be aimed at solving a particular task or subtask. While we will not merge a PR containing only a partial solution, you should still open a PR from your branch into master as soon as possible. This achieves the following:

1. You document your work for the rest of the team.
2. You allow people to review and comment on your code. Don't worry that your code might not be up to par, because it won't be anyways. The sooner we start fixing it, the better.
3. You can identify merge issues.
4. You can reference GitHub issues and thereby indicate that they are being worked on.

Within a PR, you can request reviews from specific people. Here you should always include one member from your project as well as the Head of Software. If you are actively waiting on a review and don't get a response within 24 hours, feel free to ping the relevant people on Slack. It may also be a good idea to post your PR in an affected project's channel.

Labels

Both issues and PRs can be labelled. This allows users to filter by certain categories and also to determine the scope.

We currrently have the following labels:

• by affected code (more than one possible)
  • build-system
  • configuration
  • motor-controllers
  • navigation
  • sensors
  • state-machine
  • telemetry
• by type (more than one possible)
  • bug
  • documentation
  • feature
  • testing
  • research
  • quality-assurance
• by difficulty (issues ony)
  • easy
  • moderate
  • hard

You can also mark PRs with work-in-progress if they are not ready to be merged yet but you don't want to convert them to a draft to keep the CI running and to identify merge conflicts.

Don't worry too much about picking the right labels when creating a PR or an issue, the PMs and the Head of Software will take care of it.