Forem: Kin NG

A 💯 Days in Open Source: Key Lessons That Will Help You Get Started 🚀

Kin NG — Mon, 20 Nov 2023 16:47:39 +0000

October 31st marked the end of the 100 days of open source software (OSS) challenge by Open Sauced. This challenge aimed to unite newcomers, dedicated contributors, and maintainers within OSS projects to foster active involvement, learn new skills, and enhance community interaction by engaging in OSS for 100 days. As a participant of this challenge, I will share three significant lessons I learned from this experience to help newcomers in getting started with OSS and making meaningful contributions.

Open Source is Scary

From an outsider's perspective, getting involved in open source software can seem intimidating. This feeling can be attributed to various factors, but the most common ones I've seen and personally experienced are fear of the unknown, mastering technologies, and receiving feedback. Let's break down each of these challenges.

Fear of The Unknown

It's no secret that when you first dive into a new repository, you won't know everything about it. It might cover a specific software area you are unfamiliar with, or it might introduce you to concepts you've never encountered. This fear of the unknown can be paralyzing, leading to a point where some may give up without even trying.

exploring a CNCF codebase be like

Recognizing the dynamic nature of software is the first step in accepting the presence of inherent unknowns. The key is not to let fear hold you back. Begin by exploring the codebase in small steps, such as reading the documentation or running the project locally. If you encounter a part of the codebase that seems puzzling, remember that most OSS projects have active communities willing to provide support and help you gain a better understanding.

Embrace the fact that there will always be unknowns in OSS. Start small, run the project, and gradually piece together how it works. Leveraging the community is a valuable resource to accelerate your learning.

Mastery of Technologies

In addition to dealing with the unknown, effective participation in OSS often requires proficiency in certain technologies. Given the collaborative nature of OSS, a distributed version control system like Git is an essential tool for tracking file changes. Thus, it is important to have Git in your arsenal, since it is highly likely that a project you engage with in the OSS community will leverage Git for version control. If you're new to Git or want to brush up on the basics for OSS contributions, I highly recommend the Intro to Open Source course by Open Sauced. It covers everything from the history of OSS to Git usage and types of contributions that will help you get started.

Once you've used Git, you'll face the challenge of learning specific technologies, usually a programming language. When starting your journey in OSS, it's beneficial to choose repositories aligned with your technical abilities. For example, if you are proficient in Python, you should aim to select repositories whose codebase is mostly written in Python. Additionally, if you know multiple languages, you could help with the translations of the project's documentation to those languages.

Familiarity with the technologies used in a project can expedite your understanding of the codebase, making it easier to contribute without simultaneously learning a new technology. However, there's also value in stepping out of your comfort zone and tackling repositories that introduce you to unfamiliar technologies. In such cases, opt for smaller codebases that are more digestible. Lack of complete mastery of a particular technology should not deter you from contributing to OSS.

Pick a repository with technologies you already know; this will help you to bridge gaps of knowledge faster, and avoid learning while exploring. If you pick a technology that you don't know and want to challenge yourself, start with small repositories as this will give you enough time to learn outside of exploration.

Receiving Feedback

Last but certainly not least is the challenge of receiving feedback. If it's not a lack of skills or fear of the unknown that hinders contributors, what could it be? OSS is inherently collaborative, and effective communication is crucial. After you tackle an issue and submit a pull request, you'll likely receive feedback from the maintainer and reviewers. While some contributors may interpret feedback as a sign of their contributions being inadequate, this is often not the case.

nit: racecar should be racecar

OSS projects adhere to certain standards, and it's the maintainer's responsibility to ensure that contributions benefit the project, its users, and future contributors. Receiving feedback provides you with an opportunity to improve your coding skills and communication. In some instances, however, you may encounter less-friendly maintainers, and it's essential to recognize when it is better to move on.

Treat feedback as an opportunity to enhance your technical skills and engage in effective communication with the maintainer to address any concerns. If you don't feel comfortable in a particular community, don't hesitate to explore other options.

Defining Open Source Goals

The question of why you should participate in OSS remains, and your motivations can vary widely. That's why it is crucial to set goals for your OSS contributions. Your objectives may include acquiring new skills, getting involved in exciting projects, seeking mentorship, or connecting with like-minded individuals who share your passion. You might even be contemplating becoming a maintainer to gain support for your own projects.

Regardless of your specific goals, I firmly believe that engaging in Open Source can bring invaluable benefits to your skills, and I hope that this article has provided valuable insights to help you start your journey into OSS.

Resources:

Get started with OSS here: Open Sauced Intro to OSS Course
Looking for your first contribution? check these repositories for beginners
Open Sauced
Hacktoberfest

You Might be Overlooking the PUT Method in Your REST API

Kin NG — Tue, 08 Aug 2023 17:32:11 +0000

So, you’re building your first or maybe your hundredth REST API, or perhaps you’re following along with a tutorial, and you’re about to implement the PUT HTTP method for an endpoint. To demonstrate a simple workflow for implementing a PUT endpoint, let’s take a look at the following code snippets. In this article, I will be using Golang, but you can follow along with the language of your choice. Consider the following schema for a Pokemons table.

CREATE TABLE pokemons(
    id bigserial PRIMARY KEY,
    created_at TIMESTAMP(0) with time zone NOT NULL DEFAULT NO
    atk INTEGER NOT NULL,
    def INTEGER NOT NULL
);

Now, for the server logic, we will first invoke our GET method to retrieve the Pokémon that the user wants to update, like so.

type PokemonModel struct {
 DB *sql.DB
}

