GIT Tips For Your First Project

This tutorial will not go over the basics of GIT but will discuss a basic approach that can help manage your code better when writing code in a professional environment or working on your own project.

Branching

We should not work or push code directly to main (or master). Instead, we will create a new branch for each time we start working on a new feature. This way we can make sure the main branch is always a working branch.

This will save a lot of time once something breaks after merging new code. If we merged into main a new branch and the application breaks, we can always just revert those changes (this can be done on Github).

The only exception might be the setup. If you install React for example as an initial setup, this can also be done in main because it will work “out of the box”. But, any changes we might want to do to the initial setup (delete the content of an initial component for example) will have to be done on a separate branch.

Rules of thumb

• Keep branch names short (home, user_page, fetch_cards)
• Oragnize branches around a feature — (user_login, user_signup, user_avatar). This way we can keep all related sub-feature organized with the main feature (user)
• We can even improve a branch name by stating its <type>. See more in the next section (commit messages).

Let’s go through a real-life example. After we created an initial setup for a React app using the command line we want to start and add the content of the home page. To do so we will create a new branch named "home”: git checkout -b home . Then, we will make any necessary change and will commit small changes like git commit -m"Feat[home]: added an 'about me' section . We will expend on how to write a proper commit message in the next section.

Commit Message

I recommend to follow the commits’ conventions describe here.

TL;DR
Every commit should have the following structure:

<type>[optional scope]: <description>

The most common types are

• feat for new features (any addition to the existing code base)
• fix fixing bug in the existing code that affect users
• refactor improving on code which does NOT affect users (improving code style or adding comments for example)
• docs adding documentation

Optional scope should be the files, process or components you have changes:

• fix[home page]: ...
• feat[login]: ...
• refactor[fetching users]: ...
• docs[tests] ...

And description

The description part should be too long but shortly present information on the change to make it easier to trace if there is a problem or a bug.

Something like

• fix[login]: email validation checks full pattern
• refactor[home]: fetch function moved to separate file
• feat[favorites]: like button added to all posts

Now that we have amazing commit message we can also improve on our branch naming by adding the type to the branch name:

• git checkout -b feat_login
• git checkout -b fix_login_email_input

Pull Request

Once your branch is ready to be merged, you need to create a new pull request on Github. To do that you first need to push your new branch and all recent changes: git push -u origin <branch_name> .

Then on Github, going to the repository you will see “compare & pull request” for the new branch:

Github’s repository main page

Then press on Compare & pull request to create a new pull request.

We should add a few details:

Title:

• Like the branch name or commit messages, should be constructed as type[scope]: description

A pull request title

Description, should include:

1. A general explanation to what was changed
2. Change log of all the changes
3. Linked resources

Something like this:

a pull request description

To summarize, a convention can help improve code management and help tracing any changes and reverting bugs if needed. It can also improve communication and understanding in a team setting.