Skip to content

Developer Guide

Jump to bottom
Chloe edited this page May 12, 2024 · 4 revisions

The Non-Negotiables

  • The main branch must always be functional and well-documented.
  • Protect main (pull-request only! We only accept our own pull-requests in case of emergency).
    • Emergencies are defined as critical bugs that impact production and require immediate resolution to prevent significant user impact or data loss.
  • Prioritize reviewing our team-mates' pull-requests.
  • Wait for review and then merge with squash.

Collaboration Guide

Choosing Issues to Work On in the Future

While issues are not currently used, outlining their future management is beneficial:

  • Team members will self-assign tickets. When in doubt, do not assign tickets to others.
  • Encourage proactive selection and updating of issues:
    • Comment on your engagement with an issue and provide regular updates.
    • Aim to complete one issue before taking on another.
  • Record time spent on issues to aid in future task estimation.

Issue Management Introduction

While we could not set this in place yet, planning for the introduction of issue management is essential to optimize the efficiency of our project.

Issue Creation

  • Title and Description: Ensure each issue includes a concise title and a detailed description with steps to reproduce, expected vs. actual results, and any relevant context or screenshots.
  • Categorization: Apply labels such as bug, feature, or documentation to categorize issues.
  • Severity and Impact: Assess and note the severity and potential impact of the issue on the project.

Issue Prioritization

  • Urgency and Impact: Evaluate how the issue's urgency and impact affect project timelines and functionality.
  • Dependencies: Prioritize issues based on their dependencies to streamline project workflow.

Resolution Process

  • Assignment: Assign issues based on individual expertise, interest, and workload.
  • Progress Updates: Maintain transparency with regular updates on issue status.
  • Review Process: Conduct a review process for issue resolution, either through code reviews, testing, or demos before closure.

About Code Reviews

Conduct thorough reviews, especially when:

  • Merging a feature branch to main.
  • A bug fix is ready for merge from a hotfix/bugfix branch to main.

Code Reviewing Guideline

  • Main Reviewer: Assign a main reviewer for each issue to streamline the review process.
  • Change Requests: Use the suggest a change feature to specify desired changes.
- **Approval Process**: - `Approved`: Mark with `LGTM` if no issues are found. - `Rejected`: Clearly state necessary fixes or reasons for rejection. - The main reviewer is responsible for merging and deleting the `feature branch`.

Code Reviews Checklist

  • It's beneficial to review more frequently in smaller chunks to minimize integration issues.
  • Ensure that the person responsible for the testing is not the same as the reviewer to maintain objectivity.

To help make the process more streamlined, you can use the following checklist:

Functionality

  • Does the code work as intended without any errors?
  • Has the new feature been tested and are there any potential side effects?

Code Quality

  • Are functions/methods well-organized and divided?
  • Does the code follow our coding standards and best practices?
  • Is the code clean and easy to understand?

Documentation

  • Is all new code accompanied by neccessary comments?
  • Has the documentation been updated to reflect the changes?

Security

  • Does the change introduce any security problems?
  • Are all data inputs properly sanitized?
  • Are there security checks in place?

Final Decision

  • Approve
  • Request changes
  • Reject

Handling Conflicts in Code Reviews

Disagreements during code reviews can happen, but they can also lead to a better outcome if handled correctly:

  • Seek a Third Opinion: If there is a heavy disagreement happening between reviewers, involve a third team member to provide a new perspective.
  • Escalate When Neccessary: If significant issues occur, that cannot be resolved, escalate to a project lead or our supervisor for a decision.
  • Discussion Meeting: If necessary, bring up the issue during our weekly meetings or schedule a short meeting to discuss the disagreement, making sure everyone can express their views and reach an agreement.

Asynchronous Communication

  • Utilize Slack for daily communications and asynchronous discussions. Keep threads organized and focused to ensure that all discussions are understandable and traceable.
  • Use pinned messages to specific topics or features to maintain clarity and accessibility of important information.

Resources

I quite like this code review guideline, and I highly recommend reading through it.

Clone this wiki locally