DEV Community: Rusydy

Conquering System Design Diagrams: My Shift to Mermaid.js

Rusydy — Sat, 30 Mar 2024 04:58:35 +0000

Diagrams are the cornerstone of software development, illuminating complex systems and fostering clear communication. However, traditional diagramming tools often lack crucial features, hindering efficient system design documentation.

My workflow previously relied on draw.io, a great tool for creating simple diagrams with its intuitive interface and extensive shape library. However, managing intricate system designs became cumbersome. Frequent revisions meant manually updating the entire diagram, leading to version control issues and lost design context.

Here's how Mermaid.js revolutionized my diagramming journey:

1. Embracing Version Control with Mermaid.js:

Mermaid.js, a text-based diagramming tool, revolutionized my approach. Its seamless integration with Git ensures meticulous version control. Every change is meticulously tracked, allowing me to revisit previous design iterations effortlessly. This eliminates confusion and streamlines design decision recall.

2. More Control and Collaboration:

Unlike cloud-based tools, Mermaid.js empowers local file management. Diagrams reside directly on my machine, integrating flawlessly with Git for version control. Additionally, embedding diagrams within Markdown files fosters collaborative workflows. Teams can access the latest version and contribute edits directly on GitHub, boosting efficiency by working on a single source of truth.

3. Simplicity Breeds Power:

Mermaid.js utilizes a clear and concise text-based syntax, making it remarkably user-friendly. While seemingly simple, it offers a robust set of features, generating a wide array of diagrams, from flowcharts and sequence diagrams to class diagrams and even pie charts. This flexibility caters to various diagramming needs within system design.

4. Enhancing Workflow with VS Code (Optional):

The VS Code extension for Mermaid.js further streamlines the process. Once installed, creating diagrams becomes effortless within Markdown files. Code blocks designated with the "mermaid" language allow you to write your diagram code. The extension offers optional features like real-time preview, enabling you to visualize changes as you write. Additionally, editing the code within VS Code automatically updates the preview, facilitating efficient iteration.

In conclusion, Mermaid.js has transformed my diagramming workflow, offering a seamless and collaborative approach to system design documentation. By leveraging local control, version control, and real-time collaboration, I've transitioned from diagramming frustration to clarity and efficiency.

Here are some resources to get you started:

Official Website: https://mermaid.js.org/
Interactive Tutorial: https://github.com/mermaid-js/mermaid-live-editor
VS Code Extension:
- Markdown Preview Mermaid Support
- Mermaid Markdown Syntax Highlighting
Example Repository: Diagram as Code

Using LUTs (Look-Up Tables) Data Structures to simplify code’s logic and more

Rusydy — Sat, 30 Dec 2023 07:06:38 +0000

Issues

When I was working on a feature to check the transaction’s status from a third-party service, I had to deal with plenty of possible combinations of values that could be returned by the service. The code was getting more and more complex, with each response status have its own description and action to be taken. Here is a simplified version of the code:



func (s *thirdParty) CheckTransactionStatus(
    /* request */ ctx context.Context, request CheckTransactionStatusRequest) (
    /* response */ response CheckTransactionStatusResponse, httpStatusCode int, err error,
) {
    resp, err := s.client.CheckTransactionStatus(ctx, request)
    if err != nil {
        return response, http.StatusInternalServerError, err
    }

    switch resp.Status {
        case "SUCCESS":
            return response, http.StatusOK, nil
        case "PENDING":
            return response, http.StatusAccepted, nil
        case "FAILED":
            return response, http.StatusBadGateway, nil
        case "REJECTED":
            return response, http.StatusForbidden, nil
        case "CANCELLED":
            return response, http.StatusGone, nil
        case "EXPIRED":
            return response, http.StatusGone, nil
        case "REFUNDED":
            return response, http.StatusGone, nil
        case "CHARGEBACK":
            return response, http.StatusGone, nil
        case "ERROR":
            return response, http.StatusBadGateway, nil
        default:
            return response, http.StatusInternalServerError, errors.New("unknown status")   
    }
}

The code above was performing many conditional checks to return the correct HTTP status code. It also had a lot of duplicated code. That makes me ask myself;

what if I need to add a new status code?
what if I need to add a new description? Or action to be taken?
can I add in-depth logging to the code? And update it easily in the future?

Solution

I decided to use a LUT (Look-Up Table) data structure to simplify the code’s logic. The LUT is a data structure that associates keys with values. It is a simple way to replace a lot of if/else statements or switch/case statements.

