Working with Github

The basic Github flow for StorefronUI contributors

1. Set up Github account

StorefrontUI is a Github repository. You will need to have Github account in order to start contributing to our project.

TIP

If you already have an account, we recommend you to add Two-Factor Authentication (2FA) to enable security over your account.

2. Fork StorefrontUI Repository

Forking a repository will copy the current state (at the moment of forking) into your Github account's respository list. During contributing to StorefrontUI, this is required for you to keep track your issue branches and code.

WARNING

Forked repository is not updated automatically when the original one changes, you will need to keep it updated manually once in a while.

Fork the repo

For your own copy of StorefrontUI

  • Upon completion, you can access your forked repository through your Github account. It will be listed under your repository list. Or you can go directly via URL:
https://github.com/username/storefront-ui

in which username is your Github username.

Clone it to your local machine

Once done with forking, it's time to set up your local environment in order to start working locally. You need to clone your forked repository on your local development machine. There are two ways to do it:

Using SSH

This is the most common and secured way. You can copy the SSH link by clicking on the right green button Clone or download. The link will be in the format:

git@github.com:username/storefront-ui.git

Clone or download a repo

Then in the terminal, simply use the following command:

$ git clone git@github.com:username/storefront-ui.git

TIP

By default this will clone the repo into storefront-ui folder in the current directory. If you wish to define a different folder name, you can pass the desired name as an optional parameter in the clone command.

$ git clone git@github.com:username/storefront-ui.git <your-folder-name>

Using HTTPS:

In the same popover after clicking on the green button, click on Use HTTPS link on the top right corner.

Clone or Download repo using HTTPS

The HTTPS link will be available for copying in the following format:

https://github.com/username/storefront-ui.git

The next steps to clone into local machine are the same as above, with the HTTPS link in place of the SSH one.

Keep your forked repo updated

All the code fixes and new features for StorefrontUI will be merged into the main repository. Hence, to keep your forked repo updated, you can:

Manual update with fetch

Simply run this command on the terminal within the folder containing the code of your forked repo:

git fetch git@github.com:DivanteLtd/storefront-ui.git 

This is simple solution without any setting required. However, in many cases, the second method is preferable.

Set the original repository as a second remote origin.

  • Remote origins:

See what remote origins you currently have locally, run the following command in the terminal:

git remote -v

This should show your cloned repo as the original remote:

origin git@github.com:username/storefront-ui.git (fetch)
origin git@github.com:username/storefront-ui.git (push)
  • Adding upstream origin:

We will add the original repository as another upstream remote by:

git remote add upstream git@github.com:DivanteLtd/storefront-ui.git

That's it! Running the command git remote --v will now yield:

origin git@github.com:username/storefront-ui.git (fetch)
origin git@github.com:username/storefront-ui.git (push)
upstream git@github.com:DivanteLtd/storefront-ui.git (fetch)
upstream git@github.com:DivanteLtd/storefront-ui.git (push)
  • Sync with the main repo:

To fetch the latest from the main repo to your master branch, you can run:

git fetch upstream master

3. Select a Github issue

Select issue by its label

We know it's not easy to pick an issue that is most suitable to you to work with, especially when it comes to first-timer. Thus we came up with labelling system to help addressing this problem. Below are the main labels which are grouped by:

Difficulty level

 
Good first issue
Recommended for first-time contributor or beginner
 
1. Easy
Easy and small task, good for quick contribution or beginner
 
3. Medium
Not for beginner, has some logic or API modification
 
5. Hard
Requires code understanding, complex API logic implementation
 
10. Extremely hard
Requires architecture planning, extreme understand about codebase and very complex

We recommend first-time contributor to select issues with label Good first issue to start. But it's entirely up to you.

ANY TROUBLE?

Feeling some issue's level does not match the label assigned? Drop us a message in Discord or leave a comment inside the issue.

Type of the issue

 
Bug
It's a bug that needs to be taken care of
 
Design
Related to component design, mainly for designer
 
Docs
Tasks that involve documentation activities

Status of the issue

 
Blocked
Don't touch becauce it's waiting for another issue to complete first
 
Help wanted
We want it to be done but we need help from you.
 
Question
Further information needed.

TIP

You can review the full list of labels and the issues attached to them on our Github labels

