Introduction to Using GitHub

This page will (hopefully) introduce you to the basics of the practical uses of Git and GitHub. It is strongly recommended that you use Git for version control and that you collaborate on your projects using GitHub. This will make turn-over transitions easier and streamline your work in a very powerful way. As you leverage GitHub's power, you will find yourself to be so much more productive.

Still not convinced? Think about your own time starting in the Lab. Were you able to easily find the code you needed and were you able to immediately understand what the code was doing, who did what, and what you need to finish? No? That's the power of GitHub, baby.

Git

Video Tutorials

These videos will help get to know conceptually the fundamentals of Git, including the idea of branches, merging, and where GitHub fits in the whole picture.

• Introduction to Git- Core Concepts
• Git Branch Merging
• Using Git in VS Code

Basic Theory and Vocabulary

Git always works on a branch. The main branch has the very original name of "main" and is the base/default branch. You shouldn't work directly in main for a few reasons:

• if you mess up your code it is very difficult to return to a working version of the code
• you have much less freedom to experiment. If the main is public (in the case of software development) you can't really change/fix the code without messing up the code for everyone who uses it.

You and your collaborators should always work in different branches and merge the branch to main often (some unit of work-time or progress; it is completely up to you).

install

To use Git (and eventually GitHub) you will need to have Git installed on your device. Use these instructions to install to your own platform.

Git CLI

Git via IDE

It will likely be so much easier to use Git in your IDE than try to access version control through CLI. How to do this will depend on your IDE. We will discuss how to do this in the two most popular IDEs in our lab: Pycharm and VS Code.

Pycharm

Navigate to Settings>Version control. Press the plus sign.

Note that you need to have Git pre-installed. Select your directory and select "Git" in the drop-down.

Git should now be enabled.

To set up GitHub, navigate to "GitHub" under "Version Control" and press on the plus sign.

You can select either option, but in general, logging in with a token is much more effective and gives you consistent access for a longer period of time.

To generate a token:

either navigate directly to Github.com, or select "generate" which will navigate you directly to the token generation page.

You will need to sign into GitHub. you should then see a page entitled "New personal access token". Name the token whatever you want, but it should be something descriptive so you know you are using this token for PyCharm. This page lists all of the permissions associated with this token. You should set the expiration to several months away at least. Otherwise, you will be constantly setting up new tokens to establish your Git remote.

The suggested tokens have already been pre-selected. Under admin:org you will want to select write:org, the other options should be fine.

Note: GitHub often changes the ways public keys are handled so it is possible these options are out of date. When in doubt, just accept whatever default options Pycharm selects.

If you navigate directly, selection settings in the menu with your GitHub handle, go to the bottom of the side menu and select "Developer settings"> "Personal Access Tokens"> Tokens. Make sure that the following options are selected:

• repo
• workflow
• write:org
• gist

Select "Generate" and copy the generated code. Insert this code in the Token field in PyCharm and select "Add Account". You should be good to go after this!

VSCode

Making Commits

PyCharm

GitHub Best Practices

For RLL, GitHub is a powerful took for collaboration.

commits

You should commit often, but you don't need to always merge the branch into main. Commits should always have a relevant comment. Here are a few bad ones:

Comments like "idk" and "chgs" don't say anything about what changes are actually reflected. It actually makes it much more difficult for collaborators and new RAs to understand your code. Don't do this.

Here are examples of good commit comments:

These are brief, descriptive, and helpful for others to know your intentions.

ReadMe

The ReadMe is perhaps the single most important document for a new RA or collaborator to understand your code. Here, they can learn about what it is supposed to do, how to initialize it, what steps still need to be done, necessary packages, etc. Here is an example of an OK ReadMe.

It describes the project, its goals, and where to get the data, but it is pretty limited beyond that.

For an example of an extremely helpful ReadMe: go to this repository. You can also take a look at the source code for your favorite package on GitHub and see how they write their ReadMe if you want an example of a highly technical yet extremely helpful ReadMe; we don't expect that level of precision or detail.

industry-standard ReadMes follow this format(source):

Understanding that the lab is at a point it may start outsourcing some processing or otherwise sell its programs and services, you are encouraged to follow this standard.

Documentation

Documenting your code is primordial for smooth transitions into new projects. You will make a new RA or collaborator very happy if you are able to document your code appropriately. Just think back on your time as a new RA and consider how much better off you would have been had there been some sort of documentation.

Besides the ReadMe, documentation exists in three forms: block comments, docstrings, and variable names.

comments

You do not need to comment every line, but you should still comment, especially on difficult lines. Separating the code into "blocks" with good spacing and giving each block a title for what it does goes a really long way.

Here is an example of visually helpful spacing and commenting.

At the beginning of the document, you should always have some kind of statement about what the script does.

Here is a generally accepted list of rules to consider when writing comments (source):

1. Comments should not duplicate the code.
2. Good comments do not excuse unclear code.
3. If you can’t write a clear comment, there may be a problem with the code.
4. Comments should dispel confusion, not cause it.
5. Explain unidiomatic code in comments.
6. Provide links to the original source of copied code.
7. Include links to external references where they will be most helpful.
8. Add comments when fixing bugs.
9. Use comments to mark incomplete implementations.