Phase 1: Using a LUT to replace if/else statements



var transactionStatus = map[string]int{
    "SUCCESS": http.StatusOK,
    "PENDING": http.StatusAccepted,
    "FAILED": http.StatusBadGateway,
    "REJECTED": http.StatusForbidden,
    "CANCELLED": http.StatusGone,
    "EXPIRED": http.StatusGone,
    "REFUNDED": http.StatusGone,
    "CHARGEBACK": http.StatusGone,
    "ERROR": http.StatusBadGateway,
}

func (s *thirdParty) CheckTransactionStatus(
    /* request */ ctx context.Context, request CheckTransactionStatusRequest) (
    /* response */ response CheckTransactionStatusResponse, httpStatusCode int, err error,
) {
    resp, err := s.client.CheckTransactionStatus(ctx, request)
    if err != nil {
        return response, http.StatusInternalServerError, err
    }

    httpStatusCode, found := transactionStatus[resp.Status]
    if !found {
        return response, http.StatusInternalServerError, errors.New("unknown status")
    }

    return response, httpStatusCode, nil
}

The code above is a lot simpler than the previous one. It is also easier to add a new status code.

Phase 2: Using a LUT to add in-depth logging



var transactionStatus = map[string]struct {

    httpStatusCode int

    logLevel       string

    description    string

}{

    "SUCCESS": {

        httpStatusCode: http.StatusOK,

        logLevel:       "info",

        description:    "transaction was successful",

    },

    "PENDING": {

        httpStatusCode: http.StatusAccepted,

        logLevel:       "info",

        description:    "transaction is pending",

    },

    "FAILED": {

        httpStatusCode: http.StatusBadGateway,

        logLevel:       "error",

        description:    "transaction failed",

    },

    "REJECTED": {

        httpStatusCode: http.StatusForbidden,

        logLevel:       "error",

        description:    "transaction was rejected",

    },

    "CANCELLED": {

        httpStatusCode: http.StatusGone,

        logLevel:       "error",

        description:    "transaction was cancelled",

    },

    "EXPIRED": {

        httpStatusCode: http.StatusGone,

        logLevel:       "error",

        description:    "transaction was expired",

    },

    "REFUNDED": {

        httpStatusCode: http.StatusGone,

        logLevel:       "error",

        description:    "transaction was refunded",

    },

    "CHARGEBACK": {

        httpStatusCode: http.StatusGone,

        logLevel:       "error",

        description:    "transaction was charged back",

    },

    "ERROR": {

        httpStatusCode: http.StatusBadGateway,

        logLevel:       "error",

        description:    "transaction had an error",

    },

}

func (s *thirdParty) CheckTransactionStatus(

    ctx context.Context, request CheckTransactionStatusRequest) (

    response CheckTransactionStatusResponse, httpStatusCode int, err error,

) {

    resp, err := s.client.CheckTransactionStatus(ctx, request)

    if err != nil {

        return response, http.StatusInternalServerError, err

    }

<span class="n">status</span><span class="p">,</span> <span class="n">found</span> <span class="o">:=</span> <span class="n">transactionStatus</span><span class="p">[</span><span class="n">resp</span><span class="o">.</span><span class="n">Status</span><span class="p">]</span>
<span class="k">if</span> <span class="o">!</span><span class="n">found</span> <span class="p">{</span>
    <span class="k">return</span> <span class="n">response</span><span class="p">,</span> <span class="n">http</span><span class="o">.</span><span class="n">StatusInternalServerError</span><span class="p">,</span> <span class="n">errors</span><span class="o">.</span><span class="n">New</span><span class="p">(</span><span class="s">"unknown status"</span><span class="p">)</span>
<span class="p">}</span>

<span class="k">return</span> <span class="n">response</span><span class="p">,</span> <span class="n">status</span><span class="o">.</span><span class="n">httpStatusCode</span><span class="p">,</span> <span class="no">nil</span>



}

Pros and Cons

Like any other data structure, LUTs have their pros and cons.

Pros

Fast Retrieval:
- Look-up tables provide constant-time average complexity for retrieving values based on a key. This makes them very efficient for large datasets.
Memory Efficiency:
- Look-up tables can be memory-efficient, especially when dealing with sparse data. They only store values for existing keys, reducing memory overhead.
Simplifies Code:
- Using a look-up table can make code more readable and maintainable. It centralizes related information and makes it easy to update or extend.
Pre-computation:
- Look-up tables allow for pre-computation and storage of results, reducing the need for recalculations. This is beneficial in scenarios where certain values are repeatedly used.
Flexible Key-Value Mapping:
- The key-value nature of a look-up table allows for flexible mappings, supporting a wide range of use cases from configuration settings to status code mappings.