func (m PokemonModel) Get(id int64) (*Pokemon, error) {

 if id < 1 {
  return nil, ErrRecordNotFound
 }

 query := `
        SELECT id, created_at, name, region, atk, def
        FROM pokemons
        WHERE id=$1
    `

 var pokemon Pokemon

 // Context to cancel our query, if it takes more than 3 seconds
 ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
 defer cancel()

 // Query the database and read the record into our pokemon struct
 err := m.DB.QueryRowContext(ctx, query, id).Scan(&pokemon.ID, &pokemon.CreatedAt, 
           &pokemon.Name, &pokemon.Region, &pokemon.Atk, &pokemon.Def)

 if err != nil {
  switch {
  case errors.Is(err, sql.ErrNoRows):
   return nil, ErrRecordNotFound
  default:
   return nil, err
  }
 }

 return &pokemon, nil
}

Next, we create an update method that will be invoked with the Pokémon retrieved from the GET method to finalize the update.

func (m PokemonModel) Update(pokemon *Pokemon) error {
 // update SQL query
 query := `
        UPDATE pokemons
        SET name=$1, region=$2, atk=$3, def=$4
        WHERE id=$5
        RETURNING id
    `

 // The values of our placeholder parameters
 args := []interface{}{pokemon.Name, pokemon.Region, pokemon.Atk, 
                       pokemon.Def, pokemon.ID}

 // Context to cancel our query, if it takes more than 3 seconds
 ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
 defer cancel()

 // return the result of the update query (nil if no err, otherwise err)
 return m.DB.QueryRowContext(ctx, query, args...).Scan(&pokemon.ID)

}

Nice! We're done, right? Surely, there's no problem with this simple update. Well, what if I told you that you are about to fall into a data race - one of the most common and often overlooked problems when performing updates on a mutable shared resource. Our Pokémon record is a shared resource that can be accessed by two or more threads simultaneously. Therefore, the order of operations, as it stands, is dependent on the exact order in which the scheduler executes instructions.

In the above diagram, Alice makes a GET request (api/pokemons/376) and obtains the record of the Pokémon with id=376. Similarly, Bob also makes the same GET request. At this point in time, both Alice and Bob have the Pokémon record represented by the green box, and a data race is about to occur when they both attempt to modify the original green record by sending a PUT request at approximately the same time.

In this scenario, Bob wants to change the def field to 400, while Alice wants to change the atk field to 330. However, as illustrated, only Alice's request is processed, resulting in the final green box representing only Alice's update. Ideally, the record should have contained both updates instead of just Alice's. However, due to the requests being processed at around the same time, the scheduler has decided to apply Alice's update after Bob's, making Bob's request a victim of the data race.

How to Deal with the Data Race ?

There are multiple ways to address a data race, but the two main approaches are pessimistic locking and optimistic locking. In our case, we will utilize optimistic locking to handle the data race. To protect our Pokémon record from a data race condition using optimistic locking, the following changes need to be implemented.

Add a Version Column to the Pokemons Table

The first step to address the data race using optimistic locking, is to add a version column to our pokemons table. The version number will be defaulted to 1, as shown below:

ALTER TABLE pokemons
ADD COLUMN version INTEGER NOT NULL DEFAULT 1;

Include the Version Field in the Queries

Now, we need to include the version field in our queries. For the GET method will include version to the list of fields to be returned from the query.

query := `
        SELECT id, created_at, name, region, atk, def, version
        FROM pokemons
        WHERE id=$1
    `
// Pass version as well to be stored in the struct (&pokemon.Version)
 err := m.DB.QueryRowContext(ctx, query, id).Scan(&pokemon.ID, &pokemon.CreatedAt, 
 &pokemon.Name, &pokemon.Region, &pokemon.Atk, &pokemon.Def, &pokemon.Version)

The Update method will be slightly different. When making an update, we need to ensure that we increment the version number by 1, while simultaneously checking that the version number has not changed since we sent the GET request.

By increasing the version number by 1, we guarantee a unique, monotonically increasing column that can be checked against any other simultaneous queries. Including the version number in the conditional check ensures that we don't make changes to a record that was modified during the transaction.

The full code for the Update method now looks like this.

// Custom error to notify of a data race
var ErrEditConflict = errors.new("edit conflict")

func (m PokemonModel) Update(pokemon *Pokemon) error {

 query := `
        UPDATE pokemons
        SET name=$1, region=$2, atk=$3, def=$4, version=version+1
        WHERE id=$5 AND version=$6
        RETURNING version
    `

 args := []interface{}{pokemon.Name, pokemon.Region, pokemon.Atk, 
                       pokemon.Def, pokemon.ID, pokemon.Version}

 ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
 defer cancel()

 err := m.DB.QueryRowContext(ctx, query, args...).Scan(&pokemon.Version)

 if err != nil {
  switch {
  case errors.Is(err, sql.ErrNoRows):
   return ErrEditConflict
  default:
   return err
  }
 }
 return nil

}

Now that we have handled the data race, one possible follow-up is to make use of a custom error, such as ErrEditConflict, to send this event through an event queue and retry the failed query in a background worker. Regardless of the specific way you choose to deal with the conflict, the important thing is that you have taken action to solve the data race, and that is commendable.

Even though this is a simple example and the conflict may not seem harmful, it's crucial to recognize that such errors can lead to devastating consequences. For instance, when dealing with updates to an account's balance. Nevertheless, I hope this article has been helpful to you and has made you aware of the potential errors that can arise when implementing the PUT HTTP method in REST APIs.

Resources:

Links:

Github: github.com/k1nho
Twitter: @Kinho_nth