Git Procedures

This page will give you a quick overview of how Git works. From branch creation to merging to dev and final release with Merge Requests.

Other Resources: GitLab Documentation Git Documentation

Git Basics

Git, GitLab, and GitHub are all the same thing. Git is a version control system designed to handle everything from small to very large projects with speed and efficiency. It allows multiple developers to work on a project simultaneously without overwriting each other's changes through branches and merges.

Git Repositories

We use different repositories to separate different scopes and projects. You will see below we have a repo for software developers, vehicle repos for modelers/designers, a maps repo for holding all the MLO, and a repo for add-on clothing.

• Project Draconifors: This is the scripts repository for the server and is primarily accessed by the Software Team.

• Project Draconifors - Emergency Vehicles: This repository has all vehicles for emergency departments (LEO/FD).

• Project Draconifors - Other Vehicles: This repository has all the remaining vehicles not tied to an emergency department.

  • This repository may have some emergency vehicles within and will be noted on the streamed.cfg file.

• Project Draconifors - Maps: This repo has all the streamed maps/interiors for the server.

• Project Draconifors - EUP: This repo has all the streamed EUP/uniforms for the server.

Depending on their status or project requirements, Development Team Members will only have access to the repositories needed to complete their tasks.

Git Branches

A repository can consist of several branches, each considered a different version. We use branches to allow developers to work on the code without interfering with others working on the same files. We have each task in a separate branch so that the changes are easier to track and the change/feature is in one spot.

Primary Branches

• Dev Branch This branch is open to everyone to merge into and is mirrored on the Development Server. Sometimes, the current dev branch has a different name; check Discord for the current name.

• Main Branch - This branch will be the main branch to branch off of, but it will be protected. This branch will also be mirrored in the live server. The current branch for the main server is main

Branch Naming Conventions

• new/branch-name - This branch name will be for a completely new resource

• feature/branch-name - This branch name will be for adding a feature to an already existing resource

• issue/branch-name - This branch name will be for fixing an issue within a resource

• misc/branch-name - This branch name will be for miscellaneous changes that don’t fall under the above branch names

Processing a new Task

When you begin working on a task, follow these steps

These steps are for GitHub Desktop, as that is what we recommend for beginners.

Always switch to the main branch before creating your new project branch. Basing project branches off any other branch will cause conflicts.

Main Branch > Working Branch > Dev Branch

Beginning your working branch from dev or merging dev into the working branch will cause code issues, and your project will not be eligible for release.

1. Switch to the Main Branch

GitHub Desktop

Use the dropdown near the top labeled “Current Branch” to select main

GitKraken

Double click main on the sidebar

Git Bash

git checkout main

2. Create a New Branch

GitHub Desktop

Use Branch->New Branch (CTRL+Shift+N) on the toolbar

Name the branch following the Branch Naming Conventions

GitKraken

Click the Branch button above the graph

Git Bash

git checkout -b branch-name

3. Publish Branch

GitHub Desktop

Press the blue “Publish Branch” button near the middle

This will publish your current branch to the server.

GitKraken

Click the Push button above the graph and confirm

Git Bash

git push -u origin branch-name

4. Make your code changes

At this step, make any changes you desire; the GitHub desktop will track those changes and will update as you make changes, something like this:

5. Committing your changes

Once you have finished any portion of your changes, you can make a commit. This commit sends your changes to the server for storage and editing by other developers. We recommend doing this frequently in case data loss occurs. It's also nice to do this if you are taking a break for a bit. This is your working branch; you choose when to commit and how often. We do like to see the work being done. It's also easier to spot errors or omissions at a later date.

Once you have reached a stage where you feel testing is required by other developers or the the beta team, you will merge your changes to the development branch.

6. Switch to Dev Branch

GitHub Desktop

Use the dropdown near the top labeled “Current Branch” and change it to dev

Sometime the current development branch might have slightly different names, check discord for the latest one.

GitKraken

Double-click dev on the sidebar

Git Bash

git checkout dev

7. Merge your Task Branch

GitHub Desktop

Use Branch -> Merge into current branch (CTRL+Shift+M)

Choose your working task branch as the branch to merge into dev.

GitKraken

Drag your branch over the dev branch on the sidebarThe Development Server will pull from the dev branch every 5 minutes. Use TxAdmin to either restart the resource or the server (whichever is required) to apply the merged changes.

Git Bash

git merge [branch-name]

8. Making More Changes

If you need to make more changes to your project, switch to your working branch before making changes. If you begin changes before switching to the correct branch, it will ask you if you want to keep or stash your changes. Keep changes and move to new branch is the best option if you wish to have the changes moved with you. Stashing is use rarely.

Make change commits to your working branch only. Occasionally, you will only change directly to the dev branch when solving conflicts between two working branches.

Once you make your changes, repeat steps 5, 6, and 7 to send them to the dev server for further testing.

9. Beta Team Instructions (if beta testing is needed)

When you feel your task is ready for additional changes, before pinging the beta team, ensure that any relevant liaisons have approved the work.

When requesting beta team testing, make sure the instructions are clear on what needs to be tested:

1. Include how to test your task, what processes they need to do to test

2. Include what errors or bugs you might be aware of

3. Include what changed so they can be on the lookout for those changes

4. Include any other information they need to test your task effectively

5. You may give a deadline by which you feel this can be tested. If you only need a few beta testers to complete testing, you could also provide an "I need 5 people to test this" statement.

Once you feel beta has sufficiently completed testing, you can move on.

10. Preparing for Final Release.

A couple of things to check:

1. Remove all debugging lines in code (unless debug has proper messages for members/dev to troubleshoot)

2. You may keep any comments and notes in the code.

3. Prepare release notes of the changes that took place in the branch

11. Merge Requests

A Merge Request is done on Gitlab and is only needed when ready for release.

1. Log in to your GitLab account and go to the corresponding repo with your changes.

2. On the left sidebar, there should be a button called Merge Requests

3. Click Create Merge Request the blue button on the top right

4. Under Source Branch, choose your working project branch.

5. Make sure the Target Branch is the Main branch

6. Title should be a general statement of what changed

7. Description should include your release notes, these don't have to cover every tiny change, but should be the main points of the release that the members need to be aware of, include the link to the discord task thread.

8. Under Merge Options, it generally Delete source branch when merge request is accepted should be checked to keep project branches clean and only used for one project.

9. Also, under Merge Options, check Squash commits when merge request is accepted. This will keep the primary branch history cleaner.

10. Project leaders will review, give feedback, or release.