Cons

Memory Overhead:
- In scenarios where the key space is large or continuous, a look-up table might consume more memory than alternative data structures with more memory-efficient representations.
Limited Sorting:
- Look-up tables are inherently unordered, and sorting based on keys may require additional data structures or steps.
Limited Range Queries:
- If you need to perform range queries on keys, look-up tables might not be the most suitable data structure, and alternatives like trees might be more appropriate.

Conclusion

Look-up tables are a simple and powerful data structure that can be used to simplify code logic. They are fast, memory-efficient, and flexible. They can be used in a wide range of use cases, from configuration settings to status code mappings. However, they are not suitable for all scenarios, and you should consider the pros and cons before using them.

Enhancing Code Quality and Maintainability

Rusydy — Thu, 02 Nov 2023 08:21:53 +0000

Software development is an evolving field, and it's crucial to continually improve our coding practices to maintain high code quality and ensure maintainability. In this article, we'll discuss a set of practices for writing cleaner and more maintainable code. I'll use Go as the programming language for the examples, but these practices can be applied to any language.

1. Enhance Code Organization by Separation of Concerns.

When writing Go code, it's essential to create a clear separation of concerns without making the code overly complex. To achieve this, follow these steps:

Step 1: Splitting Functions

Start by breaking down a large function into smaller, more manageable steps. For example, consider a function that processes a user's transaction. Split it into separate functions for validation, processing, and error handling.



func processTransaction(user User, transaction Transaction) error {
    if err := validateTransaction(transaction); err != nil {
        return err
    }

    if err := processTransactionInternal(user, transaction); err != nil {
        return err
    }

    return nil
}

Step 2: Separate Functions

Rewrite these individual steps as their functions in separate files. For instance, move the validateTransaction and processTransactionInternal functions into their respective files.



├── main.go
├── transaction
│   ├── process.go # processTransaction
│   ├── validate.go # validateTransaction
│   └── internal.go # processTransactionInternal
└── user
    └── process.go

Step 3: Validation as First Concern

Always prioritize validation as the initial step in each function. Group validations based on their specific purpose, such as request validation, user validation, and VCN validation. Each validation should have its own dedicated function with well-defined request and response structures.



func validateTransaction(transaction Transaction) error {
    // Validation logic here
}

func validateUser(user User) error {
    // User validation logic
}

func validateVCN(vcn string) error {
    // VCN validation logic
}

Step 4: Proper Error Handling

Ensure that all potential errors are handled effectively. This means checking for errors and returning them, rather than ignoring or suppressing them.



 vcn, httpCode, err := x.validateVCNsPrecondition(ctx, neoPG, payloadValidateVCNsPrecondition, log, now)
 if err != nil {
  return response, httpCode, err
 }

2. Optimize Conditional Statements by Variable Declarations.

When you encounter lengthy expressions inside if statements, consider declaring those expressions as variables and then using the variables within the if statements. This makes the code more readable, self-documented and easier to maintain.



func isEligibleToVote(age int) bool {
    // Lengthy expression
    if age >= 18 && age <= 120 {
        return true
    }
    return false
}

Rewrite it with variable declarations for improved readability:



func isEligibleToVote(age int) bool {
    isAgeValid := age >= 18 && age <= 120
    return isAgeValid
}

3. Minimize Reliance on Comments.

Meaningful function and variable naming can significantly reduce the need for excessive comments. While comments are helpful, they can sometimes become outdated or misleading. Therefore, it's best to rely on self-explanatory naming conventions. For example:



// Avoid
func calculateTax(income float64) float64 {
    // Calculate the tax of income
    // ...

    return tax
}

// Prefer
func calculateIncomeTax(income float64) float64 {
    // ...

    return tax
}

4. Effective Error Logging.

When dealing with error logging, it's crucial to classify errors correctly:

For 5XX errors, include an identifier such as the user ID or card number in the interface to simplify future investigation.
For non-5XX errors that may be valuable for analytical purposes, log them for analysis.
For other predefined errors, consider error logging as optional, as these cases are typically predetermined.



