diff --git a/Resources.html b/Resources.html index e6a8517..4f07fe0 100644 --- a/Resources.html +++ b/Resources.html @@ -3,69 +3,85 @@ layout: default --- - + function changeVideo(index) { + + document.getElementById("videoframe").src = getVideoUrl(index); + } +
-
+
-
- - +
+ +
-
+
-
+ +
@@ -76,12 +92,14 @@
-
+
    @@ -93,30 +111,36 @@
-
+
-
+
+ src="" frameborder="0" + allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" + allowfullscreen>
@@ -11,6 +12,7 @@
+ diff --git a/_layouts/load-tutorial.js b/_layouts/load-tutorial.js new file mode 100644 index 0000000..ebdf544 --- /dev/null +++ b/_layouts/load-tutorial.js @@ -0,0 +1,60 @@ +const json = JSON.parse(` +{{ content }} +`) + +function loadProgressButtons(currentPermalink) { + let i; + if (currentPermalink.endsWith("/")) { + setProgressLinks(null, json["articles"][0]["file"]) + document.getElementById("tutorial-home").hidden = true; + return; + } + // alert(json) // debug + // alert(json["articles"]); // debug + for (i = 0; i < json["articles"].length; i++) { + let element = json["articles"][i]; + if (element["file"] === currentPermalink) { + setProgressLinks((i === 0)? null : json["articles"][i-1]["file"], + (i === json["articles"].length - 1)? null : json["articles"][i+1]["file"]) + break; + } + } + function setProgressLinks(prevLink, nextLink) { + let prev = document.getElementById("previous"); + let next = document.getElementById("next"); + if (prevLink === null) { + prev.hidden = true; + } else { + prev.setAttribute("href", prevLink); + } + if (nextLink === null) { + next.hidden = true; + } else { + next.setAttribute("href", nextLink); + } + } +} + +function loadSidebar(currentPermalink) { + // alert("loadSidebar() called"); // debug + let parent = document.getElementById("sidebar"); + json["articles"].forEach(function (current, idx, arr) { + let element = document.createElement("a"); + element.className = "sidebar-item"; + element.setAttribute("href", current["file"]); + element.text = current["name"]; + if (current["file"] === currentPermalink) { + document.getElementById("tutorial-intro").className -= " active"; + element.className += " active"; + } + parent.appendChild(element); + }); +} + +function setTitle(currentPermalink) { + let header = document.getElementById("title"); + + let currentfile = json["articles"].filter(article => article["file"] === currentPermalink)[0]; + header.id = currentfile["name"].replace(" ", "-").replace("/", "").toLowerCase(); + header.innerText = currentfile["name"]; +} diff --git a/_layouts/tutorial.html b/_layouts/tutorial.html new file mode 100644 index 0000000..3136d7b --- /dev/null +++ b/_layouts/tutorial.html @@ -0,0 +1,25 @@ +--- +layout: default +--- + + + + + + +
+ + + Tutorial Home + + +
+

+ + {{ content }} +
+
+ + \ No newline at end of file diff --git a/assets/css/sidenav.css b/assets/css/sidenav.css new file mode 100644 index 0000000..7c6d997 --- /dev/null +++ b/assets/css/sidenav.css @@ -0,0 +1,117 @@ +.sidenav { + height: 90%; /* Full-height: remove this if you want "auto" height */ + width: auto; /* Set the width of the sidebar */ + /*position: page; !* Fixed Sidebar (stay in place on scroll) *!*/ + z-index: 1; /* Stay on top */ + /*top: ; !* Stay at the top *!*/ + left: 0; + background-color: #111; /* Black */ + overflow-x: hidden; /* Disable horizontal scroll */ + padding-top: 0; +} + +/* The navigation menu links */ +.sidenav a { + padding: 6px 8px 6px 6px; + text-decoration: none; + font-size: 16px; + display: block; +} + +.sidenav a.active { + background: #012265; +} + +/* When you mouse over the navigation links, change their color */ +.jumbotron { + top: 0; + width: 50%; + padding: 10px; +} + +#previous { + font-weight: bold; + justify-self: left; + background: #d3af37; + color: #012265 !important; + padding: 0 3%; +} + +#next { + font-weight: bold; + justify-self: right; + background: #d3af37; + color: #012265 !important; + padding: 0 3%; +} + +#tutorial-home { + font-weight: bold; + padding: 0 3%; + justify-self: center; + background: #d3af37; + color: #012265 !important; +} + + +/* The side navigation menu */ +.sidebar { + margin: 0; + padding: 0; + width: 200px; + background-color: #001e59; + position: fixed; + height: 100%; + overflow: auto; +} + +/* Sidebar links */ +.sidebar a { + font-weight: bold; + display: block; + padding: 16px; + text-decoration: none; +} + +/* Active/current link */ +.sidebar a.active { + background-color: #d3af37; + color: #001e59 !important; +} + +/* Links on mouse-over */ +.sidebar a:hover:not(.active) { + background-color: #555; +} + +/* Page content. The value of the margin-left property should match the value of the sidebar's width property */ +div.jumbotron { + margin-left: 200px !important; + padding: 1px 16px; + height: 100%; +} + +/* On screens that are less than 700px wide, make the sidebar into a topbar */ +@media screen and (max-width: 700px) { + .sidebar { + width: 100%; + height: auto; + position: relative; + } + + .sidebar a { + float: left; + } + + div.content { + margin-left: 0; + } +} + +/* On screens that are less than 400px, display the bar vertically, instead of horizontally */ +@media screen and (max-width: 400px) { + .sidebar a { + text-align: center; + float: none; + } +} \ No newline at end of file diff --git a/assets/css/styles.css b/assets/css/styles.css index ab280cd..2bf8b09 100644 --- a/assets/css/styles.css +++ b/assets/css/styles.css @@ -31,6 +31,7 @@ p { } .navbar { + float: top; background-color: #001e59; } @@ -249,16 +250,29 @@ h1, h2, h3 { color: #d3af37; } -span5 { +span { color: #d3af37 } p { text-indent: 30px; - color: #d3af37 + color: #d3af37; } div { background-color: #012265; } +img { + max-width: 100%; + max-height: 100%; + object-fit: contain; +} + +.jumbotron { + justify-content: center; +} + +p a { + text-decoration: #d3af37 underline; +} \ No newline at end of file diff --git a/assets/css/tabs.css b/assets/css/tabs.css index 7ee8bac..abdd959 100644 --- a/assets/css/tabs.css +++ b/assets/css/tabs.css @@ -3,6 +3,7 @@ overflow: hidden; border: 1px solid #d3af37; background-color: #00459c; + margin-bottom: 10px; } /* Style the buttons that are used to open the tab content */ @@ -19,7 +20,7 @@ /* Change background color of buttons on hover */ .tab button:hover { - background-color: #dddddd; + background-color: #555; } /* Create an active/current tablink class */ @@ -35,4 +36,16 @@ button.tablinks.active { padding: 6px 12px; border: 1px solid #d3af37; border-top: none; + margin-bottom: 16px; +} + +/* quote formatting is here to avoid formatting main page quote */ +blockquote { + border-left: 10px solid #d3af37; + margin: 1.5em 10px; + padding: 0.5em 10px; + +} +blockquote p { + display: inline; } \ No newline at end of file diff --git a/scripts/tabs.js b/scripts/tabs.js new file mode 100644 index 0000000..6dbf277 --- /dev/null +++ b/scripts/tabs.js @@ -0,0 +1,66 @@ +const detailElements = Array.from(document.getElementsByTagName("details")); + + +for (let i = 0; i < detailElements.length; i++) { + // alert(detailElements[i].id); + replaceElement(detailElements[i]); +} + +function replaceElement(element) { + const innerHtml = element.innerHTML; + const parent = element.parentElement; + const newElement = document.createElement("div"); + newElement.className = "tabcontent"; + newElement.id = element.id; + newElement.innerHTML = innerHtml; + // alert(newElement.id); // debug + element.replaceWith(newElement); +} + +function switchTo(evt, option) { + // Declare all variables + let i, tabcontent, tablinks; + const key = getKey(option); + + // Get all elements with class="tabcontent" and hide them + tabcontent = document.getElementsByClassName("tabcontent"); + for (i = 0; i < tabcontent.length; i++) { + if (getKey(tabcontent[i].id) === key) { + tabcontent[i].style.display = "none"; + } + } + + // Get all elements with class="tablinks" and remove the class "active" + tablinks = document.getElementsByClassName("tablinks"); + for (i = 0; i < tablinks.length; i++) { + // alert("key = " + key + tablinks[i].id + "i= " + i); + // if (getKey(tablinks[i].id).normalize() === key.normalize()) { + tablinks[i].className = tablinks[i].className.replace(" active", ""); + // } + } + + // Show the current tab, and add an "active" class to the button that opened the tab + document.getElementById(option).style.display = "block"; + // opt.color = "#012265 !important"; + evt.currentTarget.className += " active"; + evt.currentTarget.fontcolor = "#012265 !important;" +} + +let regex = /(\w+)-(\w+)/; + +function getKey(id) { + // alert("tried to get key for " + id); + const match = regex.exec(id); + // alert('id= ' + id + ' match= ' + match); // debug + const key = match[2]; + // const platform = match[1]; + return key; +} + +function getPlatform(id) { + const match = regex.exec(id); + // alert('id= ' + id + ' match= ' + match); // debug + let key = match[2]; + let platform = match[1]; + return platform; +} \ No newline at end of file diff --git a/tutorials/git/commit.md b/tutorials/git/commit.md new file mode 100644 index 0000000..cf2a32a --- /dev/null +++ b/tutorials/git/commit.md @@ -0,0 +1,60 @@ +--- +permalink: /tutorials/git/commit.html +layout: tutorial +--- +Commits can be thought of as points in the history of the repository, or groups of changes. +Each commit should be given a meaningful name that sums up the changes in that commit. +Please avoid situations like this: + +![xkcd](https://imgs.xkcd.com/comics/git_commit.png) + +Before creating the commit itself, you can choose what changes will be _`add`ed_ to the commit. + +
+ + + +
+ +
+ +To add files and changes, use `git add`: +```ps +git add file1 file2 file3 +``` +> The `*` wildcard can be used to replace any amount of characters: +`git add *.java` will add all Java files in the project. + +To create a commit, use `git commit`: +```ps +git commit -m "message" +``` + +
+
+ +Use the checkboxes on the left to select the files to add. +Write the commit message at the bottom, and press `Commit`. + +[](img/ghd-commit.png) + +
+
+ +> In IntelliJ 2020.3 and later, there are two git interfaces. +You can switch between the two by checking `Version Control > Commit > Use non-modal commit interface` +and `Version Control > Git > Enable staging area` in the settings. + +Click the green checkmark at the top-right. + +A window (the modal commit interface), or a panel on the left (the non-modal commit interface) should open. +Select the files and changes to commit with the checkboxes (staging area disabled), or by moving +changes to the `Staged` list with the `+` and `-` (staging area enabled - changes in `Staged` will be committed). + +In both, you can double-click a file name to see the changes. + +Write the commit message and press `Commit`. + +
+ +
\ No newline at end of file diff --git a/tutorials/git/create-branch.md b/tutorials/git/create-branch.md new file mode 100644 index 0000000..a4cfe30 --- /dev/null +++ b/tutorials/git/create-branch.md @@ -0,0 +1,112 @@ +--- +permalink: /tutorials/git/create-branch.html +layout: tutorial +--- +Creating a new branch allows you to add commits on a parallel version of the repository. +This can be used to test new features and not affect the `main` branch. +Later, the changes made in the branch can be added to the `main` branch once they are tested. + +### Specifying the branch base +Before creating a new branch, you want to make sure that you are _basing_ the branch on the right commit - the last commit on the `main` branch. The _base_ commit of a branch is the last commit that is shared with the other branches. A branch can be moved to a different _base_ using _`rebase`_, but rebasing should be avoided unless needed. + +##### Pulling `origin` +To make sure that we are on the latest `main`, we _`pull`_ the latest changes from GitHub (`origin`): + +
+ + + +
+ +
+ +```ps +git pull origin +``` + +
+
+ +![](img/ghd-pull.png) + +Click `Fetch Origin`. + +
+
+ +The current branch name should be in the bottom-left corner. + +![](img/ij-pull.png) + +If prompted, select `Rebase`. + +
+ +##### Switching to `main` +We can make sure we're on `main` (in older repositories the main branch might be named `master`): + +
+ + + +
+ +
+ +This command in any console (CMD, Powershell, Bash) will switch to the `main` branch. +```ps +git switch main +``` + +
+
+ +![](img/ghd-branch.png) + +If a different branch name is displayed, switch to `main` by clicking on the display and selecting +`main`. + +
+
+ +The current branch name should be in the bottom-left corner. + +![](img/ij-branch.png) + +If a different branch name is displayed, switch to `main` by opening the Branches panel (click on +the branch name) and then select `main > Checkout`. + +
+ +### Creating a new branch +Now that we have the right base, create a new branch: + +
+ + + +
+ +
+ +This command will create a new branch named `mybranch` based on the current one. +```ps +git switch -c mybranch +``` + +
+
+ +![](img/ghd-create-branch.png) + +Click `New Branch` and enter the name for the new branch. + +
+
+ +Open `Git > New Branch` from the top menu, and enter a name for the new branch. +Leave the `Checkout Branch` checkbox selected - otherwise you won't be switched to the new branch. + +
+ +
\ No newline at end of file diff --git a/tutorials/git/git.json b/tutorials/git/git.json new file mode 100644 index 0000000..a7f16ce --- /dev/null +++ b/tutorials/git/git.json @@ -0,0 +1,44 @@ +--- +layout: load-tutorial +permalink: /tutorials/git/load-tutorial.js +--- +{ + "name": "git", + "articles": [ + { + "index": 0, + "file": "/tutorials/git/create-branch.html", + "name": "Create a Branch" + }, + { + "index": 1, + "file": "/tutorials/git/commit.html", + "name": "Add and Commit Changes" + }, + { + "index": 2, + "file": "/tutorials/git/push.html", + "name": "Push Commits" + }, + { + "index": 3, + "file": "/tutorials/git/create-pr.html", + "name": "Submit a Pull Request" + }, + { + "index": 4, + "file": "/tutorials/git/reviews.html", + "name": "Reviews" + }, + { + "index": 5, + "file": "/tutorials/git/rebase.html", + "name": "Rebase" + }, + { + "index": 6, + "file": "/tutorials/git/squash-merge.html", + "name": "Squash/Merge PR" + } + ] +} diff --git a/tutorials/git/img/create-pr.png b/tutorials/git/img/create-pr.png new file mode 100644 index 0000000..15d186b Binary files /dev/null and b/tutorials/git/img/create-pr.png differ diff --git a/tutorials/git/img/ghd-branch.png b/tutorials/git/img/ghd-branch.png new file mode 100644 index 0000000..1e4d44e Binary files /dev/null and b/tutorials/git/img/ghd-branch.png differ diff --git a/tutorials/git/img/ghd-commit.png b/tutorials/git/img/ghd-commit.png new file mode 100644 index 0000000..f44aa67 Binary files /dev/null and b/tutorials/git/img/ghd-commit.png differ diff --git a/tutorials/git/img/ghd-create-branch.png b/tutorials/git/img/ghd-create-branch.png new file mode 100644 index 0000000..46692ab Binary files /dev/null and b/tutorials/git/img/ghd-create-branch.png differ diff --git a/tutorials/git/img/ghd-pr.png b/tutorials/git/img/ghd-pr.png new file mode 100644 index 0000000..4b967c8 Binary files /dev/null and b/tutorials/git/img/ghd-pr.png differ diff --git a/tutorials/git/img/ghd-pull.png b/tutorials/git/img/ghd-pull.png new file mode 100644 index 0000000..ce98178 Binary files /dev/null and b/tutorials/git/img/ghd-pull.png differ diff --git a/tutorials/git/img/ghd-push.png b/tutorials/git/img/ghd-push.png new file mode 100644 index 0000000..24bacee Binary files /dev/null and b/tutorials/git/img/ghd-push.png differ diff --git a/tutorials/git/img/git-logo.png b/tutorials/git/img/git-logo.png new file mode 100644 index 0000000..c8586d0 Binary files /dev/null and b/tutorials/git/img/git-logo.png differ diff --git a/tutorials/git/img/git-process.drawio.svg b/tutorials/git/img/git-process.drawio.svg new file mode 100644 index 0000000..344abac --- /dev/null +++ b/tutorials/git/img/git-process.drawio.svg @@ -0,0 +1,3 @@ + + +
Create Branch
Create Branch
Edit Files
Edit Files
Add & Commit Changes
Add & Commit Chan...
Push Commits
Push Commits
Submit PR
Submit PR
Reviews
Reviews
Address Reviews
Address Reviews
Rebase
Rebase
Squash & Merge
Squash & MergeViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/tutorials/git/img/git-workflow.drawio.svg b/tutorials/git/img/git-workflow.drawio.svg new file mode 100644 index 0000000..d7951d1 --- /dev/null +++ b/tutorials/git/img/git-workflow.drawio.svg @@ -0,0 +1,3 @@ + + +
master
master
example
example
The main branch
The main branch
Your feature branch
Your feature branch
Squash PR into main
Squash PR into mainViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/tutorials/git/img/ij-branch.png b/tutorials/git/img/ij-branch.png new file mode 100644 index 0000000..b250052 Binary files /dev/null and b/tutorials/git/img/ij-branch.png differ diff --git a/tutorials/git/img/ij-create-branch.png b/tutorials/git/img/ij-create-branch.png new file mode 100644 index 0000000..288bb77 Binary files /dev/null and b/tutorials/git/img/ij-create-branch.png differ diff --git a/tutorials/git/img/ij-forcepush.png b/tutorials/git/img/ij-forcepush.png new file mode 100644 index 0000000..b73dd91 Binary files /dev/null and b/tutorials/git/img/ij-forcepush.png differ diff --git a/tutorials/git/img/ij-pull.png b/tutorials/git/img/ij-pull.png new file mode 100644 index 0000000..40d17c2 Binary files /dev/null and b/tutorials/git/img/ij-pull.png differ diff --git a/tutorials/git/img/ij-push.png b/tutorials/git/img/ij-push.png new file mode 100644 index 0000000..93cea1e Binary files /dev/null and b/tutorials/git/img/ij-push.png differ diff --git a/tutorials/git/img/ij-rebase.png b/tutorials/git/img/ij-rebase.png new file mode 100644 index 0000000..dfebedf Binary files /dev/null and b/tutorials/git/img/ij-rebase.png differ diff --git a/tutorials/git/img/merge.png b/tutorials/git/img/merge.png new file mode 100644 index 0000000..4524954 Binary files /dev/null and b/tutorials/git/img/merge.png differ diff --git a/tutorials/git/img/rebase-diagram.png b/tutorials/git/img/rebase-diagram.png new file mode 100644 index 0000000..317017b Binary files /dev/null and b/tutorials/git/img/rebase-diagram.png differ diff --git a/tutorials/git/img/review-line.png b/tutorials/git/img/review-line.png new file mode 100644 index 0000000..2096803 Binary files /dev/null and b/tutorials/git/img/review-line.png differ diff --git a/tutorials/git/img/submit-review.png b/tutorials/git/img/submit-review.png new file mode 100644 index 0000000..b34533c Binary files /dev/null and b/tutorials/git/img/submit-review.png differ diff --git a/tutorials/git/index.md b/tutorials/git/index.md new file mode 100644 index 0000000..3d17b99 --- /dev/null +++ b/tutorials/git/index.md @@ -0,0 +1,33 @@ +--- +permalink: /tutorials/git/ +layout: tutorial +--- +# Git Tutorial +A general explanation about git can be found below. +This tutorial explains the different stages of working with git in our team. +This graph shows the process. + +![](img/git-process.drawio.svg) + +# Git & GitHub +[Git](https://git-scm.com/) is the version control system (VCS) that we use for team code, and we host our git repositories on [GitHub](https://github.com). + +Some git terminology: +- **`repository`** (**`repo`**) - the project folder. +- **`commit`** - a group of changes that do something / a point in the history of the repo. +- **`branch`** - a commit history of the repo. +- **`clone`** - create a local copy of the repository. +- **`push`** - update the remote repository with your local changes. +- **`pull`** - update your local repository with the remote changes. +- **`pull request`** (**`PR`**) - a request to merge the changes in a branch to the main branch. + +[frc-docs](https://docs.wpilib.org/en/stable/docs/software/basic-programming/git-getting-started.html) +has a good explanation of Git basics and a tutorial for creating your first repository. + +[k88hudson/git-flight-rules](https://github.com/k88hudson/git-flight-rules/blob/master/README.md) is +also a good reference on how to do stuff in git. + +This tutorial is for creating Pull Requests based on our Git workflow. +Our git workflow: + +![](img/git-workflow.drawio.svg) \ No newline at end of file diff --git a/tutorials/git/pr.md b/tutorials/git/pr.md new file mode 100644 index 0000000..a3a79e4 --- /dev/null +++ b/tutorials/git/pr.md @@ -0,0 +1,68 @@ +--- +permalink: /tutorials/git/create-pr.html +layout: tutorial +--- +After [pushing](./push.html) your changes to GitHub, you can ask the repo admin to accept your changes. +This is done with a _Pull Request_ (often called a PR). +A Pull Request has a _base branch_ (the branch that you want to add changes to, the one you created +a branch from [here](./create-branch.md)), and a _compare branch_ (the branch with your changes, the one you created). + +> You can open a Pull Request inside IntelliJ with the same fields, details at [the bottom of the page](#creating-a-pull-request-in-intellij). + +You can always open a Pull Request from [GitHub.com](https://github.com) by going to the `Pull Requests` tab on the repository page. + +When pushing a branch from the terminal or from GitHub Desktop you can also open a PR right away: +
+ + +
+
+ +In the terminal, a similar message will be printed (the line starting with `$>` is the push command). +```ps +$> git push --set-upstream origin mybranch + +Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 +remote: +remote: Create a pull request for 'mybranch' on GitHub by visiting: +remote: https://github.com/ExcaliburFRC/FRC-Curriculum/pull/new/mybranch +remote: +To https://github.com/ExcaliburFRC/FRC-Curriculum.git + * [new branch] mybranch -> mybranch +Branch 'mybranch' set up to track remote branch 'mybranch' from 'origin'. +``` +As explained by the message, the first link will open [GitHub](https://github.com) with options to create a Pull Request. + +
+
+ +![](img/ghd-pr.png) + +Clicking on `Create Pull Request` will open [GitHub](https://github.com) with options to create a Pull Request. + +
+ +### Comparing Changes +Once you get to the `Compare Changes` page, make sure that `base` is set to `main` (or `master` in older repositories) and `compare` is set to your branch. + +![](img/create-pr.png) + +A preview of the changes should appear below - additions in green and deletions in red. +Then click on `Create Pull Request`, and enter a name and description for your PR. + +##### Naming Pull Requests +Pull Requests have the same naming guidelines as commits (you'll see why later in [Squash/Merge](./squash-merge.html)) - it should summarize the changes done in the PR. +- Some good examples: `Add Drive System`, `Change Shooter motor type`, `Update WPI Version`. +- Some bad examples: `fix error`, `door open`, `Auto.java`. + +##### Linking Issues +If the Pull Request fixes an Issue (most do), GitHub can automatically close the Issue once the PR is accepted. +Adding `Fixes #num` to the PR description (`num` is the Issue number, all Issues have one) will link that Issue to the Pull Request. + +### Creating a Pull Request in IntelliJ +> This can be done in IntelliJ versions 2020.3 and up. + +> You need to be signed in to IntelliJ with your GitHub account for this. + +Open `Git > GitHub > Create Pull Request` from the top menu, and fill the fields. + diff --git a/tutorials/git/push.md b/tutorials/git/push.md new file mode 100644 index 0000000..372e85c --- /dev/null +++ b/tutorials/git/push.md @@ -0,0 +1,49 @@ +--- +permalink: /tutorials/git/push.html +layout: tutorial +--- +Once you have commits, you can `push` them to the remote (`origin` - GitHub): + +
+ + + +
+ +
+ +To push all local commits to the remote: +```ps + git push +``` +If this is the first time the branch is pushed, it will likely fail: +```ps +fatal: The current branch mybranch has no upstream branch. + To push the current branch and set the remote as upstream, use + + git push --set-upstream origin mybranch +``` +This is because `mybranch` doesn't have a remote counterpart yet. +The error message gives all the information needed: to push and set the remote branch use +```ps +git push --set-upstream origin mybranch +``` + + +
+
+ +Click `Push to origin`. + +![](img/ghd-push.png) + +
+
+ +Click the green arrow at the top-right, then click `Push` in the dialog. + +![](img/ij-push.png) + +
+ +
\ No newline at end of file diff --git a/tutorials/git/rebase.md b/tutorials/git/rebase.md new file mode 100644 index 0000000..a4e0894 --- /dev/null +++ b/tutorials/git/rebase.md @@ -0,0 +1,82 @@ +--- +permalink: /tutorials/git/rebase.html +layout: tutorial +--- +The `rebase` operation moves the base commit of the branch. +It takes all each commit and applies its changes on the new base commit instead of on the old one. +Usually, rebasing will be done onto a branch and not an actual commit - the new base commit will be the currently-latest commit on that branch. + + + +### When are `rebase`s needed? +The main cause for needing to `rebase` is if the base branch (usually `origin/main`) of a Pull Request (PR) has commits added to it before the PR is merged. +When this happens, the PR branch (for example, `mybranch`) should be rebased on the commits that have been added to the base branch. +This is why you fetch the latest `origin/main` and then rebase onto it. + +##### Pull +Before rebasing, make sure that `origin/main` is up-to-date and that you are on the branch you want to rebase (here: `mybranch`). +That is covered [here](./create-branch.html#pulling-codeorigincode). +Then we will rebase `mybranch` onto `origin/main`. + +### Rebase +
+ + + +
+ +
+ +```ps +git rebase origin/main +``` + +
+
+ +Click on `Branch > Rebase current branch`, select the branch to rebase onto, and click `Start rebase`. + +
+
+ +Open `Git > Rebase` from the top menu, and select `origin/main` (the new base). + +
+ +--- + +##### Force-Push +After rebasing, we will need to _force-push_ - the commit history of our branch changed, so GitHub will reject a normal `push`. + +## **!!! Be careful with force-pushing !!!** +## **!!! It can delete your work forever !!!** + +
+ + + +
+ +
+ +```ps +git push --force-with-lease +``` + +
+
+ +GitHub Desktop does not support force-pushing. Use the terminal/command-line or IntelliJ. + +
+
+ +As with regular `push`ing, click on the green arrow on the top-left corner of the screen to open the push dialog. +Unlike with regular pushing, click on the triangle next to `Push` and click on `Force Push`. + +![](img/ij-forcepush.png) + +
+ +--- + diff --git a/tutorials/git/reviews.md b/tutorials/git/reviews.md new file mode 100644 index 0000000..050ffff --- /dev/null +++ b/tutorials/git/reviews.md @@ -0,0 +1,38 @@ +--- +permalink: /tutorials/git/reviews.html +layout: tutorial +--- +After you open a Pull Request, others can review it. Similarly, you can review Pull Requests made by other people. + +Open the PR's page, and switch to the `Files Changed` tab. This page will show all changes made by +the Pull Request, additions in green and deletions in red. + +### Adding a Review +Hover on a line in the change view, and click on the blue `+` icon that appears. You can select multiple lines by dragging the blue plus. +A review panel with open, with a textbox where you can write specific feedback on that change. + +##### Suggesting Changes +You can also suggest a change by clicking on the file icon with a plus and a minus. + +![](img/review-line.png) + +This will add a MarkDown codebox with the selected line of code. Edits made to the line of code will +be added as suggestions. + +Unless it is a single comment, click `Start a review`. + +##### Submit a Review +After adding all your review comments, click on `Review Changes` at the top of the page. You can write a general message for the review in the text box. + +![](img/submit-review.png) + +Then you have three options: +- `Comment`: general feedback (this is the least used option). +- `Approve`: approve the changes, allows the PR to be merged into the repository. +- `Request Changes`: request changes/fixes, prevents the PR from being merged. + +### Addressing reviews +Line-specific reviews will be shown in the `Files` tab, and you can reply directly (each review has a chat box). +You can commit suggestions directly from GitHub by clicking `Commit Suggestion`, or add multiple suggestions in the same commit from the `Files` tab by clicking `Add to batch` on each suggestion and then `Commit Batch`. +Don't forget to `pull` those commits to your computer before making more changes. +After addressing all review comments, you can re-request a review from someone by clicking the arrow circle next to their name. diff --git a/tutorials/git/squash.md b/tutorials/git/squash.md new file mode 100644 index 0000000..aa3e62a --- /dev/null +++ b/tutorials/git/squash.md @@ -0,0 +1,39 @@ +--- +permalink: /tutorials/git/squash-merge.html +layout: tutorial +--- +Once a Pull Request has been [approved](./reviews.html#submit-a-review), it can be merged into the repository. +A Pull Request with requested changes cannot be merged. + +### Merge Methods +There are three ways to merge Pull Request changes to the main repository/branch. +The three types are `merge`, `squash`, and `rebase`: +> Repository/Organization admins can disable any of these options, but at least one must be enabled. + +##### Merge +- adds all commits on branch by a [_merge commit_](https://www.atlassian.com/git/tutorials/using-branches/git-merge) +- keeps individual commits (keeps history of the feature branch) +- considered bad style, as they cause non-linear git histories (the merge commit +has two parent commits), making them harder to debug or revert (undo) + +##### Squash +- squashes all PR changes into a single commit (which is then added to the main repo/branch) +- keeps git history clean and ordered, each PR is a single commit +- you can't revert only part of the Pull Request +- this is the suggested merging method for most Pull Requests + +##### Rebase +- [_rebases_](./rebase.html) all commits and adds them to the main branch/repo +- keeps individual commits +- linear git history (each commit has only one parent commit) + +### Merging a Pull Request +If you have write access to the repository, you can merge Pull Requests (in any of the three methods). +If not (and even if you do), someone else with write access (in an FRC context, likely a mentor or lead programmer). + + + +A `merge` box should appear above the textbox for commenting at the bottom of the PR page. +Click on the small triangle to open the options, and select the merge method you choose. + +### Well done! You've merged your first Pull Request! diff --git a/tutorials/tutorials.html b/tutorials/tutorials.html new file mode 100644 index 0000000..1cacd33 --- /dev/null +++ b/tutorials/tutorials.html @@ -0,0 +1,11 @@ +--- +permalink: /tutorials/ +layout: default +--- +

Team Tutorials

+
+ +
+

Git

+ +