Notes:

  • You can filter our Github issues according to a specific labels by clicking at column Labels and selecting the desired label from the dropdown list.

Filter issues by click on column Labels

  • Make sure that issue is not assigned to any other contributor by checking the Assignee column is empty.

Make sure it is not taken by anyone yet

or by checking the Assignee section on the right side inside the issue page.

Check assignee inside issue page

Get assigned to selected issue

Once you found the issue you want to work and it's not yet assigned, let's get it assigned to you properly.

First time contribute to our codebase

If this is your first time in StorefrontUI codebase, you need to either:

  • make a comment inside the issue page. In that comment, tag anyone in [our core team] by typing @<select-a-core-team-member> and ask to be assigned.

or

And we will make sure it happen.

Contributed to our codebase before

It'll be extremely easy. Inside the issue page, simply click on assign yourself in Assignee section, and 🎉you are assigned!

Click on Assign to yourself link

4. Create an issue branch

Now that you are assigned to an issue, it's time to get to work 😄

We strongly recommend you to create a new branch from your master branch instead of working directly on the master branch of your forked.

This allows you to work on different issues, with each of them attached to a specific branch. Keeping your master clean and synced with master of StorefrontUI ensures you will always have a clean state to start working on new or fallback to when needed.

NAME YOUR BRANCH

We suggest naming your branch according to the following format:

#<issue-number>-<brief-description-of-issue>

For example: #290-contribution-guide, and description of the issue should not more than 5 words.

There are lots of way to create a local branch, below are two most common ways:

Using terminal (or command line for Windows)

  • Navigate to your folder cloned from your forked repo.

VERIFY YOUR CURRENT BRANCH

You should verify that your current branch is master before continuing, to avoid including unlated changes for different issue branch. It can be done using:

git status
  • Run the command:
$ git checkout -b <your-branch-name>

in which, -b is the flag indicating it's a command to create a new branch.

BE CAREFUL

git checkout <branch-name> without a flag will simply just switch to an existing <brand-name> branch.

  • Setup remote branch and attach local branch to that remote branch
git branch --set-upstream <your-branch-name> origin/<your-branch-name>

Using Visual Studio Code (VS Code)

The good news is VS Code has Git support built-in.

How Github plugin looks in VS code

Create branches

  • It can be done easily by clicking the bottom left corner of VS Code, where the current Github local branch is shown.

Click on the bottom left to change branch

  • A new input dropdown will be opened at the top of VS Code with an input field for branch name and several options for selecting. After typing the new branch name and select whether to branch out from current branch (first option) or from a different branch (second option), a local branch will be created.

Checkout different branch or create new branch

SWITCH TO ANOTHER BRANCH

There is autocomplete enabled for this branch name input field. You can also check out (switch to) another existing branch by do exact the same and select the matched branch shown in the dropdown instead of the above options.

DO NOT FORGET

Click on the cloud icon at the bottom, next to the branch name to set the remote branch and have it tied to the local one.

Set upstream for new local branch

In addition, it allows you to do other basic features, such as:

  • Initialize a repository.
  • Clone a repository.
  • Create tags.
  • Stage and commit changes.
  • Push/pull/sync with a remote branch.
  • Resolve merge conflicts.
  • View differences made.

5. Create PR from branch

Make a commit and push to remote branch

WARNING

  1. You have maximum 50 characters for a commit message. Be concise!
  2. Make sure your issue number will be presented in one of the commits and follow the guide to enable auto-closing the referenced issue after your PR is merged.

By terminal (or command line for Windows users)

  • Use the following command to stage a single changed file:
git add <file-path>

Or all the changed files for a commit by using -a flag:

git add -a
  • Create a commit with a meaningful message by using -m flag:
git commit -m <your-message>

TIP

You can also combine staging all files and writing a commit message into one command with two flags -a and -m:

git commit -a -m <your-message>
  • Push that commit to remote branch
git push

//OR

git push origin <your-branch-name>

STAGE THE WRONG FILE?

If there is a staged file that wasn't supposed to be staged in the commit, you can unstage it by using checkout command. See Troubleshootings - Unstaged unwanted file(s) for more information.

By VSCode UI

While working in local branch, your changes will be reflected on the left side column of VSCode (after selecting Github plugin Github plugin icon on VSCode icon).

  • Enter a meaningful commit message in the Message field.

  • You can select specific changes to stage by hovering on the changed file and click on + icon.