func processTransaction(user User, transaction Transaction) error {
    if err := validateTransaction(transaction); err != nil {
        log.Err(err).
        Interface("request", request).
        Interface("response", response).
        Msg(LABEL + " - validateTransaction")

        return err
    }

    if err := processTransactionInternal(user, transaction); err != nil {
        log.Err(err).
        Interface("request", request).
        Interface("response", response).
        Msg(LABEL + " - processTransactionInternal")

        return err
    }

    return nil
}

Incorporating these practices into your code can significantly enhance its quality and maintainability. Remember that clean, well-organized code is not only easier to work with, but also benefits the entire development team by reducing bugs and making the codebase more understandable and efficient.

The Ease of Force-Pushing and GitHub's Safety Net

Rusydy — Mon, 11 Sep 2023 01:46:47 +0000

Last night, I made an intriguing discovery about the intricacies of git commit amending that, I believe, is worth sharing.

It turns out that once you've amended a git commit, the conventional git pull and git push commands won't work as expected. This quirk arises due to the inherent discrepancy between the local and the remote repositories once a commit has been amended. In most cases, the local repository is regarded as the source of truth, requiring the remote repository to align with it.

To illustrate this concept, consider a recent real-world scenario: I decided to remove three commits from my pull request. As anticipated, a divergence emerged between my local and remote repositories. Typically, I would have instinctively used git push -f to forcefully push these changes to the remote. However, I received advice against following my muscle memory and instead opted for the traditional approach of executing git pull, followed by git push. To my astonishment, the remote repository still retained the three commits I had removed.

Now, I couldn't help but reflect on why my previous teams resorted to using force-pushes so frequently. However, it's important to note that there's no need for concern regarding the potential loss of tracking before and after a force-push. GitHub has an effective record-keeping system that ensures your repository's history remains intact.

Why Developers Should Learn Vim: Crucial Use Cases and Real-World Scenarios

Rusydy — Sun, 10 Sep 2023 07:14:33 +0000

Developers often face the dilemma of choosing the right text editor or Integrated Development Environment (IDE) for their coding tasks. Among the many options available, Vim stands out as a versatile and efficient text editor that offers several advantages for developers.

In this article, we'll explore why developers should consider learning Vim, delve into cases where Vim is crucial, and provide a real-world scenario highlighting its importance.

Why Learn Vim?

1. Efficiency

One of the primary reasons developers should consider learning Vim is its exceptional efficiency in text editing tasks. Vim's modal editing system, extensive keyboard shortcuts, and powerful text manipulation commands allow users to perform complex editing operations with speed and precision. Once you become proficient with Vim, you'll find yourself completing tasks faster than you would with traditional text editors.

2. Portability

Vim is available on most Unix-based systems, including Linux and macOS. This portability ensures that your Vim skills remain relevant and usable across various platforms. Whether you're working on your local development machine or a remote server, you can count on Vim to be available.

3. Lightweight

Vim is renowned for its lightweight nature. It starts quickly and uses minimal system resources, making it an excellent choice for developers who want to conserve system resources or work on older hardware without sacrificing performance.

4. Customizability

Vim is highly customizable, allowing you to tailor it to your specific workflow and preferences. You can configure keybindings, install plugins, and create custom macros, making Vim adaptable to a wide range of development tasks and programming languages.

5. Command-Line Integration

Vim seamlessly integrates with the command line, enabling developers to edit files directly from the terminal. This feature is particularly useful for making quick code changes or editing configuration files without leaving the command line environment.

6. Remote Editing

Vim's lightweight nature and command-line integration make it an invaluable tool for remote editing tasks, especially via SSH (Secure Shell). You can edit files on remote servers efficiently, ensuring that you can manage configurations or code remotely with ease.

Crucial Use Cases for Vim

Now, let's explore some crucial use cases where Vim shines:

Scenario: Remote Server Configuration Edits

Imagine you are a system administrator responsible for maintaining a web server hosted on a remote Linux machine. You receive an urgent request to update the server's configuration file to resolve a critical issue. Here's why Vim becomes crucial in this scenario:

Speed: Vim launches quickly and operates efficiently, even on remote servers with limited resources. This is crucial when you need to make swift changes.
Minimal Overhead: Vim's lightweight nature ensures it won't burden the server's resources, allowing you to focus on the task at hand.
Remote Editing: Vim's seamless integration with the command line lets you edit files directly on the remote server. You can SSH into the server, open the configuration file with Vim, make the necessary changes, and save the file—all without the need for a graphical user interface.
Reliability: Vim is a robust and dependable text editor. You can trust it to work consistently, which is essential when dealing with critical configuration files.

