![[KDLP] logo](/assets/kdlp_logo.png){kind=logo}
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 for coding assignments in this class (described here) each assignment will require you to submit each patchset at least twice [5].
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, and if you finish early you can submit and potentially get feedback from us or other students that you can incorporate into a resubmission before the deadline in accordance with the resubmission policy [6].
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 automatically:
$ git format-patch -3 –cover-letter
$ # generates patches from the three most recent commits (change -3 to whatever you need for the amount of commits you have) and a cover letter template.
All of the patches must follow the patch guidelines [1]. Those generated from a commit should follow the commit guidelines [2] and the cover letter must follow the cover letter guidelines [3].
You will recieve 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 (see man git-rebase and the --amend option from man git-commit) and then regenerate the patches.
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
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
$ # include a DCO Signed-off-by line in the commit message automatically
You will need to remember to add your DCO to the cover letter manually.
You should 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.
Within the repository for this class there is a directory for each assignment (e.g. for A0, look in the A0 directory, for Mid 1, look in Mid1, etc.) and within that directory there should be everything you need to get started after you have read the specific document for the assignment you are working on.
You will make the necessary changes or additions and turn them into commits using git commit.
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 title and body respectively of the corresponding patch email it generates.
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 80 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.
When you format a patch, if you forgot the newline at the end of the file git will put this line at the end of the diff \ No newline at end of file. If you see this, you should adjust the file contents and fix your patch. You can check for the other whitespace errors by running git am to try and apply your patch. 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 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 patch in order for the latest version of your patchset to apply.
Sample workflow to check that your patchset applies cleanly:
git remote update to update all of your local copies of remote trees.origin/master branch by using:
git checkout -b <branch name> origin/master (branch name can be anything convenient)git am <patch1> <patch2> ... <patchN>When you open the cover letter file generated by git format-patch in your editor, it will contain 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 With your name and the assignment title. For example Charles Mirabile - Assignment 3
You must replace the blurb filler with your writeup
Failure to remove these filler lines including the asterisks will result in lost points
Your cover letter writeup should include a short write-up that specifies the following:
What you think your degree of success with this assignment is (from 0% to 100%)
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 specifically provide this information will result in a 0 grade on your assignment. Further, If you do not disclose problems in your write-up and problems are discovered when your work is reviewed, you will receive a grade of 0. Note: These writeup guidelines are adapted from those of Prof. Bill Moloney
Your patches should be sent to the mailing list for your cohort you were given when you joined the class using the git send-email tool. You will need to configure git send email to be able to send patches from your email account, see this guide for instructions if you are using a gmail account.
Once the configuration is correct, you will invoke git send-email to submit them:
$ git send-email –to=your-cohort@googlegroups.com *.patch
$ # send the emails to the mailing list. The list of patch files are passed as arguments
$ # The *.patch wildcard expands to all of the files whose names end with .patch in the current directory
The patch format should be as follows:
--rfc option when you format your patchset).--rfc option).Late submissions will result in an automatic grade of zero. The only exception is the one-time per semester oopsie (refer here).
If you notice a mistake in your submission (or have it pointed out to you by one of the instructors or another student) before the due date, you are welcome to resubmit as many times as you’d like until said deadline. If you choose to resubmit, you must regenerate the patches from your (potentially altered) commit(s), and send the full patch series as your resubmission (i.e. a cover letter and one email for each commit even if some of the emails are identical to what you sent before).
Further, you must make clear that it is a resubmission by adding a version number after PATCH in the square brackets (i.e. Subject: [PATCH x/n] My title here would become Subject: [PATCH v2 x/n] My title here) incrementing the number as needed for however many resubmissions you make (you can use the -v option with an argument, denoting the version number, when reformatting your patchset).
You must also document what changed since the last submission in your writeup, include a section with a title like “changes since vN” where N is the number of your last submission and you explain what changed.