Git Guide
For most of our new projects (circa 2023 or later), we use
Git for version control. All of the code for these proejcts is hosted on Github
at https://github.com/FullCount-Development.
For working with Git, we have the option of using Git command line tools or a
program called "GitHub Desktop". Whichever you decide to use comes
down to personal preference, but this guide will specifically cover using
GitHub Desktop. Before starting this guide, make sure you have Git installed on
your machine as well as GitHub desktop. Steps for installing Git and GitHub
Desktop can be found in the Developer Set
Up guide.
Cloning a Repository
First, we need to clone a repository from GitHub onto our
local machine.
1. Open up GitHub Desktop. In the top left corner select
File -> Clone Repository. (If this is the first time you're using GitHub
Desktop on your machine, you'll be asked to sign in to your GitHub account).
2. In the "Clone a repository" window, select the
repository you want to clone to your local machine. For this example, select
FullCount-Development/FullCountPOS
3. Set the "Local path" to the directory where
you'd like your project to exist on your local machine. To be consistent with
other projects, it's best to store all your projects in the same place, e.g.
"C:\java\codebase\{repository-name}".
4. Once you've selected the repository and have the local
path set to the correct location, click "Clone". This will copy all
the source code from GitHub to your local machine.
Now, in the top left tab of GitHub Desktop, you should see
your newley cloned repository (along with any other repositories you cloned
from GitHub).
Creating a New Branch
By default, every Git repository has a branch titled
"Main". The main branch houses our most up to date copy of a project.
Generally, you shouldn't commit code directly to the main branch. Instead, you
should create your own branch and commit code chnages to that. When you're
finished working in your branch and your code has been reviewed and approved by
another developer, your branch will be "merged" into the main branch.
We'll cover merging in a later section. For now, we'll go over the process of
creating a new branch.
1. In the top left "Current Repository" tab,
select the repository you'd like to create a branch for.
2. In the next tab labled "Current Branch", make
sure the current branch is set to "main". This will make sure you're
creating a branch that will be based directly off the most up to date changes
for the repository.
3. Click on the "Fetch Origin" tab. This will
ensure that the code in the local copy of your main branch is up to date with
the main branch hosted on GitHub.
4. Now we're ready to create a new branch. Click on the
"Current Branch" tab, then, click on the "New Branch
Button". You'll be prompted to enter the name of the new branch you're
about to create. By convention, we prefix all of our branches with the redmine
task number they're associated with followed by a concise description of the
task.
Note: The branch being created should (almost) always be
based on the main branch.
5. When you first create a new branch, the branch is only
available locally on your own machine. In order for the branch to be available
on the remote GitHub repository you must "Push" a.k.a.
"Publish" your branch. Click on the "Publish branch" tab to
push your local branch to the remote Git repository.
Once you've published your branch, you'll see the branch
appear in the remote repository hosted on GitHub. This allows other members of
the team to checkout and view your branch.
Switching Branches
You can switch between different branches on the fly. When
switching to a different branch within a project, all of the files on your
local machine will automatically update to refelct the contents of the code
housed in that branch. Switching branches is very simple and straightforward.
Before switching branches, it's usually a good idea to commit any changes
you've been working on or Stash them. Committing and Stashing are covered later
on in this guide.
1. Click the "Current branch" tab. You'll be able
to see all of the branches that exist for your currently selected repository.
To switch branches, simply click on the branch you'd like to work in.
Committing Changes
After completeing code changes for a task, you'll need to
"Commit" those changes to the branch you're working in. Guidelines
for making commits can be found in the developer Guidelines
for Committing Code article.
1. Ensure in the side panel of GitHub Desktop under the
"Current repository" tab you're able to see all of the local changes
you've made in your project.
2. Select/Deselct the files you would like to include in
your commit.
3. Create a meaningful and concise commit message specifying
what changes you're committing to your branch. It is not necessary to add a
description with your commits.
4. When you're ready to commit, click the blue "Commit
to (branch name)" button at the bottom of the "Current
repository" column.
NOTE: Everytime you make a commit, you're committing
to your local branch. The commit will not be available on the remote branch
until you "Push" your changes.
5. When you are ready to re-sync the local copy of your
branch with the remote branch, click the "Push origin" button. This
will push all of the commits that have been made to the local copy of your
branch to the remote hosted branch on GitHub.
Merging
When code is reviewed and approved, the code reviewer will
merge the changes into the main branch. In order to avoid merge conflicts (more
on merge conflicts later), you'll want to ensure that the branch you're working
in is always up-to-date with the latest changes. As you work through your
tasks, it's very important that you frequently merge in changes from main to
your branch. If you created a branch from main three months ago and then
decide to merge in changes from main, you're gonna have a bad time.
Before merging, commit or stash any changes that have been
made in your local branch.
1. Ensure that your "Current repository" is
pointed to the correct project you're wanting to merge from.
2. Click on the "Current branch" tab to view all
the available branches for your selected repository. From here, select
"main" to switch to the main branch for the project.
3. Now, your repository is pointed to you local main
branch. Click "Fetch Origin" to pull all changes from the the remote
main branch to your local main branch.
4. Use the "Current branch" tab to switch back to
the original branch you were working in.
5. In the "Current branch" tab, click the button
at the bottom of the tab that says "Choose a branch to merge into (branch
name)".
6. A window will pop up asking you to select the branch
you'd like to merge into your branch. Select "main" and then click
the button that says "Create a merge commit". This will merge the
local copy of the main branch into the local copy of the branch you're working
in and automatically create a default commit message that says "Merge
branch 'main' into (branch name)".
.
7. Merging is now complete, but keep in mind, the merge is
only done locally. Remember to push your updated branch to the remote
repository by clicking the "Push origin" button.
Reminder: Make sure you merge from main frequently to
prevent your branch from becoming outdated with the most up to date content for
the project!
Related Articles
Developer Guide
Installations An installation guide can be found in the Setup a New Developer Machine guide. Version Control Guide We use both Subversion and Git for version control. A crashcourse of our Subversion versioning processes can be found in the Subversion ...Subversion Guide
We use a version control software called Subversion. With this we can check out repositories, create branches, commit code changes, and do many other cool things. We don’t use the command line to interact with Subversion, rather we use TortoiseSVN, ...Selenium Testing Guide
Selenium Testing Guide Objectives Create End-To-End Selenium Tests for FullCount Applications Prerequisites - Completed the "Setup a new developer machine" guide. - Checkout the ui-tests subversion repository: ...FullCount Git Repositories
FullCount Git Repositories Repositories FullCount Git repositories are stored on GitHub. Name Description authentication Authentication project for device management. authorization Manages JWT-based authentication back-office-ui-tests UI Tests for ...Release Notes Style Guide
Release Notes Style Guide Submitted by biermannp on Tue, 07/09/2024 - 10:40 Along with each monthly release, we have a Release Meeting and publish Release Notes (internally). These help other members of the company understand what the Dev Team has ...