By leveraging Vim in this scenario, you can efficiently and reliably update server configurations, contributing to the smooth operation of your web server and minimizing downtime.

Learning Vim is a valuable investment for developers due to its efficiency, portability, lightweight nature, customizability, command-line integration, and suitability for remote editing. In real-world scenarios, such as making critical edits to remote server configuration files, Vim's capabilities shine, making it a crucial tool for developers across various domains.

Setting Up a .NET Project on macOS

Rusydy — Sun, 10 Sep 2023 02:53:12 +0000

If you're a macOS user looking to set up a .NET project, follow these steps to get started with creating a web API project using .NET Core. This guide will walk you through the process, from ensuring you have .NET Core installed to creating a model and generating a controller with CRUD (Create, Read, Update, Delete) actions.

Step 1: Verify .NET Core Installation

Before you begin, make sure you have .NET Core installed on your macOS. Open your terminal and run the following command to check if it's already installed:



dotnet --version

If you don't have .NET Core installed, you can follow the steps in this guide to install it on your macOS Setup .Net on Mac.

Step 2: Create a New Web API Project

Let's start by creating a new web API project. Open your terminal and run the following command to create a new project named "RestApi":



dotnet new webapi -n RestApi

This command sets up a basic web API project structure for you to build upon.

Step 3: Install Required Dependencies

Code Generation

For code generation, we need to install the dotnet-aspnet-codegenerator tool. Run the following command:



dotnet tool install -g dotnet-aspnet-codegenerator

Next, add the Microsoft Visual Studio Web Code Generation Design package:



dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design

Entity Framework

If you plan to use Entity Framework, you'll need to add the required packages. Run the following commands to add Entity Framework and the SQL Server provider:



dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Microsoft.EntityFrameworkCore.SqlServer

These packages are essential for database operations in your .NET project.

Step 4: Create a Model

In your project's Models folder, create a new class named Recipe.cs. You can use the following code as a starting point:



using System;

namespace RestApi.Models
{
    public class Recipe
    {
        public int Id { get; set; }
        public string Name { get; set; }
        // Add other properties as needed
    }
}

This class represents a basic model for your application. You can add additional properties as required for your specific project.

Step 5: Generate a Controller

Now, you can generate a controller with CRUD actions and views using the code generator. Run the following command:



dotnet aspnet-codegenerator controller -name RecipesController -async -api -m Recipe -dc ApplicationDbContext

This command generates a controller named RecipesController with all the necessary CRUD actions and views. You can customize this controller to suit your project's requirements.

That's it! You've successfully set up a .NET web API project on your macOS machine, created a model, and generated a controller to handle your application's functionality. You can now start building your application by adding business logic and further customizing your project as needed.

Setting Up .NET on macOS: A Step-by-Step Guide

Rusydy — Sat, 09 Sep 2023 07:41:28 +0000

Microsoft's .NET platform is a versatile and powerful framework for developing a wide range of applications, from web and mobile to desktop and cloud-based solutions. If you're a macOS user and want to start working with .NET, you're in the right place. In this guide, we'll walk you through the steps to set up .NET on your macOS.

Prerequisites

Before you begin, ensure that your macOS version meets the system requirements for .NET. You'll also need an internet connection to download the necessary components.

Step 1: Install Homebrew

Homebrew is a popular package manager for macOS that simplifies the installation of various software packages, including .NET. If you don't have Homebrew installed, follow these steps to get it:

Open Terminal, which you can find in the “Utilities” folder within the “Applications” directory.
Install Homebrew by running the following command:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Follow the on-screen instructions to complete the Homebrew installation.

Step 2: Install .NET SDK

The .NET Software Development Kit (SDK) contains everything you need to build and run .NET applications. With Homebrew installed, you can easily install the .NET SDK:

In Terminal, run the following command to install the .NET SDK:
```
brew install --cask dotnet-sdk
```
Homebrew will download and install the .NET SDK for you. This might take a few minutes, depending on your internet speed.

Step 3: Verify Installation

After the installation is complete, you can verify that .NET is installed correctly by running the following command in Terminal:

dotnet --version

This command should display the version of the .NET SDK that was installed.

Step 4: Optional – Install Visual Studio Code

While you can use any text editor or integrated development environment (IDE) for .NET development, Visual Studio Code (VS Code) is a popular choice due to its excellent support for .NET development. You can install it from the macOS App Store or by downloading it from the official website.

Step 5: Create a New .NET Project

Now that you have .NET installed on your macOS, you can create and run your first .NET application. Follow these steps to create a simple “Hello World” application:

