Skip to content

Commit 8728b05

Browse files
KyleQ1KyleQ1
authored
Add more learning materials for new students (#18)
Made the docs more apparent so students are more likely to read it. Added a way of learning git so students aren't thrown in the deep end. Updated the github page so it's easier for new students to use.
1 parent d40bc64 commit 8728b05

File tree

3 files changed

+91
-103
lines changed

3 files changed

+91
-103
lines changed

‎ci/github/index.html

Lines changed: 56 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -37,39 +37,65 @@
3737
<div class="body">
3838
<h1>GitHub</h1><strong>Prerequisites:</strong> <a href=
3939
"../intro-to-git/">Intro to Git</a>
40-
<h2 id="Resources">Resources</h2>
40+
<h2 id="Setup">Setup</h2>
41+
<p>Create an account on <a href="https://github.com/">GitHub</a>.</p>
42+
<h3 id="Create_SSH_key_pair">Create SSH key pair</h3>
43+
<pre>ssh-keygen -t rsa -b 4096 -C "[email protected]"</pre>
44+
<p>See <a href=
45+
"https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent">
46+
this</a> for more.</p>
47+
<h3 id="Add_public_key_to_GitHub">Add public key to GitHub</h3>
48+
<pre>cat ~/.ssh/id_rsa.pub</pre>
49+
<p>Copy the entire block, then follow the instructions <a href=
50+
"https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account">
51+
here</a> to add it to your account.</p>
52+
<h2 id="Usage">Usage</h2>
53+
<p>To push an updated commit, it's best to use this command to not
54+
overwrite a teammates commit. If you cannot push by running this command
55+
then update your local repo by pulling and rebasing, then run this command
56+
again.</p>
57+
<pre>git push --force-with-lease</pre>
58+
<h3 id="New_patchset">New patchset</h3>
59+
<p>Make sure new patchsets are created with <code>git commit</code>. Using
60+
<code>git commit --amend</code> will change a commit already merged
61+
upstream and lead to conflicts. Commit messages should have a format like
62+
this:</p>
63+
<pre>Implement a thing
64+
65+
Optional extended description that should be complete sentences.
66+
67+
Fixes #42.</pre>
68+
<p>where <code>42</code> would be the issue number being closed by this PR.
69+
The last line ensures the issue is automatically closed when the PR is
70+
merged. Make sure each issue resolution is a separate branch and PR.</p>
71+
<h3 id="Revisions_to_patchset">Revisions to patchset</h3>
72+
<p>Any changes should be incorporated into the commit previously pushed by
73+
either amending or rebasing (not pushing a new commit on top of the old
74+
one). Gerrit tracks the revisions using the "Change-Id" line at the bottom
75+
of the commit message. <i>Make sure this line does not change and remains
76+
the last line</i> during commit message modifications. Otherwise, a new
77+
patchset will be created instead.</p>
78+
<p>Verify this was done correctly by inspecting the output of <code>git log
79+
main..HEAD</code>. There should be only one commit listed and its Change-Id
80+
should match the old one.</p>
81+
<h4 id="Uncommitted_changes">Uncommitted changes</h4>
82+
<pre>git commit --amend</pre>
83+
<h4 id="Squashing_committed_changes">Squashing committed changes</h4>
84+
<p>If a new commit or commits were made while working, they should be
85+
squashed into the first before submitting it all as a new revision. To do
86+
so, run</p>
87+
<pre>git rebase -i &lt;commit hash before your commits&gt;</pre>
88+
<p>The first commit in the resulting generated file should be set to "r"
89+
for "reword" if the commit message needs to be altered to include parts of
90+
the other two commits. The other commits should be set to "f" for "fixup"
91+
so their contents are squashed into the first commit. <code>git
92+
rebase</code> descriptions for other options are in the file comment.</p>
93+
<h2 id="Git_.28advanced_usage.29_lecture_notes">Git (advanced usage)
94+
lecture notes</h2>
4195
<ul>
42-
<li>
43-
<a href="https://github.com/frc3512/">GitHub</a> - mirrors of the code
44-
we've written for the robotics team reside here.
45-
</li>
46-
<li>Git's <a href="https://git-scm.com/doc/">online documentation</a>.
47-
</li>
48-
<li>Git (advanced usage) lecture <a href="lecture/">slides</a>.
49-
</li>
50-
<li>
51-
<a href=
52-
"https://tom.preston-werner.com/2009/05/19/the-git-parable.html">The
53-
Git Parable</a> - an alternate explanation of Git terminology.
54-
</li>
55-
<li>
56-
<a href="https://chris.beams.io/posts/git-commit/">How and why to write
57-
a good commit message</a>
58-
</li>
59-
<li>
60-
<a href=
61-
"https://github.com/k88hudson/git-flight-rules/blob/master/README.md">Flight
62-
rules for Git</a>: solutions to common problems.
63-
</li>
64-
<li>
65-
<a href=
66-
"https://github.com/pluralsight/git-internals-pdf/releases/tag/v2.0">PDF
67-
on Git internals</a> for those curious about how Git stores files and
68-
revisions.
96+
<li>Git (advanced usage) lecture <a href="lecture/">slides</a>
6997
</li>
7098
</ul>
71-
<h2 id="Git_.28advanced_usage.29_lecture_notes">Git (advanced usage)
72-
lecture notes</h2>
7399
<h3 id="Versioning">Versioning</h3>
74100
<ul>
75101
<li>Easily get commit later? (tag)</li>
@@ -139,59 +165,6 @@ <h3 id="Nuclear_option_for_binary_files">Nuclear option for binary
139165
<li><code>git filter-branch --tree-filter 'rm -f largeFile.out'
140166
HEAD</code></li>
141167
</ul>
142-
<h2 id="Setup">Setup</h2>
143-
<p>Create an account on <a href="https://github.com/">GitHub</a>.</p>
144-
<h3 id="Create_SSH_key_pair">Create SSH key pair</h3>
145-
<pre>ssh-keygen -t rsa -b 4096 -C "[email protected]"</pre>
146-
<p>See <a href=
147-
"https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent">
148-
this</a> for more.</p>
149-
<h3 id="Add_public_key_to_GitHub">Add public key to GitHub</h3>
150-
<pre>cat ~/.ssh/id_rsa.pub</pre>
151-
<p>Copy the entire block, then follow the instructions <a href=
152-
"https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account">
153-
here</a> to add it to your account.</p>
154-
<h2 id="Usage">Usage</h2>
155-
<p>In Gerrit, features are submitted in branches with one commit per
156-
branch. Give each branch a name reflecting its content for easier
157-
management. Submit new patchsets and revisions of existing patchsets via
158-
the following command.</p>
159-
<pre>git push --force-with-lease</pre>
160-
<h3 id="New_patchset">New patchset</h3>
161-
<p>Make sure new patchsets are created with <code>git commit</code>. Using
162-
<code>git commit --amend</code> will change a commit already merged
163-
upstream and lead to conflicts. Commit messages should have a format like
164-
this:</p>
165-
<pre>Implement a thing
166-
167-
Optional extended description that should be complete sentences.
168-
169-
Fixes #42.</pre>
170-
<p>where <code>42</code> would be the issue number being closed by this PR.
171-
The last line ensures the issue is automatically closed when the PR is
172-
merged. Make sure each issue resolution is a separate branch and PR.</p>
173-
<h3 id="Revisions_to_patchset">Revisions to patchset</h3>
174-
<p>Any changes should be incorporated into the commit previously pushed by
175-
either amending or rebasing (not pushing a new commit on top of the old
176-
one). Gerrit tracks the revisions using the "Change-Id" line at the bottom
177-
of the commit message. <i>Make sure this line does not change and remains
178-
the last line</i> during commit message modifications. Otherwise, a new
179-
patchset will be created instead.</p>
180-
<p>Verify this was done correctly by inspecting the output of <code>git log
181-
main..HEAD</code>. There should be only one commit listed and its Change-Id
182-
should match the old one.</p>
183-
<h4 id="Uncommitted_changes">Uncommitted changes</h4>
184-
<pre>git commit --amend</pre>
185-
<h4 id="Squashing_committed_changes">Squashing committed changes</h4>
186-
<p>If a new commit or commits were made while working, they should be
187-
squashed into the first before submitting it all as a new revision. To do
188-
so, run</p>
189-
<pre>git rebase -i &lt;commit hash before your commits&gt;</pre>
190-
<p>The first commit in the resulting generated file should be set to "r"
191-
for "reword" if the commit message needs to be altered to include parts of
192-
the other two commits. The other commits should be set to "f" for "fixup"
193-
so their contents are squashed into the first commit. <code>git
194-
rebase</code> descriptions for other options are in the file comment.</p>
195168
<h2 id="Useful_Git_features">Useful Git features</h2>
196169
<ul>
197170
<li>End-of-line conversion (crlf or eol)</li>

‎ci/intro-to-git/index.html

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
</header>
3737
<div class="body">
3838
<h1>Intro to Git</h1>
39-
<h2 id="Install_and_config">Install and config</h2>
39+
<h2 id="Setup">Setup</h2>
4040
<p>To install Git, run <code>pacman -S git</code> in an MSYS2 terminal. Set
4141
up the commit author information with the following commands.</p>
4242
<pre>
@@ -63,35 +63,47 @@ <h2 id="Install_and_config">Install and config</h2>
6363
<p>In general, Git tries to be helpful. If you don't know what to do after
6464
running a Git command or seeing something fail, read the text Git prints
6565
for possible hints or instructions.</p>
66-
<h2 id="Resources">Resources</h2>
67-
<ul>
66+
<h2 id="Learn_more_about_Git">Learn more about Git</h2>
67+
<ol>
6868
<li>
69-
<a href="https://github.com/frc3512/">GitHub</a> - mirrors of the code
70-
we've written for the robotics team reside here.
69+
<a href="https://learngitbranching.js.org/">Learn Git</a> - great
70+
resource to learn how to use Git
7171
</li>
72-
<li>Git's <a href="https://git-scm.com/doc/">online documentation</a>.
73-
</li>
74-
<li>Git lecture <a href="lecture/">slides</a>.
72+
<li>Git lecture <a href="lecture/">slides</a>
7573
</li>
7674
<li>
7775
<a href=
7876
"https://tom.preston-werner.com/2009/05/19/the-git-parable.html">The
79-
Git Parable</a> - an alternate explanation of Git terminology.
77+
Git Parable</a> - an alternate explanation of Git terminology
8078
</li>
8179
<li>
82-
<a href="https://chris.beams.io/posts/git-commit/">How and why to write
83-
a good commit message</a>
80+
<a href="https://www.leshenko.net/p/ugit/#">ugit: DIY Git in Python</a>
81+
- implement Git in Python to learn more about how Git works on the
82+
inside
8483
</li>
8584
<li>
8685
<a href=
87-
"https://github.com/k88hudson/git-flight-rules/blob/master/README.md">Flight
88-
rules for Git</a>: solutions to common problems.
86+
"https://github.com/pluralsight/git-internals-pdf/releases/tag/v2.0">PDF
87+
on Git internals</a> for those curious about how Git stores files and
88+
revisions
89+
</li>
90+
</ol>
91+
<h2 id="References_for_Git">References for Git</h2>
92+
<ul>
93+
<li>
94+
<a href="https://github.com/frc3512/">GitHub</a> - mirrors of the code
95+
we've written for the robotics team reside here.
96+
</li>
97+
<li>Git's <a href="https://git-scm.com/doc/">online documentation</a>
98+
</li>
99+
<li>
100+
<a href="https://chris.beams.io/posts/git-commit/">How and why to write
101+
a good commit message</a>
89102
</li>
90103
<li>
91104
<a href=
92-
"https://github.com/pluralsight/git-internals-pdf/releases/tag/v2.0">PDF
93-
on Git internals</a> for those curious about how Git stores files and
94-
revisions.
105+
"https://github.com/k88hudson/git-flight-rules/blob/master/README.md">Flight
106+
rules for Git</a> - solutions to common problems
95107
</li>
96108
</ul>
97109
<h2 id="Git_lecture_notes">Git lecture notes</h2>

‎ci/robot-software/index.html

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,16 @@ <h2 id="Disclaimer">Disclaimer</h2>
4949
tutorials/labs is encouraged to help other students understand pieces of
5050
software quicker in the future.</p>
5151
<h2 id="Installation">Installation</h2>
52-
<p>Eclipse should already be installed from following the <a href=
52+
<p>VSCode should already be installed from following the <a href=
5353
"../../bootstrap/">bootstrap page</a>. For robot software development,
5454
follow the instructions <a href=
5555
"https://docs.wpilib.org/en/stable/docs/getting-started/getting-started-frc-control-system/wpilib-setup.html">
56-
here</a> to install WPILib and roboRIO ARM toolchain. Other robot software
57-
resources can be found on <a href=
58-
"https://docs.wpilib.org/en/stable/">docs.wpilib.org</a>.</p>
56+
here</a> to install WPILib and roboRIO ARM toolchain. Other very important
57+
robot resources that you should go through can be found on <a href=
58+
"https://docs.wpilib.org/en/stable/">docs.wpilib.org</a>. These docs will
59+
help you learn more about what robots are made from, resources that you can
60+
use in your robot code, and example projects that might help you with
61+
something you're doing.</p>
5962
<h2 id="Design_patterns">Design patterns</h2>
6063
<p>Design patterns are used all over software development. Expert
6164
programmers know the idiomatic design patterns for their language to solve

0 commit comments

Comments
 (0)