The #questions
channel on Matrix is the best place to turn.
If you're having an issue with something, chances are that
you're not alone and sharing your question publicly helps
everyone. Feel free to answer questions posted by other students.
Before posting a question, we encourage you to:
Carefully proofread your command or code for typos
Thoroughly re-read the assignment instructions
Read any relevant man pages or documentation
Read and research any error message or output
If you were stuck but manage to figure out something yourself, feel free to share on Matrix.
If you are not able to figure out the solution yourself, we encourage you to include the following information in your post. The more complete this information is when you ask for help, the easier it will be to help you.
What you were doing when the error occurred and what steps are needed for someone to reproduce it
Any input or output remotely relevant to the error, include as applicable all of the following:
The command you ran and the output
Your complete source code Makefile
Any error messages
Any dmesg or system log messages that seem relevant to the error
Any references or resources you consulted during your troubleshooting, e.g. manpages, websites, repositories, documentation
What you tried to do to fix your problem
Your best educated guess(es) as to what's wrong
If you notice any of the following:
The directions are incorrect or could be made clearer
There is a bug in our course infrastructure
You have an idea for a feature that could improve the course quality
Feel free to let us know. We appreciate the feedback. In addition, we invite any interested students to work with us and improve the course. We can guide you through the process of making the appropriate changes and successful upstream contributions will result in extra credit.
Keep in mind that this policy covers anything in the course, including code, scripts, process, curriculum, formatting, style, security, design, testing, automation, devops, site reliability, IT, or any other aspect that you can imagine and convince us is a part of the course.
All homework submissions must be submitted in the form of an email patchset
generated by git format-patch
from commits made in your local copy of
this repository
with a cover letter describing your work, and sent by git send-email
to
our mailing list.
As part of the peer-review process for coding assignments in this class, each assignment will require you to submit each patchset at least twice.
Note that version numbers are maintained between RFC and non-RFC patchsets--in the best case, your RFC would be v1 and your final submission would be v2. Your cover letter shoud include a summary of changes since the previous version.
Try to start your assignments early. If you run into issues and get stuck it gives you time to ask questions and get help before the due date so you can submit something on time and get credit for the assignment. If you finish early, you can resubmit.
Any code submission that:
violates these guidelines,
compiles with warnings, or
fails to compile and produces errors
will receive a zero.
With the exception of presentations, all work in this course takes place on our mailing list. Students submit assignments and review peer submissions on this list.
Each assignment involves the following three stages:
The student makes their submission to the mailing list using git-send-email
This submission is due on Tuesday the week the assignment is listed
If the initial submission is late, the student will get a zero on the entire assignment
Each student is assigned two other students' work to review
If the student approves of a submission, then the student will reply to the cover letter of the patchset with a single line containing the following:
Acked-by: Firstname Lastname <USERNAME@COURSE_DOMAIN>
Peer-reviewed-by: Firstname Lastname <USERNAME@COURSE_DOMAIN>
In parallel, other students have been assigned the student's submission and the student should receive feedback from two other students
These reviews are due one day past the initial submission, a late or no submission results in a zero for the review section of the assignment
Reviews are graded based on how many issues a student missed. The student receives 20% off for each unique issue not spotted with max penalty of 100%
The student, if canny, will act on the feedback from the received reviews.
Regardless of whether the student made changes to their initial submission, they must make a final submission
A late or missing final submission will result in a zero grade for the assignment
This is due two days after the initial submission, and due one day after the deadline for sending reviews
The total assignment grade is composed of 80% for the final submission, and 10% for each peer review
While the initial submission is not explicitly graded, failure to submit anything or submissions devoid of content will result in a zero
The specific assignment document will specify which files to edit, and how many commits you should be making which will inform the overall structure of your patchset, but every patchset in this class must follow these general guidelines:
Each commit gets its own patch with a title and body
The patch series is introduced with one additional patch, the cover letter
Fortunately, git format-patch can generate the appropriate files for you:
$ git format-patch -3 --cover-letter --rfc -v1
This command generates git email patches from a base repository. The arguments mean the following:
-3
specifies that the three most recent commits should be included, and therefore 3 email patch files will be generated. Change the number as needed.
--cover-letter
specifies that a cover letter email template file is generated as "patch 0" of the patchset. You should always use this
Use -v<n>
, in this case -v1
to specify the version number of this patchset.
Increase this number each time you resubmit an assignment. Use --rfc
to denote
on each patch that the changes are a draft posted for review. Use this when generating
initial submissison patchsets, but not when generating the final submission patchsets.
All of the patches must follow the patch guidelines[^1]. Patches generated from a commit should follow the commit guidelines[^2] and the cover letter must follow the cover letter guidelines[^3].
You will receive an automatic zero on the assignment if any of the patches
in your patchset are corrupt. This shouldn't be possible if you generate
your patches with git format-patch
, but if you edit the files manually
they might get corrupted. You have been warned! The correct way to edit
the patches is to edit the underlying commits and then regenerate the patches.
To edit previous commits, see man git-rebase
and the --amend
option from man git-commit
.
Assignments must be submitted in the format of git email text patches. Binary patches are forbidden because all work in this class is in plaintext.
Every patch in the patch series (including the cover letter) must end with a "Signed-off-by" line, called the DCO (Developer Certificate of Origin). The line must exactly match this format:
Signed-off-by: Firstname Lastname <USERNAME@COURSE_DOMAIN>
The DCO line must be the final line of the email body right before the start of the patch diff.
Fortunately, you can make git add this line automatically for you when you author a commit:
$ git commit -s
This will add the DCO line in the commit message automatically from information
in the current user's git config, or if present the repository's .git/config
file.
You will need to remember to add your DCO to the cover letter manually.
You must use the checkpatch.pl
script in the scripts/
directory of Linus' kernel tree
to make sure your patch is as close to upstream Linux kernel patch standards as possible.
To do this quickly outside of the kernel tree, download the script and spellcheck file using the following two commands or some equivalent:
$ wget https://github.com/torvalds/linux/raw/master/scripts/checkpatch.pl
$ wget https://github.com/torvalds/linux/raw/master/scripts/spelling.txt
Then, invoke the script with ./checkpatch.pl --no-tree --strict --show-types
--no-tree
indicates that we aren't checking a patch intended for the actual kernel tree
--strict
will enable the some tests that are not enabled by default
--show-types
will clearly indicate the types of errors
You can input patches to the script by either standard in or via specifying the paths to the patch files as arguments following the flags.
Within the submissions repository for this course each student will create a directory matching
their username. If any starter files are needed, the assignment descriptions will specify the
necessary details. You will do the assignment and turn your work into commits using git commit -s
.
When you author a commit the first line(s) you type into your editor will become the title,
and by hitting enter twice and leaving a blank line the subsequent text will become the full
commit message. The git format-patch
utility will automatically put the title and message
of a commit into the respective title and body of the corresponding generated email patch file.
Your commits should have a title that is a short summary of the changes in this commit and you should include any further details in the commit message.
You should make sure that the changes you are including in your commits are tidy. This means that code should follow the kernel code style guidelines, (tabs for indentation, tab width of 8, no lines exceeding 100 columns, etc).
You must also avoid whitespace errors. These include whitespace at the end of a line, lines with only whitespace on them, extra blank lines at the end of a file, forgetting the newline on the last line of the file, etc. A good editor will highlight and/or automatically fix these for you, but git will also detect these when formatting and applying patches.
You can check for the other whitespace errors by using git am <email patch file>
to attempt
to apply your patch to the local tree. If git am
prints a warning like this when you apply the patch:
warning: 2 lines add whitespace errors.
You should adjust the indicated lines and fix your patch.
Your patches also must apply cleanly to the HEAD
commit on the master
branch of the
upstream repository. You can verify this by checking out that branch and trying to apply
your patches. We should NOT need to apply your previous versions of the patchset in order
for the latest version of your patchset to apply.
Sample workflow to check that your patchset applies cleanly:
Generate your patches and put them in a known location and take note of the filenames
Make sure your local git worktree is up to date (you should do this each time you begin work within any git repository)
Use git remote update
to update all of your local copies of remote trees
Create and checkout a local branch based on the upstream origin/master
branch by using:
git checkout -b <branch name> origin/master
(branch name can be anything convenient)
Apply your patchset to this branch using git am <patch1> <patch2> ... <patchN>
If there are no errors that appear, congratulations, your patchset applies cleanly!
If there are whitespace errors or corrupt patches, revise as needed by amending or rebasing your commits
When you open the cover letter file generated by git format-patch
in your editor,
you will see a summary of all the changes made in the subsequent patches at the bottom
and two filler lines indicating where you can add the title (*** SUBJECT HERE ***)
and message (*** BLURB HERE ***)
to the email.
You must:
Replace the subject filler text with the assignment name and your username,
separated by a dash '-'
(for example, "Exercise 18 - charles-joel")
Replace the blurb filler text with your write-up
Failure to remove these filler lines including the asterisks will result in lost points
The first line of your cover letter write up should state what you think your degree of success for the assignment was (from 0% to 100%), formatted as follows:
Completed: 100%
Following this, your cover letter write-up should include a short discussion that includes the following:
An estimate of how much time you spent working on this assignment
How you approached the assignment
A detailed description of any problems that you were not able to resolve before submitting
Failure to cover each of the above will result in a zero grade on your assignment. If your self-assessment of success is not 100%, please document all known issues. Be honest with your self-assessment. If obvious errors are discovered despite high self-assessment, then we reserve the right to give you a zero. We also reserve the right to dock points for grammatical mistakes.
Your patches should be sent to the address for the specific assignment. Each assignment will list the appropriate email to use like so:
$ git send-email --to=whatever_assignment@COURSE_DOMAIN *.patch
This command attempts to send any file in the current directory ending in
.patch
to the mailing list. *.patch
is an example of glob
expansion
in the shell. See man 7 glob
for more information.
For each student to whom you are assigned, you will do the following:
Make a new branch off of master/main and switch over to that branch to apply the patches.
Apply the student's latest patchset submission to your local tree
Make sure each patch applies cleanly IN ORDER (a.k.a no corrupt patches, whitespace errors, etc.)
Make sure the code compiles without warnings or errors
Sanity check that any programs run without immediately crashing
Make sure that the output looks reasonable
Scan through the rubric, as each assignment's peer review requirements will be different
If there are any problems with the submission, report them in your review
If you determine that there are no issues with the submission, inform the recipient.
If it turns out that there were issues with the submission that you missed, points will be deducted from your overall assignment grade
You can resubmit as many times as you please before a deadline. If you resubmit, you must regenerate and resend all the patch files and cover letter as a new version of the entire patch series, incrementing the version number in the subject line appropriately.
You must also document what changed since the last submission in your write-up, include a section with a title like "changes since vN" where N is the number of your last submission and you explain what changed.
You can resubmit a peer review by making a new reply to the original cover letter with a new version of your complete review.
For any patchset or peer review, we will only grade the most recent submission.
msg = (silence)
whoami = None
singularity v0.6-4-gbe148cb https://github.com/underground-software/singularity