Open Terminal and navigate to the directory where you want to create your project.
Create a new directory for your project and navigate into it. For example:
```
mkdir MyDotNetApp
cd MyDotNetApp
```
Use the following commands to create a new console application, build it, and run it:
```
dotnet new console
dotnet run
```
You should see “Hello World!” printed on the terminal, indicating that your .NET application is working correctly.

Congratulations! You've successfully set up .NET on your macOS machine and created your first .NET application.

Now you're ready to explore the world of .NET development on macOS. You can use Visual Studio Code or your preferred code editor to build various types of applications, including web applications using ASP.NET, cross-platform desktop applications using .NET MAUI or Xamarin, and more. The .NET ecosystem offers a wide range of tools and libraries to help you develop powerful and feature-rich applications. Happy coding!

CLEAN GIT: Pushing Local Changes to Remote Repository Using Git

Rusydy — Fri, 08 Sep 2023 19:02:09 +0000

In this Standard Operating Procedure (SOP), we will walk through the process of applying CLEAN GIT principles to efficiently push our local code changes to a remote repository. This SOP assumes a Git flow with branches such as staging, local/feature, UAT, and main. It also covers scenarios where code changes may require adjustments during the review process.

Git Flow Overview

Our Git workflow involves the following branches:

local/feature: This branch is dedicated to feature development.
main: The main branch serves as the central location for all integrated features.
staging: QA tests features from the main branch.
UAT: This branch is available for client testing.
PROD: The production-ready branch.

It's important to note that while the main branch may contain untested features, the staging branch is reserved for QA-tested features.

Pushing Local Changes to Remote Repository

Let's delve into the steps of applying CLEAN GIT principles when pushing local code changes to the remote repository.

Step 1: Create a New Branch

Start by creating a new branch for your feature. In this example, we'll name it feature/TICKET-1234.



git checkout main
git pull
git checkout -b feature/TICKET-1234

Step 2: Develop the Feature

Develop your feature by adding or modifying files. In this instance, we create a new file called feature.txt and add content to it.



echo "This is a feature" > feature.txt

Step 3: Commit the Changes

Commit your changes to the local repository.



git add feature.txt
git commit

This will open your default text editor. You can use vim or another text editor to compose your commit message. For example:



[TICKET-1234]: Add feature.txt

Previously, we did not have a feature.txt file in the repository.

In this commit, we add the feature.txt file to the repository.

Thus, we can now use the feature.txt file.

Step 4: Fetch and Rebase the Latest Changes

Retrieve the latest changes from the remote repository and rebase your changes onto them.



git fetch --all --tags
git rebase -i --autosquash origin/main

This will open your default text editor. For example:



pick 1a2b3c4 [TICKET-1234]: Add feature.txt

Step 5: Push the Changes to the Remote Repository

Push your changes to the remote repository.



git push -u origin feature/TICKET-1234

Step 6: Create a Pull Request

Now, create a pull request to merge your changes into the main branch.

Handling Reviewer-Requested Changes

Major Changes with the Same Technical Decision

If the reviewer requests significant changes but the technical approach remains the same, you can amend your commit after making the necessary adjustments.



git add feature.txt
git commit --amend

Update the commit message to reflect the changes:



[TICKET-1234]: Add feature.txt

Previously, we did not have a feature.txt file in the repository.

In this commit, we add the feature.txt file to the repository.

Thus, we can now use the feature.txt file.

Major Changes with a Different Technical Decision

In case the reviewer requests substantial changes that involve a different technical approach, create a new commit to incorporate the new decision.



git add feature.txt

git commit

Minor Changes

For minor adjustments requested by the reviewer, you can amend the existing commit without changing the commit message:



git add feature.txt

git commit --amend --no-edit

Conclusion

In this SOP, we've outlined the CLEAN GIT principles for pushing local code changes to a remote repository. We've also covered how to handle reviewer-requested changes efficiently. In our next SOP, we'll explore how to apply CLEAN GIT principles to address hotfix requests in a production environment.

Clean Git: Self-Documented Project

Rusydy — Wed, 06 Sep 2023 21:52:11 +0000

Why Should We Care About Git Commit Messages and PR Descriptions?

Real-world example:

Imagine this scenario: your team discovers a critical bug in your production environment. This bug is traced back to a change made by a developer who is no longer with the company. To resolve the issue, you need to adjust a SQL query file. The catch? You have no idea why this change was made in the first place. The commit message, PR description, ticket description, and even the code itself offer no clues. You're left scratching your head.

