Kernel Development Learning Pipeline

Procedures and policies

For the purposes of clarity in this document, we use the term "student" to denote the entity formed by each pair of collaborators.

How to get help in this course

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

Contributing

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.

Coursework Policies

All homework submissions must be submitted in the form of an email patchset [0] generated by git format-patch [1] from commits [2] made in your local copy of this repository with a cover letter [3] describing your work, and sent by git send-email [4] to our mailing list.

As part of the peer-review process [5] for coding assignments in this class each assignment will require you to submit each patchset at least twice.

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 [6].

Any code submission violating these guidelines or that fails to compile with zero warnings and zero 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:

Step 1: Initial submission

• The student makes their submission to the mailing list using git-send-email

• This submission is due on Monday the week the assignment is listed

• If the initial submission is late, the student will get a zero on the entire assignment

Step 2: Peer review

• 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>

• If the student finds issues with a submission, then the student will reply to the cover letter of the patchset with detailed feedback about their concerns and conclude the email with a single line containing the following:

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%

Step 3: Final submission

• 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

[0] Patchset Guidelines

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.

[1] Patch Guidelines

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.

[2] Commit Guidelines

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

[3] Cover Letter Guidelines

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 your username, separated by a dash ('-'). For example, "Exercise 18 - charles-joel".

• You must replace the blurb filler text with your write-up

• Failure to remove these filler lines including the asterisks will result in lost points

Your cover letter write-up should include a short discussion that includes the following:

• What you think your degree of success with this assignment is (from 0% to 100%)

• An estimate of how much time you spent working on this assignment

• A brief discussion of your approach to 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.

[4] Mailing List Guidelines

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.

[5] Peer Review Guidelines

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

• 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

[6] Resubmission Guidelines

You can resubmit as many times as they 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.