/
Project Workflow Guide

Project Workflow Guide

Owned by Tommy Truong (Unlicensed)
Last updated: Aug 06, 2020
5 min read

Git workflow

For current git workflow, please refer to the CONTRIBUTING.md.

PR workflow

To write a PR, there is a format provided by a template when a PR is first being created. Please stick to this template to create consistency. In general a PR description should be linked to a Jira Ticket, have a brief and concise one liner in imperative language describing what will be done and a description that explains the context of the PR depending on what is being worked on.

  1. Functionality - explain the problem, why the solution was chosen, and any specifics that might be worth highlighting

  2. Refactoring - why there was a need for the change, how the changes address this problem, and steps to take to avoid the same mistakes (better documentation, another step in PR reviews, simplification of system design)

Please make PRs on one self-contained change. This is often a part of a feature and not a feature in and of itself. This is to ensure that reviews do not put to much of a strain on the reviewer.

Cognitive load increase is exponential relative to the number of changes done.

So a 300 line PR is a good starting point, seeing that we are still students and are often involved in other activities. Ultimately it is up to the team to decide (and decide quite quickly) what their ideal is based on their shared experience.

It only seems fitting that as we use Golang as our back-end language that we also use Google as our reference for good engineering practices especially when it comes to PR reviews. We will be following the guide https://github.com/google/eng-practices which states the general standard and reasoning behind the method we use.

Factors to review on:

  • Design: Is the code well-designed and appropriate for your system?

  • Functionality: Does the code behave as the author likely intended? Is the way the code behaves good for its users?

  • Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future?

  • Tests: Does the code have correct and well-designed automated tests?

  • Naming: Did the developer choose clear names for variables, classes, methods, etc.?

  • Comments: Are the comments clear and useful?

  • Style: Does the code follow our style guides?

  • Documentation: Did the developer also update relevant documentation?

Steps to take:

  1. Read the description of the PR written by the developer.

  2. Locate the most central file that implements the functionality needed. If confused, asked the developer for clarity, if not already stated in the PR.

  3. Check the file for the above requirements and make a (physical or mental) checklist, making note of where the PR falls short.

  4. Follow a logical sequence for the rest of the code and make sure those files are of similar quality.

  5. Write your review. When this is being done please keep a balance between writing directives and posing questions. It is often best to leave it to the developer to improve on the code. Provide alternatives if you are going to write directives.

Ideally, the PR should be linked to a ticker on our Jira system.

PRs should be reviewed and merged as soon as all checks pass and reviews given. Code review should be given priority over something that an individual developer is building. Good PRs should not take time away from a reviewer and hence can be the first thing to be completed in a days work. A practice that will be undertaken and trialled is the introduction of conducting reviews before a daily stand up so that points of contention can be brought up and talked about in standups.

An important quote from the document is

In general, reviewers should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn't perfect.

CL is defined by the document to be a change list synonymous with PRs. This is what we will achieve by following the PR workflow described. That is why the introduction of a nit: tag will be introduced for developers to distinguish what is a nitpick as to not dwell on making a PR ‘perfect’.

Jira Workflow

The current Jira workflow for creating tasks is a process of three steps.

  1. Create epics that frame the work that needs to be done. These epic stories should involve an introduction outlining the need and purpose of the epic story and specifications relating to the product and design requirements and any technical specifications/limitations placed on the feature.

  2. Using the user personas as a guide, create user stories with acceptance criteria. Please use the given/when/then format. Format down below.

  3. At every sprint meeting to decide what is to be done for the next sprint, choose user stories to do and create tickets (Jira task) for that user story. Remember to link the tasks with their user stories. When creating tickets please separate coding task from supporting task into subtasks and description/comment respectively. By this it means, that activities relating to specific coding elements for example building API should be a subtasks. And so any task that you may need to do should be in the comments or description for example read documentation on creating API.

At the beginning of the sprint make sure that you have estimated your tickets and add them to your sprint. To begin the sprint, go to the backlog and move tickets into the sprint and start it. As you progress make sure you are updating the progress of your task and move it across from To-do → In progress → Code Review → Done. Rinse and repeat until finished with all tasks, stories and epics. It is the role of the Team Lead to monitor the progress of tickets/tasks and to change their user stories accordingly

Examples

User stories

  • As a [user], I want [the something] so I can [the goal].

Acceptance criteria

  • Given [situation], when I [action] then [result].

Tickets/Tasks Example

  • Title: short, concise overview of the ticket.

  • Description: Concise information about the context of the task as well as anything that needs to be done not related to actual coding. Keep the ticket content focused on specific commands (command language like Add, Update, Build etc) to help communicate to our developers how you’d like the issue to be changed.

  • Type: Its either a task, blocker, bug or improvement.

  • Subtask: Use if a task requires you to remember a specific aspect of the code that needs to be done. E.g. “Refactor sponsor database operations” and not “Read API documentation”.