Code Repository Maintenance Notes

Overview

This page provides notes on how to use github to maintain SWIM. The installation instructions (Step 1) refer to cloning the code repository to your computer. But what does that entail and how do you approach the cloning process in the ODOT environment. This page gives a handful of notes and tips to follow. First, the user needs to have Git Bash installed on the machine that will be connecting to the code repository. The way this is setup now, this is typically the SWIM "boxes" (Thing 1 and 2), but it can be any machine where the linkage will be maintained. At the time of writing this, I like keeping the code repo connection under the C:\Work folder of the "Thing" machines. Anyway, step 1 is to have git bash installed on the machine you plan to use. Let's move on from there.

Using Git Bash and Cloning

After you have Git Bash, the first thing you are going to want to do is to "Clone" the code Repository. The "Code Repo" is an online cloud storage solution that helps version control the code and allow team members from all over the world (literally) to access and help maintain the SWIM code base. ODOT is one of those maintaining members. To help maintain the code, ODOT needs to have a local copy, which is a clone of the cloud copy. Git Bash helps keep the local and the cloud copies in sink. In the following sections we will learn how to use Git Bash to do this. In this first step with Git Bash the user first needs to establish a local copy by "Cloning" the repo. To do this (after Git Bash is installed):

• right-click in the file explorer window where the cloned local copy will live (I like using C:\Work)
• right-clicking should include the option "Git Bash Here" which, when selected, will open a Git Bash command line window pointing to the folder that you right-clicked in. Choose "Git Bash Here" to open the Git Bash environment in this location.
• Now, you just need to clone - super easy. Just type the following into Git Bash:

git clone https://github.com/tlumip/tlumip

Note, while you are here cloning things, you might also want to clone some of the other SWIM (tlumip) related code repositories. I think the most important additional one is the wiki:

git clone https://github.com/tlumip/tlumip.wiki

But you might also be interested in some of the other repos that make up the full body of work within SWIM (note - you don't need to clone these to run SWIM, this is more developer level - if you are going to work on these sub-components of SWIM specifically):

git clone https://github.com/tlumip/tlumip_dependencies
git clone https://github.com/tlumip/swimctr
git clone https://github.com/tlumip/swimr
git clone https://github.com/tlumip/model-dev-report

Hopefully you are seeing that pattern that cloning a Github code repository is as simple as knowing the web-address of that repo and typing git clone [web-address] in Git Bash. With the repo cloned, you now have a local copy and can make changes and maintain (contribute to) the code base.

Making Changes (Maintaining) the Code Base

This set of the instructions assumes that you have a github account and that your github account has been elevated within the code repository to a contributor. Perhaps in the future an instruction set on this can be written as needed. This would be a one-time thing. For now, please work with the team maintaining SWIM to get you setup with a user name and proper permissions. When you have your account and permissions, you will need to remember your Git Hub log-in credentials when making changes to the repo, to sign in as yourself to push changes to the code from your local copy to the cloud. Depending on how you sign in to Git Bash, you will probably just be asked once for your credentials (or asked again if you password changes). But just know that from time-to-time you might need to put in your credentials - signing in every once in a while is part of the process.

Assuming that you have the credentials, making changes is almost as easy as making changes to files on your computer the way you would be commonly used to. There are just a couple additional steps that are required to help keep the code (files) well versioned (documented):

• Overall, I don't like to directly work in the local copy folder structure. I will make changes and tests out on the "D" drive. Then when I feel like I have a change that's functioning correctly, I will move the files needed for that SWIM change (and only those files or edits) to my local copy. The point of this bullet is to keep the local copy clean - only changes and only files that the code needs, not working or test copies.
• Before making changes in the local, you need to ensure that your local environment is full up-to-date with the cloud
• Make the file/folder changes to your local after ensuring your up-to-date
• "Push" your changes from the local to the cloud

Those 3 steps (along with the 4th side note to keep your local space clean) are explained further in the following.

Ensuring Your Local Copy is Up-to-Date

If you are doing this in order of this wiki and still have a Git Bash window open from cloning the repo (or repos), close that Git Bash window. Now navigate to the folder of the repo you are going to update. In this example it would be C:\Work\tlumip. Once in this local copy folder, right click here and choose "Git Bash Here". This opens a new Git Bash window specific to this code repository. To ensure you local copy is up-to-date type the following commands into Git Bash:

git status git pull

This should ensure that your local copy has all the latest changes. Note that you also need to know what branch you are working in. Typically you want the master or main branch (both terms mean the same thing, "master" is just legacy naming). If your team is working on a different branch, you will need to "checkout" that branch, as follows:

• Make sure the master branch is clean and there are no uncommited changes
• Use the command git fetch to pull the latest commits from Github.
• Use the command git checkout branchname to checkout the branch you want to work on.

To return to the master, when the team pulls the branch back to the master, you would update your local pointer back to the master (or main) as follows:

git checkout master

Make The Changes and Update the Cloud

Now that you are sure you have the latest copy in the code repo and you are working in the correct branch, move over (overwrite) which ever files you need to in the local copy files. A good example of this might be updating SWIM to use the latest version of Visum. This would involve updating a line in the globalTemplate.properties file. Make whatever changes are needed and save the file in the local copy.

Then in Git Bash (re-open in the root directory of the repo, example C:\Work\tlumip, if you don't have Git Bash open) type:

git add -A (where -A means all, there are other options here too, but if you keep a clean folder structure, you can just say all for everything you changed).
git commit

Once in git commit you need to type a note about what you changed. Hopefully the change is related to an open issue in Github. Assuming so use # and then the issue number (like #177) in the comment, to link the code change with the issue being worked on. To add a comment/note, line (cursor) down in Git Bash to the first text line (~ line).

• Type i to enter "insert mode".
• cursor down to the last hashtag (#) comment line and hit return to start a new line where you will insert your comment.
• Type your comment, something like, "#177 - Updated properties file to use the latest version of Visum"
• Use the esc key to exit insert mode
• Then type :x! and hit enter to save and exit

The comment window should close and return to the Git Bash command line. If you had to enter credentials, you might have gotten prompted along the way or in the push step (next) to add your log-in and password. The final line is to push to the branch you are working on:

git push origin master (or maybe main if it's a newer repo, or replace "master" with whatever branch name you are working in)

And with that you are done. The cloud (web copy) should so an update with your credentials. If there are any questions on this, please follow-up with a team member that has been using Git, and we can update the instructions to resolve anything that's not clear or out of date.