The result? Countless hours spent deciphering the change and fixing the bug. However, if the commit message, PR description, ticket description, and code were well-documented, you could resolve the issue swiftly.

So, What Makes a Good Commit Message and PR Description?

While there's no rigid standard for good commit messages and PR descriptions, following these guidelines can significantly improve your documentation:

Be Self-Documenting, Descriptive, and Concise: Your commit message and PR description should explain the change without requiring readers to dive into the code. Clearly state the reason behind the change and the technical decisions involved in a brief and clear manner.
Ideal Structure:

Commit Message



[branch-name]: <commit-message> Describe your changes briefly

<commit-description> Provide detailed information about the commit, including:
   <pre-commit-description> Explain the problem this commit addresses
   <commit-changes> Detail the changes made in this commit
   <post-commit-description> Describe the impact of this commit

Example:

PR Description



[branch-name]: <PR-title> Describe your changes briefly

<PR-description> Provide detailed information about the PR, including:
    <pre-PR-description> Explain the problem this PR addresses
    <PR-changes> Detail the changes made in this PR
    <post-PR-description> Describe the impact of this PR

Focus on a Single Aspect: Each commit should centre on a single technical decision. If a change is linked to a ticket, the commit shouldn't include the ticket description, as that focuses on product and feature details, not the technical decision. Avoid duplicating code in the commit message, since the code is self-documenting.
Squash Multiple Commits: When multiple commits are required for a change, consolidate them into one commit before merging into the main branch. Update the commit message and PR description to reflect the change.
Split Multiple Changes: If a ticket involves multiple changes, separate them into distinct commits. Each commit should address one technical decision, and accordingly, the commit message and PR description should be updated.

Incorporating these guidelines into your Git workflow will enhance clarity, save time, and make it easier to maintain your codebase.

Git Rebase: How to Handle Request for Changes to Specific Commits

Rusydy — Sun, 19 Feb 2023 08:08:17 +0000

Introduction

After completing my feature branch, I created a pull request to merge my changes into the master branch. However, I received feedback from a reviewer who suggested changes to my code. To address this, I need to make the following updates:

In my pull request, there are three commits. For the second commit, I need to remove a few files and make substantial changes to one file.
I also have to merge the third commit into the first commit, but I want to keep the second commit unchanged.

Solution

first problem: Updating a Specific Commit

Suppose we have three commits in our pull request, and we have to update the second commit by removing some files and making significant changes to one file.

Here are the steps to address this:

First, make sure we are on the branch that contains the three commits. We can check this by running git log and making sure we see all three commits listed.
Next, run git rebase -i HEAD~3. This will open an editor with the last three commits listed.
Change the word pick to edit on the line that corresponds to the second commit. Save and close the editor.
Git will then start the interactive rebase. It will stop at the second commit and give us a shell to work on. We can now make any changes we want to the second commit. When we are done, run git add to add the changes to the staging area.
Use git commit --amend to commit the changes to the second commit. We can change the commit message if we'd like to.
Finally, use git rebase --continue to resume the interactive rebase and apply the changes to the remaining commits.

This will leave we with three commits, but the second commit will have the changes we made.

second problem: Merging Commits while Keeping One Untouched

Suppose we also need to merge the third commit into the first commit, but we want to keep the second commit unchanged. Here are the steps to address this:

Same as before, make sure we are on the branch that contains the three commits. We can check this by running git log and making sure we see all three commits listed.
Run git rebase -i HEAD~3. This will open an editor with the last three commits listed.

In the text editor, change the position of the third commit so that it's above the second commit.

For example:

pick 1a2b3c4 First commit
pick 2a3b4c5 Second commit
pick 3a4b5c6 Third commit

becomes

pick 1a2b3c4 First commit
pick 3a4b5c6 Third commit
pick 2a3b4c5 Second commit

Change the word pick to squash on the line that corresponds to the third commit.

pick 1a2b3c4 First commit
squash 3a4b5c6 Third commit
pick 2a3b4c5 Second commit

Save and close the editor.
Git will combine the changes from the first and third commits into a single commit. We will be prompted to enter a new commit message for the merged commit. Edit the message as desired and save it.
Once the merge commit message is saved, the interactive rebase process will complete and the new commit will be added to the repository.

The result will be two commits, the first with the changes from the first and third commits, and the second with the changes from the second commit.

Conclusion

