On behalf of the teaching staff, welcome to OS1! Although this course can be tough at times, by the end of the semester you will have an extremely in-depth knowledge of the principles underlying every single device around you, from your everyday laptop and smartphone to your smart thermostat and Google’s server farms. This course will teach you some of the most valuable skills and knowledge that you will certainly use for the rest of your software engineering career.
As TAs of the course, we see lots of mistakes all the time, and they are a perfectly normal part of the learning process.
However, not all mistakes are the valuable, learning-opportunity type; unlike general implementation mistakes, some tend to have a much larger impact on your score than they should or deserve. That said, this is not a list of those; talking about them excessively will just reinforces your memory of the wrong things. Instead we talk about some of what you should do.
You can use this as a global checklist or list of best practices.
Us TAs are here to help! Last year, we were exactly where you are now, and we chose to be TAs this year because we find the material fascinating, the homeworks engaging, and we want you to enjoy the course to its full potential. If you are facing an issue, we have certainly encountered it before, or helped another student who has. And more generally, we found that just working on the homework assignments during office hours allows you to ask us small questions along the way, and is very effective at preventing you from getting stuck.
You will also overhear other student’s questions and TA discussions, which will almost certainly contain useful information. We have also found that, even outside of office hours, the OH room serves as a great working space for OS assignments, as you will often find other OS students working there.
Overall, please don’t be shy! We are students just like you, and we are here to help :)
If someone else shows up in the same office hours you do, then they
…probably.
Homework 2 onwards will be done in teams of 3, so you should start scouting early for potential teammates. A good team can easily make or break your submission, so be sure to be on the lookout. And if you don’t feel the chemistry, feel free to switch teams between homeworks.
Direct emails might not be promptly responded to if, for instance, you ask about something that is not normally taken care of by the specific TA you contacted. TAs don’t all have the same context to everything within the course. Make sure to email the mailing list for the fastest response by the TA best suited to handle your request.
…or you might lose video-recording access. This is not fun if you are under the required attendance ratio but there are no more lectures to make up from at the end of the semester: you will not regain access before the exam.
Even if you are gonna miss some classes, having a buffer is always good.
Baseline: if you are unsure about anything at all, cite it.
To be very clear: if you do get the AI to do your actual coding work, and you properly cite it in your references file:
As such, you should always cite such usages, and you should also always try work out the issues by yourself.
If your code has AI-autocompletion, you should include in your reference files the context where it autocompleted any code that you are not already going to type exactly anyway. Mention the context and your intent with the code logic, and then the code generated by AI.
When you share your AI chat history, we also much prefer that you submit the full log as is, instead of pasting the URLs to the chats, which can go all sorts of wrong and takes more time to verify.
Unfortunately, a few students get caught every semester for un-cited LLM usage. This is never fun to deal with and typically gets escalated to CSSI, which never ends well. Even worse, when this happens, the whole team typically gets a 0 for that assignment, even if they didn’t know about the plagiarism. You should be encouraging your teammates to properly cite everything.
If your question does not directly reveal your specific implementation, but you also like some anonymity, please prefer to post your question publicly but ask it anonymously (Edstem allows this), so that more people can potentially benefit from it. More often than not, the “particular weird thing” that you are facing is not unique and others are suffering from it too.
We have found that students often leave comments on each others Edstem posts if they have encountered a similar issue before, or to ask useful follow-up questions. Remember, there’s no such thing as a stupid question!
Before the deadline, someone who has been clearly designated within the team should take the time to verify that your kernel compiles. No one should push after this commit without this person signing off.
Nothing else matters as much as this. If your kernel doesn’t compile, you will get a 0.
Not much to say about this. We assure you the two weeks allocated are never an excess.
For the case of the team assignments, you will be much better off if you have good teammates to work with. Trying to complete them alone in two weeks is very hard. You should have one or two teammates who are (hopefully) just as eager to get it done as you are.
Typically, the first part of the assignment must be done prior to any other parts. And while we’ve seen some groups successfully pair-program their way through the assignments, we’ve done our best to design them such that you can parallelize right after the first part. Give out tasks to each other and keep in frequent contact.
However, by the end of the assignment you shouldn’t have any “blind spots” which you don’t know how they work because someone else worked on it. Much of the material in the homeworks is directly relevant to the exams, so you want to have a good grasp of how every aspect of your implementation works.
Also, in general we’ve found that working together in-person is much more productive, especially at the start and the end. A big part of the assignments is understanding the technical concepts in the Linux Kernel, and subtle differences in assumptions about how the kernel works and your teammates’ implementation can lead to huge bugs down the line. We encourage you to pick one or more office hour slots you can all attend, and use them as your regular OS homework meeting.
Some thing we frequently mention in class is to make tiny, incremental changes. This makes each change that much more easy to isolate and, if needs be, to revert. Larger commits are harder to review, harder to merge, harder to understand when you come back to your short commit message, and if you have too few commits in a team project, we will also be hard-pressed to recognize your coding contribution.
This is not saying not to write lots of code at once – rather, just commit more often. For instance, you can always make a lot of local commits, many of which not necessarily working or even compiling, as long as you make sure that when you do push to main, you have something that is sound.
Aditionally, the 5 commit rule is real and is actively enforced, and “my code was pushed under my teammate’s account” is not a valid excuse. Make sure to get those commits in!
Every year, we get a handful of emails saying something along the lines of “I committed the code but forgot to push! Could you please let me push these commits after the deadline?” And unfortunately we aren’t able to do so, because it is easy to back-date git commits, and we can’t prove whether you actually wrote the code before the deadline. So please don’t be that person, and always push right after committing.
This also helps in the very unfortunate scenario where you committed, didn’t push, and corrupted your kernel to the point where you need to restore from a VMware snapshot that doesn’t have that commit, therefore losing it forever.
Since you are modifying and tearing apart the guts of the kernel, you will certainly encounter quite a few scenarios where for whatever reason, your kernel is simply unable to boot no matter what you try. You will panic the kernel. You will brick your environment. Reverting to a snapshot takes seconds; rebuilding your environment takes hours.
main FunctionalMost homeworks are a group effort, and as a general recommendation, try to make
it so that if you push something to main, that commit is properly tested or
you make any issue within known to your teammates – it should at the very least
compile.
Granted, there are lots of different possible team dynamics, but this is something we believe to be sound. We are not saying you always need proper PRs and code reviews, since sometimes they do slow down development, but keeping commit hygiene is good.
Large companies enter code-freeze before holidays to avoid the risk of pushing something bad and then causing poor oncalls to have to get away from festivities and get on conference calls. Once you are very near the deadline of a homework submission, we recommend you hold off any significant code change efforts. Many homeworks require thorough testing to get right, and regression is always a risk. If you have a sudden realization in the final hour before the deadline that you made a mistake, slow down, stop, hold the thought.
Almost every homework we have students who make bad last minute pushes that don’t compile, that mess something up, or otherwise cause more harm than good.
The biggest difference between the good grades and the best grades is the amount of testing programs they wrote. Typically the assignment will ask you to write a simple test program to get you started, but you should always write many, many more.
We will not release the homework rubrics until after the deadline, however the items are always fairly predictable by looking at the specification. Our tests are NOT “does your kernel still work if we use this random value you have never heard of?” In fact, with some creativity you definitely can (and should) try and guess what we might test for, and write those tests yourself ahead of time!
If you notice yourself doing the same couple of things to verify that your code is working after each recompilation, consider making that a test suite – some shell script, potentially even ChatGPT’ed, whatever, just cite it properly.
Now obviously if we ask you to write some tester program as a deliverable, then you should do it. But you are not limited to it, and whenever your test procedure involves not just the program itself, but a full process, having some sort of script will greatly improve the testing process. Not only does it save your manual typing time, it also serves to make the process consistent, preventing cases where you get the wrong impression because you neglected a step, or are testing against a previous kernel version.
You don’t have to create a full CI/CD pipeline, but it would be really cool.
And overkill. But cool.
Use at your own risk. These tooling suggestions will not be supported officially by the teaching staff. Think of them as extra-curricular tech.
clang-formatThe linux repo in most homeworks comes with a .clang-format file hidden in
the root directory. This file will allow the very relevantly named
clang-format tool (sudo apt install clang-format) to format your code to the
spec that is expected in the Linux repo, and help avoid many of the issues that
checkpatch looks for.
HOWEVER, it should be noted that if you just use it directly on existing linux source files, it might format irrelevant stuff to your own, and possibly introduce some degree of messiness. It should be fine for brand new files that you are adding though.
For the even lazier: add it as a pre-commit.
repos:
- repo: https://github.com/pre-commit/mirrors-clang-format
rev: v14.0.6
hooks:
- id: clang-format