umm-csci-3601 / intro-to-git

A group exercise practicing with various git ideas and tools

Introduction to git

‼️ 🧙‍♀️ Faculty

Each semester there's fair bit of setup that has to be done to initially create and configure that semester's GitHub organization, that semester's GitHub Classroom, and the specific set up for this first lab.

After you've gone through those instructions, you should remove these faculty-oriented instructions.

Make sure to leave these notes in the copy in the "starter" repository so it's there each semester when we make a copy of this.

• Background
  • Resources for learning git and friends
  • How we're going to use git
  • Configuring your git e-mail
• We're ready to start the lab

Background

This is an in-lab exercise where we'll introduce and practice several of the key features of the git version control system, and the GitHub repository hosting service. We'll provide command line means of accomplishing the various tasks in the first part of this lab. For the second part of the lab, we'll provide info on how to use GitKraken along with Visual Studio Code (VS Code) since those tools will be part of our primary workflow this semester. git is essentially a command line tool, and it can be difficult to visualize branching and history; GitKraken provides a nice GUI for git which we find quite helpful for understanding what's going on. VS Code is our IDE (basically our fancy program editor); there are lots of alternatives, but we've been very happy with VS Code over the past few years.

‼️ While in most labs it will be fine for groups to move ahead at their own pace, in this lab we'd like people to keep together because there are moments where we're expecting certain things to happen (e.g., merge conflicts) and we want everyone to be in roughly the same place when that happens.

Resources for learning git and friends

This lab experience definitely will not provide a comprehensive overview of the many features git provides, and there are a lot of on-line resources that can provide additional information.

Below are some resources that you might want to look at right away to help you get up to speed on git and its friends:

• A few of the many GitHub tutorials and docs. There are a lot more than just these, but these are short and pretty easy to spin through, and cover the key concepts we’ll need at the beginning of the semester.
  • GitHub Hello World (a really nice, short introduction to the key ideas)
  • Getting started with GitHub
  • Understanding the GitHub flow
• The GitKraken tutorial videos
  • The beginner tutorials would be the obvious place to start; over time, though, we’d encourage you to work through the more advanced ones.

As well as reading this README document, you should read two other pieces of documentation we have in the docs/ folder:

• A discussion of how to avoid merge conflicts and deal with them when they (inevitably) happen
• An overview of the Gradle build tool and how we're using it in this lab

You should also probably read GitHub's Basic writing and formatting syntax guide. Markdown is the markup language used by Discord, Slack, GitHub, and many other online tools, so understanding at least the basics is really valuable.

Below are some additional resources that you might want to (re)visit over time as you become more experienced with git and want to use some of its more advanced features.

• The excellent Atlassian git tutorials
• The "standard" git documentation site, which also includes links to videos, cheat sheets, and such
• git – the simple guide, a single-page app that goes through the major features of git
• A little on-line "game" for learning how branching works in git

As circumstances allow, you might also want to at least skim one or two of the tutorials listed above.

We'll also be using Gradle, a tool for building and running programs. We'll be using Gradle throughout the course, so it's useful to see it a bit here. We also use it to automate the tests for this project, which allows GitHub Actions to automatically run our tests whenever someone makes a change, and holler at us if someone breaks the tests.

The discussion below assumes that people are paired up in the lab, but we want to make sure everyone has hands-on experience with these tools and ideas. This sort of pair programming will be common throughout the class and beyond, with two people working together. It is common in these settings for one person (the driver, say Pat) to be at the keyboard, while the other person (the navigator, say Chris) is actively engaged in working with Pat, suggesting ideas, noticing typos, and answering questions. For this process to work, both of you have to contribute and be involved, and it's extremely important for you to trade off the roles of driver and navigator now and then. Thus in this lab there will be times where we'll explicitly ask you to trade roles so that everyone has a chance to go through all the activities.

How we're going to use git

git is a piece of software which provides distributed version control, allowing a team of developers to work together on a project, helping manage collaboration and change. We're going to use three related tools:

• git is the fundamental program. It was originally developed to help manage change in the Linux operating system codebase, and it underlies the next two tools. git organizes projects into repositories, which are collections of files and the histories of all the changes ever made to that project. It is a command line tool.
• GitKraken is a GUI for git that provides a nice visual interface to git and displays of complex things like git histories and branching.
• GitHub is a web-based software service that allows people to host, search, and manage repositories created and managed with git.

You could use git without ever using GitKraken or GitHub. We've found that a good GUI like GitKraken can be a big help when things get complicated. GitHub is an extremely popular repository hosting service, and it's a good idea for computing folks to be familiar with it. We use it to manage all the labs for this course, and you'll use GitHub to manage all your labs and project iterations in this course.