Or select all by hovering at the CHANGES tab and click on + icon.

  • Commit the selected changes to the branch by clicking on the confirm icon icon at the top.

TIP

Click on that icon without pre-selecting changes will auto commit all the changes listed.

  • Once done, push that commit to the remote branch by clicking the sync area at the bottom left of VSCode, next to the branch name.

push the commit

Confirm the action and here we go, the commit will be synced.

Sync branch with master

Syncing with master is simple, and we strongly suggest to do it frequently to avoid conflicts.

After you set up synchronization between your forked repo and StorefrontUI repo and have your master branch up-to-date, simply use git merge to merge the latest master changes into your branch.

git merge master

TIP

You can also use git merge <branch-name> to merge changes of another branch into your branch.

If the merge is done without conflict, terminal may switch to vim editor with a basic information about the merge as a commit. If so, you can start editing it by hitting i key.

Once done, hit ESC key and type :wq to save (-w) and quit the editor (-q).

Then push to the remote branch using git push command mentioned in the previous section.

Create Pull Request (PR)

  • Navigate to Pull Requests Tab in StorefrontUI repo and click on "New pull request" button (located on the right side)

New pull request

  • Search for your branch name and select from the dropdown

Search for branch

  • Review your changes (files comparison are available by scrolling the page down) and confirm by clicking on Create pull request button

Create pull request after review

  • Fill in the following details before submitting the Pull Request:

Fill in pull request details

  1. Write the title of your pull request in the following format:
#[Issue-number] - [Issue title]

WORK-IN-PROGRESS PR

You can also create pull request while working on an issue, just remember to add [WIP] at the beginning of the issue title. This will let us know not to review it until it's ready.

  1. Write the issue description according to our template.

  2. Add a reviewer to review your PR by searching for their Github account or selecting from the suggestion list. This will send the assigned reviewer(s) a notification on every changes made to the PR hereafter, as well as to start reviewing.

TIP

There can be multiple reviewers assigned to one PR, depending on how complex that PR is and how many reviewers you would like to review your Pull Request. But minimum one is required.

  1. Confirm create the pull request.

Code review

WARNING

Make sure your code follows our Coding guidelines.

After the pull request is created and assigned, the selected reviewer(s) will go over the changes, whether it's code or documentation fixes. They will leave the comments at the relevant area if needed to:

  • Request for a code change.
  • Ask a question.

This step is required to ensure the consistency in coding standards, readability and avoid unseen bug(s) that may occur along the way from a fresher look.

Once it's done and approved, one of our core team members will merge it to master and that's it! Congratulations, you just make a contribution 🎉 !

Troubleshootings (FAQs and tips)

Close issue through commit message

You can trigger closing the issue automatically once the PR (Pull Request) is merged to master. All you need to do is to ensure there will be a commit with message in the following format:

Fixes <issue number>

There other possible keywords are fixes, fix, closes, close, etc.

More information:

Rename a branch locally and remotely

To rename your branch and make sure your repo is synced, only two steps are required:

  • Rename locally by using
git branch -m <old-branch-name> <new-branch-name>

in which, -m flag stands for --move command.

BE CAREFUL!

A capitalized -M flag will indicate --move with --force flag enabled to "force" the change". This will allow you to rename even if the name already exists in your repository.

If you want to rename the branch that is currently checked out, just omit the <old-branch-name> option, which looks like this:

git branch -m <new-branch-name>
  • Rename remotely Once the local branch has been renamed, just run the below command:
git push origin :<old-branch-name> <new-branch-name>

Behind the back, it actually does the followings:

  • Delete the remote branch that is to be renamed
  • Push the new branch to the remote repo
  • Switch to the new branch
  • Reset the upstream reference for the renamed branch

Unstage unwanted file(s)

Use reset command to:

  • Removed a single staged file from the staging area
git reset HEAD -- <file>
  • Removed whole directory from the staging area
git reset HEAD -- <directoryName>

WARNING

This must be done before you make a commit.

More information: Git reset Manual

Undo file(s) changes

Use checkout -- command to undo your changes on a single file or on all files in a single directory:

git checkout -- <file-path-or-directory>

Or all the files

git checkout -- .

WARNING

This must be done before you make a commit.

More information: Git checkout Manual

FAQs

TBD