This is a compelling tool that can be used to change the history of our repository. It's important to understand how it works and how to use it properly. If we are not confident, we can always run git reflog to see the history of our repository. This will show us the history of all the commits, even if they've been removed from the repository.

Introduction to Colima

Rusydy — Thu, 09 Feb 2023 05:23:30 +0000

Docker has become a popular tool for developers and sysadmins to manage and deploy applications. However, sometimes Docker may get stuck in the "starting" stage or the Docker daemon may not start, causing frustration for the users. In such cases, Colima can be a useful alternative. In this article, we will provide a step-by-step guide on how to install and start Colima.

Installing Colima

To install Colima, we will use Homebrew, a package manager for macOS. If you don't have Homebrew installed, you can follow the instructions on the Homebrew website to install it.

Once you have Homebrew installed, you can use the following command to install Colima:



brew install colima

Starting Colima

After installing Colima, you can start it using the following command:



colima start

Conclusion

Colima is a useful alternative for users who are facing issues with Docker. It provides a simple and straightforward way to install and start applications. For more information, you can visit the Colima repository on GitHub at https://github.com/abiosoft/colima.

Python Unittest for Beginners: How to use HTMLTestRunner to generate test reports

Rusydy — Sun, 05 Feb 2023 20:58:10 +0000

In this article, we will go over the process of generating test reports using the unittest framework in Python. We will use the HTMLTestRunner library to generate HTML reports for our tests.

Setup HTMLTestRunner

The HTMLTestRunner library is a third-party library that extends the unittest framework to generate HTML reports for our tests. It is available on GitHub-findyou or GitHub-Rusydy. Just download or copy-paste the file and put it in the same directory as your test file.

Using HTMLTestRunner

To use HTMLTestRunner to create an HTML report for your tests, you need to write your test cases using the unittest library, and then use HTMLTestRunner to run your test cases and generate the HTML report. Here's an example:

initiate a test case class that inherits from unittest.TestCase

class MyTestCase(unittest.TestCase):
    def setUp(self):
        pass

    def tearDown(self):
        pass

    def testCase1(self):
        self.assertEqual(2,2,"testError")

    # The following test case will fail
    def testCase2(self):
        self.assertEqual(2,3,"testError")

    def testCase3(self):
        self.assertEqual(2,5,"测试错误")  # en: test error

    def testCase4(self):
        self.assertEqual(2,1,"测试错误")
    # The upper test case will fail

    def testCase5(self):
        pass

create a test suite and add the test cases to the test suite

# 添加Suite, en: add Suite
def Suite():

    #定义一个单元测试容器, en: define a unit test container
    suiteTest = unittest.TestSuite()

    #将测试用例加入到容器, en: add test cases to the container
    suiteTest.addTest(MyTestCase("testCase1"))
    suiteTest.addTest(MyTestCase("testCase2"))
    suiteTest.addTest(MyTestCase("testCase3"))
    suiteTest.addTest(MyTestCase("testCase4"))
    suiteTest.addTest(MyTestCase("testCase5"))
    return suiteTest

run the test suite using HTMLTestRunner

if __name__ == '__main__':
    with open('test_report.html', 'w') as f: 
        runner = HTMLTestRunner.HTMLTestRunner( # type: ignore
            stream=f, 
            title='测试报告', # en: test report
            description='测试报告') # en: test report
        unittest.main(testRunner=runner)

run the test file and generate the HTML report

python3 test_file.py

Replace "test_file.py" with the actual name of your test file. After running the tests, the HTML report will be generated in the same directory with the file name "test_report.html". You can open the report in any web browser to view the test results.

Summary

In this article, we showed you how to set up and use HTMLTestRunner to generate HTML reports for your unit tests. HTMLTestRunner is a useful tool that makes it easy to view the results of your tests in a clear and organized way. By using HTMLTestRunner, you can quickly and easily see which tests passed and which failed, and get a more profound understanding of the overall status of your tests. The full code on this page can be found on GitHub.

Q&A

Q: What is the difference between HTMLTestRunner and unittest?
A: HTMLTestRunner is a third-party library that extends the unittest framework to generate HTML reports for your tests. It is not part of the standard library.
Q: What is setUp and tearDown in unittest?
A: The setUp and tearDown methods are used to set up and tear down the test environment. The setUp method is called before each test case is executed, and the tearDown method is called after each test case is executed. You can use the setUp and tearDown methods to set up and tear down the test environment, such as creating a test database, creating a test user, or creating a test file. More information about setUp and tearDown can be found in the unittest documentation.