diff --git a/.vscode/settings.json b/.vscode/settings.json index bab0b8e..c147230 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,6 +4,7 @@ "bangbang", "gaurav", "gradlew", + "jacoco", "Phee", "unstage", "Unstaged", @@ -12,7 +13,7 @@ "editor.formatOnSave": true, "[java]": { "editor.suggest.snippetsPreventQuickSuggestions": false, - "editor.defaultFormatter": "redhat.java", + "editor.defaultFormatter": "redhat.java" }, "[markdown]": { // Prettier tends to mangle Markdown, so we'll use the Markdownlint extension instead. @@ -39,4 +40,4 @@ "**/.settings": true, "**/.factorypath": true } -} \ No newline at end of file +} diff --git a/PART_1_SHARE_INFO.md b/PART_1_SHARE_INFO.md index 07aa2d3..239c40a 100644 --- a/PART_1_SHARE_INFO.md +++ b/PART_1_SHARE_INFO.md @@ -12,6 +12,8 @@ - [Creating a page](#creating-a-page) - [`commit` your changes (locally)](#commit-your-changes-locally) - [`push`ing your work to GitHub](#pushing-your-work-to-github) + - [Personal Access Tokens](#personal-access-tokens) + - [Back to `git push`](#back-to-git-push) In this part of the lab we'll add everyone's names and GitHub usernames to the repository so we'll be able to figure out who GitHub user `MightyWombat259` @@ -52,6 +54,9 @@ that should take you to the shared repository on GitHub. From there you can get the URL for that repository from the green `Code` button visible on the "home page" for each repository on GitHub. + +![Green "Code" button and GitHub URL](./docs/images/GitHub-repo-URL.png) + See [GitHub's "Cloning a repository" tutorial](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) for examples. The URL should look like this: @@ -59,7 +64,7 @@ for examples. The URL should look like this: https://github.com/YOUR-ORG-OR-NAME/REPO.git ``` -where `YOUR-ORG-OR-NAME` is the a user name or (in our case) an organization name +where `YOUR-ORG-OR-NAME` is a user name or (in our case) an organization name and `REPO` is the name of the repository. ### Command line `clone` @@ -167,7 +172,7 @@ of the repo (the directory `intro-to-git`) and choose `Open`. When you first open a project in VS Code, it will ask you if you trust the authors of the project: -![](docs/images/VSCode-trust-dialog.png) +![VS Code "Do you trust the authors" dialog box](docs/images/VSCode-trust-dialog.png) This is important because VS Code and its extensions are quite powerful, and a malicious agent could hijack these @@ -200,11 +205,15 @@ open up `src -> main/java/hellos -> Main.java` and Java program. Now open up `src -> test/java/hellos -> HellosTest.java` and you should see our JUnit tests. +![`intro-to-git` file structure in VS Code](./docs/images/VSCode-file-structure.png) + > [JUnit is a widely used testing framework for Java](https://junit.org/junit5/docs/current/user-guide/#writing-tests). > A Junit test is a method that has the special `@Test` annotation and contains > one or more _assertions_ like `assertTrue` or `assertEquals`. Tests _pass_ > if all the assertions in a test method are true; they _fail_ if any assertion -> is false. +> is false. You won't have to edit or directly work with the JUnit tests in this +> lab, but you will work with JUnit in subsequent labs and your project iterations. +> Feel free to ask questions about the test code. As well as running tests from an "external" terminal window, you can also run them from a terminal inside VS Code. Go to the "Terminal" menu and select @@ -230,7 +239,8 @@ lab we'll create a new file in that directory for each group, each of which will contain your real names and your GitHub user names. Sometimes it's easy for us to figure out how those names relate, but if your GitHub user name is `UnicornWizard375` it's not always obvious who in the -class that is, especially if you don't always wear your wizarding regalia to lab. +class that is, especially if you don't always wear your single-horned +wizarding regalia to lab. There will be several steps to this process, each of which is described in more detail below: @@ -254,18 +264,20 @@ approach is: you want the new file to go in. - Right click on that directory and choose "New File". - Enter its name (see below for naming rules for this step). Make sure - to include the appropriate extension (e.g., `.md` or `java`) so + to include the appropriate extension (e.g., `.md` or `.java`) so VS Code will know how to handle the file and its contents. - Press Enter/Return and VS Code will create your new (empty) file and open an editing pane for you to start working in it. +![Creating a new file in VS Code](./docs/images/VSCode-new-file.png) + Each contact info page should: - Be created in the `user_info` directory. - Be named `.md`, e.g., `Pat_and_Chris.md` - Contain at least: - Your preferred names (e.g., "Nic" or "KK") - - [Your pronouns](https://www.mypronouns.org/) + - [Your pronouns](https://www.mypronouns.org/) (e.g., "she/her/hers", "he/him/his", or "they/them/theirs") - Your GitHub usernames (so we can figure out who `UnicornWizard375` is in real life) @@ -354,10 +366,10 @@ you can save and exit the editor. > If you've set up a GUI editor like VS Code > to be your editor for `git` commit messages, then you may need to save > and close the editor window for the commit message before `git` will -> recognize that you're done editing the message. +> recognize that you're done editing the message. That should finalize +> the commit. -That should finalize the commit, and you should get -output that looks something like: +After finishing the commit, you should get output that looks something like: ```text [main 47d9c89] Add the info for Pat and Chris to `user_info/KK_and_Nic.md`. @@ -411,17 +423,63 @@ work up to the GitHub repository: git push ``` +#### Personal Access Tokens + :warning: You'll need to authenticate with GitHub at this point. So far all you've been doing with things like `git clone` and `git pull` is "reading" info from Github, and anyone can do that on a public repository (which this is). Now, however, you want to _change_ something, so you need to prove that you -have permission to make changes to the contents of the repository. How exactly -this will play out depends on your setup and what exactly GitHub is doing at -the moment. Hopefully it'll be fairly "obvious" how to authenticate after you -enter `git push`, but if not definitely ask! If it asks for a username and -password at some point, that will almost certainly need to be the info you -used when setting up your GitHub account. - +have permission to make changes to the contents of the repository. + +To make `git push` work on the command line you'll need [a GitHub _Personal +Access Token_ (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). +GitHub doesn't want you typing your GitHub password on the command line +(where there's no guarantee that it'll be encrypted), so they instead +have you get a PAT from their web site, and type that in on the command line +instead. You don't need PATs on things like GitKraken and VS Code because +they completely control the communication with GitHub's servers, and GitHub +can force them to use encrypted communication channels. + +PATs are basically short-lived "passwords" that you can use to authenticate with +GitHub up until they expire. They also have neat properties like the ability +to constrain a PAT to only work on a particular repository/project, or only +have certain permissions on that project, all helping limit the damage if +someone was able to get a copy of your PAT. + +To create a PAT for this lab, follow GitHub's ["Creating a fine grained personal access token"](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) +instructions. We're going to create a PAT that's entirely specific to this lab, +which means you'll need to create new PATs later in the semester if/when you +need them. You can go with the defaults for most of the options, but there will +be some questions/options you'll need to address when creating your PAT: + +- You can use whatever **Token name** makes sense to you for the token. +- I'd go with an **Expiration** of 7 days since we should be done with this lab + the end of the week. +- Under "Resource owner" you _have_ to select the organization for this semester's + Software Design course. That's probably something of the form `UMM-CSci-3601-S24`. +- Under **Repository access** choose "Only select repositories". Then choose + the repository with `intro-to-git` in the name from the "Select repositories" dropdown. +- Open the **Repository permissions** drop-down. You'll get a somewhat bewildering + set of options there, but all you need is to set "Contents" to "Read and write". + You can leave the rest alone. +- Ignore **Organization permissions**; you don't need to do anything there. + +:warning: :bangbang: Make sure you save that token somewhere safe. Once you +leave that page you won't be able to get back to it and you'll have to generate +a new token. They're also really long and no fun to type in, so you probably want +it in someplace you can access from a lab computer. + +#### Back to `git push` + +Now that we have a PAT sorted out, we can come back to `git push` and hopefully +authenticate properly. When you enter `git push`, it should essentially ask +for your user name and password: + +- It'll ask you for your `Username for 'https://github.com'`. +- It'll ask you for your `Password for 'https://@github.com'`. + This is where you paste (or type in) your PAT. + +Assuming all that worked the push should happen. Again, look for errors in the output of `git push`. If someone else managed to do a `git push` between when you did `git pull` and tried `git push`, `git` will complain and force you to do `git pull` again. Essentially you can never diff --git a/PART_2_JAVA_INTRODUCTIONS.md b/PART_2_JAVA_INTRODUCTIONS.md index 844119a..b541375 100644 --- a/PART_2_JAVA_INTRODUCTIONS.md +++ b/PART_2_JAVA_INTRODUCTIONS.md @@ -20,6 +20,8 @@ :bangbang: Don't move on to this next part until _everyone_ is done with the previous part. +:bangbang: You should definitely change _driver_ and _navigator_ roles now. + > :bangbang: :mage_woman: **Faculty** > > When the students get this part of the lab, we'll need to @@ -29,8 +31,6 @@ the previous part. > e.g., the tests fail or there aren't enough code > reviews. -:bangbang: You should definitely change _driver_ and _navigator_ roles now. - In this second part each group will make a small change to a simple Java program, `Hellos.java` in the `src/main/java/hellos` directory. Each group will make a small extension to that program in a way that virtually guarantees some sort @@ -63,7 +63,7 @@ GitHub account** as this will do two important things: for resolving merge conflicts. :bangbang: _If you haven't set up your GitHub Student Pack, you should do so before setting up GitKraken._ -After you've authenticated with GitHub, GitKraken will ask to setup +After you've authenticated with GitHub, GitKraken will ask to set up your `git` info; you should enter your name and whatever email you've used for GitHub. Once all the setup is finished, select `File -> Open` and navigate to the directory @@ -78,10 +78,12 @@ we have the latest version of the code. In GitKraken you can just click the changes that you didn't have, the history would update to show the new commits you just pulled down to your local repository. +![The "pull" button in GitKraken](./docs/images/GitKraken-pull.png) + ## Creating a branch -Before we get started on actually editing the program, we want to introduce -the concept of _branches_ in `git`, as they are a powerful tool for +Before we start actually editing the program, we want to introduce +the concept of _branches_ in `git`, which are a powerful tool for isolating in-progress work on a particular feature from other on-going work on the project. Creating and working in your own feature branch allows you to commit, @@ -105,22 +107,6 @@ lives, while active development, bug fixes, and the like happen in other development branches that are merged into `main` when that work is deemed "done done" (passes the tests, has been through a code review, etc.). -> Historically the default has actually been called `master`. One side-effect -> of the Black Lives Matter movement has been an increasing recognition of -> the painful connotations that term has for many people, and there have -> been [calls to change from `master` to the more neutral `main`](https://dev.to/afrodevgirl/replacing-master-with-main-in-github-2fjf). -> GitHub in fact did a lot of work to support changing the default naming for new projects, -> and provides tools to help automate changing the name of the default branch. -> See [their renaming repo](https://github.com/github/renaming) for the -> details. New, blank repositories will, for example, now -> have `main` as their default branch name, and they've provided tools for -> renaming your primary branch. -> -> There were a _lot_ of instances of `master` created when that was the -> default, so there are likely to be references to `master` as the default -> branch in older -> `git` examples and documentation for quite a while. - To illustrate the use of branches, we'll have each group create a new branch for their modification of the shared program. Assuming, for example, that we still have Pat and Chris, they would create a new branch called something @@ -130,12 +116,19 @@ In GitKraken we can do this by clicking the `Branch` button in the toolbar up at the top. It won't immediately look like anything actually happened, but there will be a text box to the left of the history diagram where the _HEAD_ (top) of `main` is. + +![Creating a new branch in GitKraken](./docs/images/GitKraken-create-a-branch.png) + Enter your branch name (e.g., `pat-and-chris-greetings`) there and hit return. It should now show (part of) `pat-and-chris-greetings` and a `+1` which indicates that there's another branch (`main`) whose HEAD is at the same place. You should also have `pat-and-chris-greetings` listed as a new branch under `LOCAL` in the explorer on the left, and it should be highlighted to indicate that it is the -currently _checked out_ branch. That means that any new commits you make will +currently _checked out_ branch. + +![After creating a new branch in GitKraken](./docs/images/GitKraken-with-new-branch.png) + +That means that any new commits you make will be _in that branch_ instead of in `main` as they were in the first half of this lab. @@ -144,14 +137,13 @@ command line as well. To create and move to a new branch in the command line you'd use something like ```bash -git checkout -b +git switch -c ``` -This creates the new branch and perform a `checkout` on that branch. -The `checkout` part of the process tells `git` to "switch over" to that new -branch, so subsequent commits will happen on that branch. You use -`git checkout` without the `-b` to just switch between existing branches; -the `-b` tells `git` that this is a new branch that needs to be created. +This creates the new branch and switches to that branch, so subsequent commits +will happen on that branch. You use +`git switch` without the `-c` to just switch between existing branches; +the `-c` tells `git` that this is a new branch that needs to be created. ## Edit the program @@ -169,7 +161,7 @@ method: builder.append(patSaysHello()); ``` -Here you'll replace `pat_says_hello` with method names that +Here you'll replace `patSaysHello` with a method name that reflects the name of the person providing the greeting. You should create one new method for _every_ person in your group. If your group is Pat and Chris, then you @@ -205,7 +197,7 @@ So let's fix that, by adding the necessary new methods somewhere down amongst the example methods; they should look something like: ```java - private static String chrisSaysHello() { + private String chrisSaysHello() { return "Chris says 'Hello!'\n"; } ``` @@ -380,9 +372,9 @@ collectively can. ### Create a pull request Go this repo on GitHub (on the web) and there's likely to be one or -more messages in a light yellow box near the top that say something like: +more messages in a light yellow box near the top like: -> **\** had recent pushes \ +![GitHub button to create a pull request](./docs/images/Create-pull-request-button.png) If you pushed recently, then one of these messages may will be about your branch. @@ -401,34 +393,34 @@ this pull request – what are you trying to accomplish and how did you do it? When all that's ready, click the green "Create pull request" button to actually create the pull request. -Once that's done, you want to request two or three reviewers. Click the gear -icon to the right of "Reviewers" in the right hand column of actions. Hopefully -there will be several people in the drop-down list; if so pick two or three at -random. You should always be able to just type in "NicMcPhee" to add me as a -reviewer, but you want to get a few other people in case I'm swamped. - ### You can't merge yet What you _want_ to do is merge this into `main` so your wonderful changes are -an official part of the project. You can't do it yet, though – the "Merge pull -request" button down at the bottom is grayed out. Before you can merge, at least -two things must be true: +an official part of the project. You can't do it yet, though. + +Before you can merge, the following things must be true: - A set of automated checks have to pass - Your pull request/branch has to be up-to-date with `main` -- At least one person has to review _and accept_ your pull request +- At least two people have to review _and accept_ your pull request + +In this example, all the automated checks are passing and the branch is +up-to-date with `main`, but there haven't been any reviews yet. + +![GitHub showing checks have passed, but missing reviews](./docs/images/Merging-blocked.png) #### Automated checks We use a feature called GitHub Actions to automate a set of checks on the lab and project repositories in this course. All those checks have to pass before -you can merge in your pull request. For this lab we have four checks: - -- "build": This runs `./gradlew check`, which compiles the code - and runs the JUnit tests. If these succeed you get a green check mark, and you get a red x if anything fails. - and runs several checks. If all of these succeed you get a check mark (:white_check_mark:), and you get a red x (:x:) if anything fails. - - It runs the JUnit tests - - It confirms that the test coverage is at least 80%. (This should +you can merge in your pull request. For this lab we have several checks: + +- "Java / build": This runs `./gradlew check`, which compiles the code + and runs several checks. If all of these succeed you get a check mark + (:white_check_mark:), and you get a red x (:x:) if anything fails. + In particular "Java /build": + - Runs the JUnit tests and makes sure they pass. + - Confirms that the test coverage is at least 80%. (This should be trivially true as the tests that we've provided should automatically cover any new code that's added to `Hellos.java`) - "markdown-link-check": This checks that all the links in the @@ -436,8 +428,10 @@ you can merge in your pull request. For this lab we have four checks: the other end of that URI). You won't be adding or changing any links in this lab, so that should continue to pass without any concerns. -- "CodeQL": This triggers security checks in languages specified in our GitHub workflows -- "Analyze (java)": This checks some security things in the Java of this project (since we asked it to check Java) +- "CodeQL / Analyze (java-kotlin)": This triggers quality and security + checks on our Java code. +- "Check markdown links" makes sure that all the links in the Markdown + documents in this repository still actually work. So have a look at the bottom of your pull request and you should see the status of this check. If any of them have an orange/yellow dot next to them, then that tells you that check is still being processed (e.g., the tests are still @@ -498,7 +492,8 @@ have a section that looks something like: ``` What this rather odd syntax says is that Chris's `chris-greeting` branch has -a line that calls `chrisSaysHello()`, where `main` (which has Pat's changes) +a line that calls `chrisSaysHello()`, where the `main` branch (which has Pat's +previously committed changes) has a line that calls `patSaysHello()`. Everything between the `<<<<` line and the `====` line is what things look like in the `chris-greeting` branch, and everything between the `====` line and the `>>>>` line are what things @@ -510,8 +505,7 @@ There are numerous ways this conflict could have come about, such as: instead call the (supposedly different) method `chrisSaysHello()`. - Chris has renamed `patSaysHello()` to `chrisSaysHello()`, and wants to change the call to match this renaming. -- Chris wants to make _both_ function calls in some order, and `git` can't - begin to guess what the desired is. +- Chris wants to make _both_ function calls. Here `git` can't tell which of these happened, and thus can't "know" how to handle the merge. Thus it punts it to us, the human developers, to sort out. Sometimes @@ -535,11 +529,11 @@ conflicts, and you'd probably rather use that for more complex conflicts. See [our write-up on using GitKraken to deal with merge conflicts](docs/MERGE_CONFLICTS.md) for more examples and details. -:warning: :bangbang: At this point Chris (or you if you've been doing something +:bangbang: At this point Chris (or you if you've been doing something similar) will need to pull these changes back down to your copy if you want or need to make changes to your branch. The changes you've made by resolving conflicts in the web GUI _only_ affect the version of the -code on GitHub, so you have to pull if you want those changes to be +code on GitHub, so you have to `pull` if you want those changes to be reflected in your local copy as well. If, for example, Chris realizes here that the tests are failing because they have the alphabetical order wrong, they'll need to pull down these changes, fix the alphabetical order, push back @@ -623,9 +617,9 @@ Once you receive a positive review you can proceed to merge. If, however, you received a request to make some changes, look those over. Does the request make sense? Do you understand what (and why) it's being made? If not, _definitely_ ask the requestor for further information or explanation. You can post your own comment -on the pull request and/or contact them by other means (e.g., talk to them in person, -or use things like Discord or email). You probably want any important info to be captured -in the pull request, but sometimes it's useful to poke someone on another channel +on the pull request and/or contact them by other means (e.g., talk to them in person, +or use things like Slack or email). You probably want any important info to be captured +in the pull request, but sometimes it's useful to poke someone on another channel to get their attention. While you're waiting for them to re-review your pull request, check and make sure @@ -635,15 +629,28 @@ requests! ### Finally merge your pull request Let's assume you've _finally_ gotten all the checks to pass, you're up to date -with `main`, and you've gotten a positive pull request. Now the green -"Merge Pull Request" should enabled, so push that button! Make any updates -you want, and then click "Confirm merge". - -At this point your pull request should be merged in and your changes should now -be visible in `main` – your work is officially part of the project! You'll +with `main`, and you've gotten the necessary code review approvals. Click the +"Merge when ready" button to tell GitHub that you think everything is good, +and you're ready to merge this code in. You'll then be asked to "Confirm merge +when ready". + +If there's something still blocking the merge (a test is failing, or you're +still missing an approval), then GitHub will hold your pull request until everything +is OK. Once that happens, though, your pull request will be added to the +_merge queue_, which is a series of "good to go" pull requests waiting to +be merged into `main`. This process can take a few minutes because GitHub +re-runs all the checks just to make sure things are good, and if there are +several other pull requests ahead of you in the queue it could be a bit. +While you're waiting, do your colleagues a favor and go review some other +pull requests. + +Eventually, hopefully, your pull request will get be merged in and your +changes should now +be visible in `main` – your work is officially part of the project! If you +go back to your pull request page, you'll be given the option to "Delete branch", which will delete your work branch. Since the changes on that branch are now all merged into `main` it should be -safe to delete that branch, but you can leave it there if you prefer and +safe to delete that branch. You can, however, leave it there if you prefer and remove it in some "branch housekeeping" session you run later. ## Huzzah! We're done! :-) diff --git a/README.md b/README.md index a5402b5..95c3307 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,24 @@ # Introduction to `git` -!["Broken" badge to remind us to fix the URLs on the "real" badges](https://img.shields.io/badge/FIX_BADGES-Badges_below_need_to_be_updated-red) - > :bangbang: :mage_woman: **Faculty** > > Each semester _after creating the instance in GitHub Classroom_, > we need to (in the version of the repository generated by GitHub Classroom once you accept the assignment): > +> - [ ] Post the link on the LMS (e.g., Canvas) > - [ ] Create a team called "Everyone" -> - [ ] Fix the URLs in the badges below so they point to that semester's -> repository instead of the "starter" repo. +> - [ ] Go to , click on +> "GitKraken", and grant access to the new semester's organization > - [ ] Make sure we've added every student in the current semester > to that semester's organization so they'll have permission to -> push to this repo. +> push to this repo > - [ ] [Turn off branch protection](docs/FACULTY_BRANCH_PROTECTION_SETTINGS.md) -> so that students can `push`. -> - [ ] Remove this note and the broken badge above in the fork. +> so that students can `push` +> - [ ] Remove this note and the broken badge above in the fork > > We should leave these notes in the copy in the "starter" > repository so it's there each semester when we fork this. -[![Continuous integration status](../../actions/workflows/gradle.yaml/badge.svg)](../../actions/workflows/gradle.yaml) - - [Background](#background) - [Resources for learning `git` and friends](#resources-for-learning-git-and-friends) - [How we're going to use `git`](#how-were-going-to-use-git) @@ -77,7 +74,7 @@ of documentation we have in the `docs/` folder: - [A discussion of how to avoid merge conflicts and deal with them when they (inevitably) happen](docs/MERGE_CONFLICTS.md) - [An overview of the Gradle build tool and how we're using it in this lab](docs/Gradle_README.md) -You should also probably read [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). +You should also probably read GitHub's [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/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. @@ -104,7 +101,7 @@ tutorials listed above. > 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. +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 diff --git a/build.gradle b/build.gradle index 131762b..418513c 100644 --- a/build.gradle +++ b/build.gradle @@ -9,6 +9,9 @@ plugins { // Apply the application plugin to add support for building a CLI application. id 'application' + // Apply the java plugin to add support for Java. + id 'java' + // Apply the Jacoco plugin to add suppport for JUnit test coverage reports. id 'jacoco' } diff --git a/docs/FACULTY_BRANCH_PROTECTION_SETTINGS.md b/docs/FACULTY_BRANCH_PROTECTION_SETTINGS.md index 8f306b9..8b9828f 100644 --- a/docs/FACULTY_BRANCH_PROTECTION_SETTINGS.md +++ b/docs/FACULTY_BRANCH_PROTECTION_SETTINGS.md @@ -60,7 +60,19 @@ Then go through and check/enable the following options: - [ ] "Restrict who can dismiss pull request reviews" - [ ] "Require status checks to pass before merging" - [ ] "Require branches to be up to date before merging" - - [ ] Check "build" to turn that check on +- [ ] "Require merge queue" +- [ ] "Do not allow bypassing the above settings" + +You also need to add `build` to the set of required checks. Go to the +search box right below "Require branches to be up to date before merging", +search for "build", and select the "build" entry in the resulting +drop-down: + +![Finding `build` to add to the status checks](./images/Requiring-build-to-merge.png) + +You will have had to have had GitHub Actions run at least once for "build" +to show up in the list. That should have happened multiple times during +part one of the lab, though. This should prevent anyone from directly committing to `main`, forcing them to go through pull requests. Those PR will require at least two diff --git a/docs/Gradle_README.md b/docs/Gradle_README.md index 6b36a73..a822588 100644 --- a/docs/Gradle_README.md +++ b/docs/Gradle_README.md @@ -17,8 +17,14 @@ like (minus all the comments): ```groovy plugins { - id 'java' id 'application' + id 'jacoco' +} + +java { + toolchain { + languageVersion = JavaLanguageVersion.of(21) + } } repositories { @@ -26,12 +32,13 @@ repositories { } dependencies { - testImplementation 'org.junit.jupiter:junit-jupiter-api:5.5.2' - testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.5.2' + testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.1' + testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine' + testRuntimeOnly 'org.junit.platform:junit-platform-launcher' } application { - mainClassName = 'hellos.Hellos' + mainClass.set('hellos.Main') } test { @@ -39,10 +46,17 @@ test { } ``` -The two lines in the opening `plugins` section tell Gradle that this is a Java project -and that we want to build a stand-alone command-line application. +The two lines in the opening `plugins` section tell Gradle that we want to +build a stand-alone command-line application using Java. That actually gives us a _bunch_ of Gradle commands we can run that know -how to build, run, test, and deploy a Java application. +how to build, run, test, and deploy a Java application. The `jacoco` +plugin gives us tools for determining which parts of our code are covered +by our JUnit tests. + +The `java / toolchain` section specifies which version of Java we're using. +If Gradle can't find that version of Java on the computer you're using, it will +in fact download a project-specific copy of that version of Java and use it for +all the Gradle commands you run. The `repositories` section allows us to provide one or more repositories where Gradle can go to download libraries that our project depends on. We're using [`mavenCentral()`](https://search.maven.org/), which is the Maven Central Repository. @@ -62,7 +76,10 @@ qualified path, so in this case `hellos.Hellos` for the class `Hellos` in the pa In the `test` section we specify (via `useJunitPlatform()`) that we want Gradle to use JUnit to run our tests. If we were using a different Java test platform like -[TestNG](https://testng.org/doc/) then we would indicate that here. +[TestNG](https://testng.org/doc/) then we would indicate that here. There's some +additional configuration there that tells Gradle to use Jacoco to compute the +test coverage, and fail the build if our tests don't cover at least 80% of our +code. There are a _lot_ more nifty things you can set up in a `build.gradle` file, but this is all we need for this lab. @@ -70,7 +87,7 @@ but this is all we need for this lab. ## Running Gradle This simple setup creates a _lot_ of Gradle commands that we can use to build and -run our application. These can be done through IDEA or on the command line. +run our application. These can be done through VS Code or on the command line. ### Gradle on the command line diff --git a/docs/MERGE_CONFLICTS.md b/docs/MERGE_CONFLICTS.md index 12735d2..bac71d6 100644 --- a/docs/MERGE_CONFLICTS.md +++ b/docs/MERGE_CONFLICTS.md @@ -75,19 +75,20 @@ Many projects, including ours, block pull requests from out-of-date branches as a safety measure. So, you'll need to bring your branches up to date before merging your pull requests. -In general you want to keep your branch up-to-date with any -changes that have been merged into `main` as much as you can. +In general you want to keep your branch as up-to-date with `main` +as possible, merging changed from `main` into your branch +as often as you can. The longer you wait to merge changes in from `main`, the harder it will be and the more likely it is that you'll have merge conflicts when you do. Branches that get really disconnected from `main` often get abandoned because merging that work in just becomes too much -hassle, and lots of potentially good work has been "lost" +hassle, and lots of potentially good work gets "lost" that way. In the next section we'll go over the mechanics of getting -your branch up to do with `main`. +your branch up to date with `main`. ## How to deal with merge conflicts @@ -108,14 +109,15 @@ The basic process you'll typically want to follow is: committed. If there is an `WIP` entry, you can click on it to see what's not yet committed. (There can be times where you have changes you don't yet want to commit, but these can interfere with the process. Feel free - to create a _stash_ as a way to temporarily store those changes so you + to [create a _stash_](https://help.gitkraken.com/gitkraken-client/stashing/) + as a way to temporarily store those changes so you can get them back later.) - - Or use `git status` on the command line to confirm that everything you - mean to have committed is in fact committed. + - Alternatively, you can use `git status` on the command line to confirm that + everything you meant to have committed is in fact committed. - Check out the `main` branch - Double click on `main` in the branch listing on the left-hand side of GitKraken. - - Or `git checkout main` on the command line + - Or `git switch main` on the command line At this point you should be on the `main` branch, and all your work on your new feature should "disappear" in VS Code. Don't worry, it's still @@ -143,7 +145,7 @@ your feature branch. `my-cool-feature`). That will bring up a dialog with several options. Go with the first one (probably "Merge", but possibly "Fast-forward"). - On the command line - - Run `git checkout my-cool-feature` to check out the + - Run `git switch -c my-cool-feature` to check out the feature branch - Then run `git merge main` to merge in the new changes from `main`. - On the command line, `git merge ` will merge the specified @@ -196,8 +198,8 @@ The sequence of events in GitKraken is likely to look something like: ### Push your feature branch to GitHub -When that's all done then the merge conflict will be _resolved_ in `git` -terminology and you'll be (nearly) read to `push` your changes. +When that's all done then the merge conflict will be (in `git` terminology) +_resolved_, and you'll be (nearly) read to `push` your changes. Before you do that, however, you should carefully proofread any code that's modified in resolving a merge conflict, @@ -213,7 +215,7 @@ Once that's all happy, you should `push` your feature branch up to GitHub! Hopefully, at this point, your branch should be up-to-date with `main`. Occasionally, however, someone will manage to sneak in another change to `main` while you were resolving your merge conflict—and that's actually -pretty likely today with so many people working in parallel on the same +pretty likely in this lab with so many people working in parallel on the same file. If that happens, `pull` the latest `main` branch again, merge it into your diff --git a/docs/images/Create-pull-request-button.png b/docs/images/Create-pull-request-button.png new file mode 100644 index 0000000..4788ac3 Binary files /dev/null and b/docs/images/Create-pull-request-button.png differ diff --git a/docs/images/GitHub-repo-URL.png b/docs/images/GitHub-repo-URL.png new file mode 100644 index 0000000..f05463f Binary files /dev/null and b/docs/images/GitHub-repo-URL.png differ diff --git a/docs/images/GitKraken-create-a-branch.png b/docs/images/GitKraken-create-a-branch.png new file mode 100644 index 0000000..3c8972c Binary files /dev/null and b/docs/images/GitKraken-create-a-branch.png differ diff --git a/docs/images/GitKraken-pull.png b/docs/images/GitKraken-pull.png new file mode 100644 index 0000000..22d8165 Binary files /dev/null and b/docs/images/GitKraken-pull.png differ diff --git a/docs/images/GitKraken-with-new-branch.png b/docs/images/GitKraken-with-new-branch.png new file mode 100644 index 0000000..8d283ee Binary files /dev/null and b/docs/images/GitKraken-with-new-branch.png differ diff --git a/docs/images/Merging-blocked.png b/docs/images/Merging-blocked.png new file mode 100644 index 0000000..f68bc59 Binary files /dev/null and b/docs/images/Merging-blocked.png differ diff --git a/docs/images/Requiring-build-to-merge.png b/docs/images/Requiring-build-to-merge.png new file mode 100644 index 0000000..33cf850 Binary files /dev/null and b/docs/images/Requiring-build-to-merge.png differ diff --git a/docs/images/VSCode-file-structure.png b/docs/images/VSCode-file-structure.png new file mode 100644 index 0000000..81195e2 Binary files /dev/null and b/docs/images/VSCode-file-structure.png differ diff --git a/docs/images/VSCode-new-file.png b/docs/images/VSCode-new-file.png new file mode 100644 index 0000000..37b0223 Binary files /dev/null and b/docs/images/VSCode-new-file.png differ