Major Programming Assignments on GitHub

MajorProgrammingGitFlow.md

NC A&T COMP167 Gitflow

Creating the Repository

• The first step to working on your assignment is to create the repository on GitHub. NO code should be written before an assignment has been accepted, and a repository automatically created for the student. Your instructor will provide you with a link to your assignment. When you click the provided link, you will be prompted to "Accept Assignment" and then will be provided a link to your repository.
• Next, clone the repository to your local machine using git. To clone a repository, click the clone or download button on the GitHub repository page, and copy the provided url to your clipboard.
• Using the terminal on MacOS or Linux, or Git Bash on Windows, navigate to your COMP 167 directory and then clone the repository using

git clone [paste url here]

• Now that you have a local repository, it is time to begin work on your project.

NOTE: You should not commit any code to your master branch. Master branches are protected on the GitHub side, meaning that any code you commit to master locally wil not be able to sync with GitHub. Before completing any code, carefully read the following section

Completing the Assignment

• All assignments are broken into parts, usually annotated as "Levels". The work for each level must be completed on a separate branch to ensure full credit.
• Create a new branch from your terminal using the command git checkout -b level-1.
• After you have created your first working branch, for example, level-1, you will need to create your NetBeans Project. When you create your project, it is very important that you specify your git repository as your project location.
• Now that you have a project, it is a good time to commit! Switch back to the terminal or to Git Bash and run the following commands:

git add .
git commit -m "[your-commit-message-here]"

• After you make a commit, you should push immediately. You can push using the following command:

git push

• Remember that for your first push on a new local branch, you will have to copy and paste a comand from git that includes set-upstream. You will only have to do this once.
• Continue working and commiting for the first level.
• Once you have completed all work for a level, push your final changes and open your repository on GitHub's website. Since you just pushed, there will be a banner across the top of your repository and a button to "Compare and Pull Request", select this button
  • Enter a quick message, and send pull request.
  • Then, select the displayed link to view the pull request on GitHub.
  • Add your TA's as reviewers under the "Reviewers" section.
• Your TA's will likely have some feedback for you regarding your pull request, make the requested changes and comment back, letting them know you've completed them.
• Once you have received an approval, merge your pull request and work on the next level!

Making Commits

• Commits are the backbone of git. Making frequent, atomic commits is the best way to succeed with git.
  • Commit often. You should never stop work with uncommited changes in the Changes tab of GitHub desktop. You should commit regularly and Sync after every commit.
  • Atomic commits. Atomic commits cover one logical change in the code. They are a single, totally independent change, hence atomic. For example, if you implement a single new method, you should commit that. If you create a new class, you should commit that. You should be able to summarize your commits in a single, concise summary. If you have difficulty summarizing your commit in 55 characters or less, you've probably made too many changes for a single commit.
• Commit messages should be in the imperative case. The imperative case means like giving a command. Rather than saying "I changed the variable name from A to B", you would say "Change the variable name from A to B".
  • Because we are using working branches, and not committing directly to our master branch, the changes in these commits are not done in the code yet! Therefore, to say in a commit message "I changed a thing" is not accurate. Instead, write your commit messages in the imperative case so that when a reviewer looks at them in your pull request, they see an accurate summary of what your changes intend to do on master.

NOTE: you are not being graded on the content of your commit messages, so don't stress out about them. However, using the git best practices now will make you stand out to an employer at an internship or co-op.

Making New Branches

• Notice the ability to branch from a specific branch. Generally, you want to start work from your most recently updated branch. For example, immediately after closing a pull request, you should branch from master, as you just merged in your latest code. However, if you have not yet merged level-1 because you are awaiting review, but need to start work on level-2, it is appropriate to branch from level-1.
  • If you branch from a development branch, for example, level-2, and begin work on level-3, you must got back and update level-3 after level-2 is merged. This will ensure that any changes made during the review process are reflected in level-3. The example workflow will look like this:
    • Commit code for level-2, fulfilling all stated requirements
    • Open pull request for level-2
    • While awaiting review, create branch level-3 from level-2 and begin work. To do this, run the following commands:

    git checkout level-2
    git pull
    git checkout -b level-3
    

    • The above commands make level-2 your active branch, which means it will be the base for your new level-3 branch.
    • Receive level-2 feedback, commit changes to level-2, receive approval.
    • Merge level-2 into master.
    • Now, there are changes in master that level-3 does not have, we want to update level-3 with those changes before we do any more work. Run the following commands:

    git checkout master
    git pull
    git checkout level-3
    git merge master
    

    • The above commands get your most recent changes from the remote master branch, and then merge them into your level-3 branch so that it is up to date!

The best place to look for Git and GitHub tutorials is GitHub's official YouTube channel or Git's official book.