This lab essentially has two halves:

• Adding your names in separate Markdown files
• Adding your greetings in the Java code

We'll use command line git for the first half so you have some exposure to using git on the command line. This is important because you don't always have GUIs (for example, when you're remotely logged into some cloud server). We'll then use GitKraken in the second half, also mentioning how you'd accomplish some of the new git tasks on the command line.

When you use git and GitHub, you typically have a single "primary" copy of your repository hosted on GitHub; this will be visible to everyone in your group (and the world if the project is public), and will be the "copy of record". People will transmit changes through that copy, and use GitHub tools like issues, pull requests, and code reviews to discuss potential changes.

Each developer then has one or more private copies of the repository (called clones) that they make local changes to. They can pull changes from the GitHub repository into their local repository, as well as push local changes up to the GitHub repository so that other people can access them.

In the diagram below, each of Pat, Chris, and Sally would have their own copy of the repository on their computer, and they would use git to push changes up to GitHub and pull changes (that other people made) down to their copy. Thus they're all effectively communicating with each other through GitHub as the shared "truth".

Configuring your git e-mail

⚠️❗⚠️ This whole section will be irrelevant for people that already have done this configuration step, either because you did it by hand (perhaps for another class) or used a tool like GitKraken that set all this stuff up for you. To see if you're already set up, run the following two commands on the command line, and confirm that they return the email you used when you created your GitHub account, and your user name as you'd like it to be displayed in things like commit messages and on GitHub.

• git config --global user.email
• git config --global user.name

If both of those look right, ignore the rest of this. You're done with the setup and ready to start the first half of the lab exercise!

If either or both don't return the values you want, then follow along below to set that up. Ignore everything from here to the end of this section if your settings are correct.

---

Before we actually start to use git, you should configure your git email so work you do in our lab properly connects to your GitHub account. You only need to do this once and it will "stick" throughout the course (and beyond) in all systems that use git.

• Open a terminal window
• Type git config --global user.email "[email protected]" where you replace [email protected] with the email you used to set up your GitHub account.
• Verify that it worked by typing git config --global user.email; you should get the address you just configured as the response.

If you want to use a different e-mail address than the one you signed up for GitHub with (e.g., you signed up with a non-U email but you'd like to use your UMM email now) you can set your commit email address on GitHub so that they match.

⚠️ If you'll occasionally be using any non-lab machines (like your own computer) to do work, make sure you set your git email on those machines as well. This will ensure that no matter where you commit from, git and GitHub will "know" it's you and properly credit you for your work.

We're ready to start the lab

There are two parts to the lab:

• In the first part we'll all share some info through git
• In the second part we'll take it up a notch and collectively edit a single Java program, using git to manage all the possible conflicts that might arise.

⚠️ DO NOT START THE LAB until lab time and the instructor asks everyone to start up. Unlike many labs, it's fairly important that everyone should stay in sync in this lab, and if you start early that might complicate things.

intro-to-git's Issues

Make contact info into YAML files

We should have them build the contact info files as YAML files with specified headers. That would make number of interesting things possible that won't work with the current "free form" set up.

We may want them to install the Gradle Tasks plugin for VSCode

The Gradle Tasks plugin for VSCode adds a "Gradle Tasks" panel which allows users to run gradle tasks from VSCode in a manner similar to how that worked in IntelliJ. I don't know if it's necessary, but it might be useful. If we do this, we might want to create a "folder" of tasks and put "run" and "test" there so students won't have to go hunting for those in the big pile of things that gradle knows how to do.

Change badge in README to use GitHub Actions

Move documentation to docs/

We have a docs/ directory where we currently have just Gradle_README.md. We should move some of the extra docs we put in the root to there like MERGE_CONFLICTS.md and maybe FACULTY_BRANCH_PROTECTION_SETTINGS.md

Update git learning goal on canvas to say something about size of commits

This semester's learning goal only talks about commit messages, but we also want them to generate small, focused commits, and that should be reflected in the learning outcome and thus on the rubric.

Write some tests

It would be nice to have at least some really minimal tests for this so there's something for Travis to do beyond just compile when we do CI builds.

At a minimum we can require that each line has the form NAME says 'Hello' where NAME is basically any text.

We could fancy it up some more and have a text file with the expected names, and the tests can confirm that the set of names in that file is exactly the same as the set of names in the output. The students would then need to update the file of names and add their properly formatted method
to get everything to stay in sync.

Add a link checker to this project

There are various tools that will check links in GitHub Actions, such as lychee link checker action. Given the number of links in the README for this project, it would be good to have something like that installed that checks maybe every month and on PRs so we hear about it if links break.

Add Travis-CI

Now that we have a (simple) program, we could add Travis-CI so students could see the automatic builds.

We'd have to set up some sort of build system, and preferably some basic tests, but at a minimum it would verify that the program compiles and runs.

Fix inconsistency in how spacing is handled by Checkstyle

@jpwalbran pointed out on Slack that Checkstyle isn't being super consistent about spacing around braces:

I noticed a thing about the checkstyle. As part of some of the tests for lab 2, we’d have a line like

queryParams.put("orderBy", Arrays.asList(new String[] {"body"}));

This passes checkstyle fine. However,

queryParams.put("orderBy", Arrays.asList(new String[] { "body" }));

This does not, because of the space between { and "body".
The thing that I noticed was that

queryParams.put("orderBy", Arrays.asList(new String[] {"body" }));

also passes checkstyle, and I feel that it shouldn’t.

It's not our job to "fix Checkstyle", but it is weird that there is this inconsistency. I'm not 100% sure I "like" the brace/space rule anyway, so maybe we just remove that rule?

This would apply to almost all the subsequent labs, and the iteration template.

Add links to some GitHub guides

We should link to (at least):

• https://guides.github.com/features/mastering-markdown/
• https://guides.github.com/introduction/flow/

Update `MERGE_CONFLICTS.md` to match our new workflow

Much of the text in MERGE_CONFLICTS.md was written for a GitKraken/command-line-based workflow that didn't use pull requests. Our goal now is to move to a much more pull request oriented workflow, and that text really needs to be rewritten to better reflect that reality.

Document subtle "checkmark" when running tests in VSCode

If you run JUnit tests in VSCode with the nice "Run" hover thing, if the tests succeed you just get a very subtle checkmark and not other feedback. We should document that this is all you get, since it's not at all obvious and is likely to be a source of confusion/surprise for students.

It would probably be reasonable to have them run the tests with the code they initially clone, which will pass, and use that an an opportunity to explain the checkmark thing. We can then ask them to deliberately fail a test and see that in that case the "Java Test Report" panel pops up with more information.

Update README GitHub Actions badges to new format

See UMM-CSci-3601/3601-lab3_angular-javalin#525

Add instructions for setting up BCH, LGTM, and GitKraken for new org each semester

There should be a note at the top in the faculty setup section about the need to set up Better Code Hub and LGTM, and what to do.

Here's what I think I had to do:

Better Code Hub

• Install the Better Code Hub app in the new, semester specific organization.
  • Choose the free plan
  • Make sure you set the account (right above the green "go" button) to the new, semester specific organization
  • Click to install
• Go to the Better Code Hub interface, load up the new org, and run a check on the intro-to-git repo in that org (& using whatever name you used there)
• Click the button on the bottom left of that card to enable PR checks
• Update the badge URL to point to the correct org/repo

LGTM

• Install the LGTM app in the new, semester specific organization.
• Go to the LGTM interface and put the URL for the new intro-to-git repo in the "Follow a project" entry at the top
• Click the "Enable PR code reviews" button
• Update the badge URL if necessary

GitKraken

• Enable GitKraken on the new, semester specific organization
  • Go to your settings (assuming you're an admin on the org)
  • Click "Applications" in the "Account settings" panel on the left
  • Click "Authorized OAuth Apps" tab
  • Find and click "GitKraken" on that list
  • Click "Grant" for the new, semester specific org

Document setting up your commit e-mail in the README

@kklamberty shared this in #11 and I kept losing it, so I made it a new issue so I could find it.

We should add a little bit early in the README that tells them that they should configure their git e-mail for the Dungeon.

We had this announcement in Canvas last semester. Should we add this information to the lab somewhere?

Github/Git doesn't necessarily know who you are

Note: you should set your email in Git or Github so it knows who you are (your icon will show up and you get credit for your commits) rather than only knowing you on certain computers.

Setting your commit email address in git

Include command line instructions or create alternative version without webstorm

I'm trying to learn git but it would be useful to include a version that is IDE agnostic

Update the README.md when we tell where to put builder.append stuff

Right now, it says to add lines to main(), but really, the lines go in generateOutput().

Support multi-word names in the tests

The current test only allow single word names in the greetings. So "Nic says 'Hello!'" works, but "Nic McPhee says 'Hello!'" will fail. I think we should support more complex names, not just for situations where people want to include there last name (maybe we have two Matts or two Jennifers in the class) or someone's first name is more complex than just a simple string of characters. Since people's names might include non-ASCII characters and things like hyphens, we might want to use a regex like the one suggested in this StackOverflow answer.

Divide write-up into three parts

This write-up is quite long and intimidating, and @floogulinc and I think it would make sense to divide it up into three separate documents:

• The README is basically the background
• The first part is moved into its own file
• The second part as well

Reformat everything to 2 space indents

After some discussion yesterday, we decided to try to switch all the labs to follow Google's standards, which appear to be 2 space indents. See, e.g., the Angular .editorconfig.

So we need to update our .editorconfig and reformat all the files accordingly.

Update docs for S22

I made a number of changes to the write-up last year because we did the whole thing remotely due to COVID. I now need to undo those changes.

There are also a bunch of Markdown lint warnings I should deal with, and it never hurts to proofread things.

Improve write-up of compiling and running Java

The current write-up doesn't say anything useful about setting up IDEA in the lab so that people can compile and run Java. There also seem to be problems with people have JDK set up in IDEA.

Replace references to Slack with references to Discord

The world appears to have moved from Slack to Discord (at least for now), so we need to catch references to Slack and change them.

Fix Gradle warnings about deprecated features

When you run Gradle on this project, you get the following warning:

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.5/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

We should figure out what's happening here and fix it, both here an in the subsequent labs and iteration template.

This only happens with Gradle v8.5, so we need to do #115 first.

Add tests that require that names are in alphabetical order

As discussed in #18 there are various ways we could make the current tests more sophisticated, i.e., make them more likely to fail if people aren't paying attention. Probably the simplest way to do that would be to require that all the names in the messages are in alphabetical order. That wouldn't be terribly difficult, but it would probably trip up students who aren't reading carefully or remembering to run their tests.

Update the README.md to make it clear how to log in to GitHub from IntelliJ IDEA

By default, the option to login using a token is selected in IntelliJ IDEA, and we should maybe mention that you would want to choose the password option at that point to help people not get stuck.

Update the Rubric on Canvas

The current rubric doesn't reflect the changes to use pull requests and protected branches. That really should be fixed.

Create a "Code quality checks" document

There used to be a "Code quality checks" document in Lab 4 that explained what BetterCodeHub (BCH) and LooksGoodToMe (LGTM) were doing. We're not using either of those anymore, so that whole document got removed last year.

It would probably make sense to create a replacement that talks about what we're using now (CodeQL and DeepSource), and then copy that forward into the remaining labs.

Document (or automate) all the IDEA setup

IDEA seemed to be a lot more complicated this fall than last spring, and I'm not entirely sure why. Problems people had that I can remember (that the documentation said nothing about):

• No JDK
• Couldn't run Java program from IDEA even after a JDK was specified. (Does that have to be known by IDEA before you first clone the project?)
• The version control view/panel on the bottom left wasn't visible for many groups, and it's not obvious how to make it visible.
• How to (best) connect IDEA and Github isn't clear to me. It seems that different students set that up in different ways, with varying degrees of success and/or confusion.
• E-mails didn't always line up with Github's e-mails for people, so many of the commits aren't connected to an actual Github account.

I think some of the git/IDEA problems would have been less troublesome if people had watched the video before lab, but we didn't get the link out to them soon enough for anyone to have done that.

Part of this is awkward because it's hard to test without a new person with a working e-mail university address that's never been through the process.

Split off parts of the write-up into other READMEs

This lab write-up has gotten really long. We should probably extract more of the "background" info on different tools into their own READMEs like the Gradle README, so the "main" writeup can be shorter, with links into the appropriate parts of those other READMEs.

Upgrade Gradle when we upgrade IntelliJ

We tried upgrading Gradle to v5.1.1 (#29) but that broke the world because the somewhat out-of-date version of IntelliJ in the lab wasn't compatible with that version of Gradle. We resolved that for now by rolling Gradle back to 4.10.3 (5a5567e).

Once we upgrade IntelliJ we'll want to upgrade Gradle as well, here and in the subsequent labs.

Add JUnit 5 module to the project

JUnit 5 does not seem to work by default in the our lab. I think the trouble is that we might not have Maven Repository defined somewhere, because there does seem to be an attempt at including this module.

I couldn't push a change to `.github/workflows/gradle.yaml` from GitKraken

I changed the JDK version in .github/workflows/gradle.yaml (which specifies the info for GitHub Actions) and GitKraken "failed" when I tried to push. The message fades away fairly quickly, but here is what I think is the core info:

Refusing to allow an OAuth App to create or update workflow without workflow scope.

My guess (but it's only a guess) is that the problem is that @floogulinc used the Java CI template but then included gradle actions. There is a Gradle Command template for GitHub Actions and I have a feeling that this is what we're supposed to be using?

I tried doing the push from the command line, and it pushed fine, so it's clearly GitKraken being "smart" about something here. The action also succeeded fine, so whatever the problem is it's a "this is how you should do things" as opposed to "this is how you must do things" kind of issue.

fix any place that says the repo will be private to say nothing or public

This repo doesn't need to be private. If we're not making it private, we should be consistent about how we talk about it.

Upgrade Gradle wrapper and JDK version

This PR on the iteration template should basically get us there. We might need to add a settings.gradle file to hold the foojay resolver config into.

Update README.md to choose one approach for git usage for each part

The current version of the README.md instructions explains how to use git from the command line AND how to use GitHub from within IntelliJ for almost every aspect of the lab. This made it challenging to help people since we didn't know their trajectory. We might consider making them use a command line and plain editor for the first part (pronouns and github username part) and IntelliJ IDEA for the second part. This might also be a good place to include a couple hints about VIM.

Clarify what repo to clone

The current writeup tells how to clone the repo and has an example of what the url might look like... but some groups copied that example rather than following the instructions of how to do this.

Add settings app to all the 3601 repos

@floogulinc found this GitHub Settings app that should allow us to specify the "default" settings for all our projects. By setting that in a file in the repo, it'll be copied over to the repos created by GitHub classroom so all the copies will automatically have the desired settings.

Neither of us know any more than a tiny bit at the moment, so it's not entirely clear that we want to use this, or how to best use it. Giving it a try on this lab would be a reasonable start.

Test issue

We want to see what happens automagically in ZenHub with pull requests.

Add an editor config file

Apparently (according to @floogulinc) there is an editor config standard that IDEA will pick up that allows one to specify things like spaces vs. tabs in an editor independent fashion.

Switch default branch to `main`

As per "Replacing master with main in GitHub", which has instructions on how to do it.

• ❗ Update the branch reference in the BetterGitHub badge. Changing the default branch may also "break" things on LGTM so that will need to be checked as well.
• ❗ Update the branch protections so main is now protected.
• ❗ Update any open pull requests to target main instead of master.

Add reasonable use of Markdown as an explicit requirement

Several people really didn't get their content formatted sensibly in S17, and we should probably require that they do that as part of the assignment.

The rubric might also want to be updated to make that worth more than just 1 point once it's made explicit.

Remove question to KK

I left a question to KK in the lab write-up that needs to be removed. It was removed from the S17 classroom version, so I think I can cherry pick that commit back to here?

Say something about new "Do you trust these folks?" question in VS Code

When you first open a new project in VS Code you get asked “Do you trust the authors of the files in this folder?”. This is a good question, and we don't say anything about it in the write-up. They should click the “Yes, I trust the authors” button.

Upgrade Gradle to v7.3.3

We presumably want to upgrade this Gradle and all the other Java-based-labs to the latest version, which is currently 7.3.3.

Upgrade to Gradle v5

The current version of Gradle is 5.0.0 and we're using 3.1 in the labs.

I have no idea how easy/hard this will be and how it might affect things. At a minimum, I suspect it will make on-line documentation more useful. I tried changing testCompile to testImplementation to match this quick start guide and it didn't work, presumably because our Gradle is so old.

Different platforms guess different encodings for Java source files

cf. UMM-CSci-3601-S21/intro-to-git-S21#28

At the moment, we aren't telling Gradle what encoding we're using for our Java files, so Gradle is just guessing. (On *nix, it guesses UTF-8, but on Windows, it guesses Windows-1252.) This means that on Windows, any non-ASCII characters get misinterpreted.

To fix this problem, we should probably add lines to build.gradle specify the encoding of our Java files. (I recommend using UTF-8, which is very nice and widely-supported. 🙂)

See also https://stackoverflow.com/a/37627954 for more information on this problem.

Add the AllContributors app

The AllContributors app looks like it might be a neat way to ensure that everyone who has contributed to a project gets "automagically" recognized at the bottom of the README. Not a vital thing, but it would make sense as a thing to include if it's not hard.

If it works, it should be added to subsequent labs and the iteration template as well.

Add test code coverage

The intro-to-git lab doesn't include any test code coverage, and it probably should. We might not talk about it/use it in the actual lab time, but it would be good to have it there so people are used to seeing it and knowing that it exists.

This should be easy; all we need to do is copy over some of the dependencies, etc., from build.gradle in tje iteration template.

Add default formatting on saving

This was proposed some time ago by @floogulinc on the iteration template and I definitely think we want to do this. It might be nice to start here since that might be simpler and we can see what that looks like before wading into the swamp of doing it on the full project.