|
Size: 4375
Comment:
|
Size: 8116
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Getting Started as an OPW applicant = | ## page was renamed from OPWfirstpatch Hooray! Thanks for your interest in working on the Linux kernel. The next step is to [:OutreachyApply:apply] to Outreachy, and use this tutorial to create your first patch to the Linux kernel. |
| Line 3: | Line 4: |
| Hooray! Thanks for your interest in working on the Linux kernel. | == Intro == If you run into any issues with this tutorial, please ask questions on the #kernel-outreachy IRC channel on irc.oftc.net, or on the [https://groups.google.com/forum/#!forum/outreachy-kernel outreachy-kernel mailing list]. Please make sure to set your real name in your IRC client, so that we can correlate names and emails with irc handles. |
| Line 5: | Line 7: |
| If you run into any issues with this tutorial, please ask questions on the [https://live.gnome.org/OutreachProgramForWomen#Introduction #opw IRC channel] | [[Anchor(kernel-setup-done)]] = Contribution Instructions = |
| Line 7: | Line 10: |
| = Intro = | All patches, to be considered '''must''' be sent to the [https://groups.google.com/forum/#!forum/outreachy-kernel outreachy-kernel mailing list] (outreachy-kernel@googlegroups.com). In this round, we also ask that you submit your patches to the maintainers of the various staging drivers. Information about this is below. If you have any questions about any aspect of the patch submission process, please ask on the mailing list. |
| Line 9: | Line 12: |
| This tutorial will cover how to get your first patch submitted. We would love it if accepted interns could test their kernel code on a computer running Linux, however, to get applicants started, this tutorial will describe how to set Linux up in a virtual machine. | [[Include(FirstKernelPatch)]] |
| Line 11: | Line 14: |
| You can run Linux from within Windows (or even run Linux on Linux!) from a virtual machine (VM). This tutorial will show you how to: * Install VMPlayer * Download our Linux VM image * Configure kernel drivers * Compile and install the kernel * Make a simple driver change * Test your changes * Create a patch * Submit a patch |
= Resending patches = |
| Line 21: | Line 16: |
| = Hardware Requirements = | If you find a mistake in your initial patch submission, and you need to correct it, make sure to version your new patch as described in the previous section. |
| Line 23: | Line 18: |
| You need a system with virtualization (VT-d), at least 4GB of RAM, and 40GB of free hard drive space in order to run Linux in a VM. == Alternatives == If your system doesn't meet those requirements, you will need to be running Linux, or dual boot your machine so you can run both Linux and Windows. We strongly suggest you use the [http://www.ubuntu.com/download/desktop/thank-you?distro=desktop&bits=64&release=lts Ubuntu 12.04 64-bit version]. If your machine doesn't have 64-bit support, you can use the [http://www.ubuntu.com/download/desktop/thank-you?release=lts&bits=32&distro=desktop&status=zeroc 32-bit version]. Once you have Ubuntu installed, please follow the "Option 2" directions [:OPWfirstpatchAlt:here]. = Install VMPlayer = Go to the [http://www.vmware.com/products/player/ VMPlayer website] and click the 'download' link. Download the VMPlayer that's appropriate for your operating system (e.g. Windows or Linux 64-bit), and install it. == Linux installation instructions == The [http://www.vmware.com/products/player/ VMPlayer download] comes as a .bundle file. That's a binary executable, that will launch a setup wizard. First, change to the directory where you downloaded the VMPlayer binary by using the command {{{cd}}}. Tip: {{{cd}}} changes the current working directory to a different directory. You can learn more about any command by reading the manual pages. Simply prefix the command with the word "man", e.g. {{{man cd}}}. Next, check to see if the file is executable. Run this command: |
If your patch has not been responded to within three business days (not including weekend days), the mentors may have missed it, and you may want to resend it. Make sure to use RESEND in the subject line if the patch itself has not been changed (meaning no changes in the patch description or body). You can use the `--subject-prefix` argument to `git format-patch` to add RESEND, by running |
| Line 44: | Line 21: |
| ls -l}}} | git format-patch --subject-prefix="RESEND PATCH" }}} |
| Line 46: | Line 24: |
| Then look at at the file's listing, and see if it has the executable ("x") bit set: | That command will create an email you can send with mutt (or your approved mail client) that will have a subject that looks like: |
| Line 49: | Line 27: |
| $ ls -l total 181056 -rw-rw-r-- 1 sarah sarah 185386101 Apr 26 22:19 VMware-Player-5.0.2-1031769.x86_64.bundle}}} |
[RESEND PATCH] Foo: Fix these things }}} |
| Line 53: | Line 30: |
| If it doesn't show the executable bit, make the file executable by running: | If your patch hasn't been responded to within a week, ping a mentor (or jlawall) on the IRC channel. '''Do not ping mentors immediately after sending patches.''' We know you're excited/worried about submitting your first patch, but mentors need to take time to properly respond and review patches. |
| Line 55: | Line 32: |
| {{{ chmod a+x VMware-Player-5.0.2-1031769.x86_64.bundle}}} |
[[Anchor(tips)]] = Tips for Applying to be an Outreachy Kernel intern = |
| Line 58: | Line 35: |
| Then execute the binary by prefixing it with a ./ and running it as the root user with sudo: | After you complete the first patch tutorial and get a patch accepted into the Linux kernel, you may wonder what to do next. We recommend getting 3-5 single cleanup patches accepted, and then moving on to create a patchset with several different cleanups for the same staging driver. Please limit your patchsets to no more than 10 patches, unless you've been told to break the patchset down further. Please try to limit your patches to no more than 100 to 200 lines total, to avoid mentors getting patch review fatigue. If you're bored and losing focus when you're tediously creating the patch, it's highly likely the mentors will get tired while reviewing it. :) |
| Line 60: | Line 37: |
| {{{ sudo ./VMware-Player-5.0.2-1031769.x86_64.bundle}}} |
Once you've gotten 3-5 patchsets accepted, move onto exploring more complex tools, like sparse and coccinelle. Try to tackle some code refactoring, or take on a [:OutreachyTasks:small task]. Mentors will link to their task lists on the [:OutreachyIntro:Outreachy introduction page]. Mentors are more likely to pick you for their project if they see you tackling tasks from that project or asking questions about that project. |
| Line 63: | Line 39: |
| Tip: Be careful about what you run as root! The root user has access to all the files on your system, so you usually don't want to run arbitrary commands as root. Always run commands without sudo, and without changing to a root terminal, where ever possible. | Tackling increasingly complex patches mean the Outreachy mentors will get a sense of how good a C programmer you are. It's very easy for beginner C programmers to do some of the more simple checkpatch cleanups, but it takes more skill to complete our mentor's small tasks, or sparse and coccinelle patches. You may find yourself trying to understand advanced C topics, such as [http://stackoverflow.com/questions/1665250/why-declare-a-variable-or-function-static-in-c/1665270#1665270 when to declare a function static]. If you are attempting silence a checkpatch.pl warning, and you don't understand what the warning message means, please ask on IRC or the mailing list before blindly trying to silence the warning. We value applicants that know when they need help, and we are happy to share knowledge and help you expand your skillset. |
| Line 65: | Line 41: |
| Now run VMPlayer with the command: | Please remember that we value consistently clean patches, so make sure to compile your code and ensure that no checkpatch errors or build warnings were added. Do this every single time for every patch revision, immediately before you send your patches out. We value applicants that learn fast enough to avoid making the same mistakes twice. It's a good practice to keep a log of improvements people have suggested for your previous patches, and double check that before submitting a new patch or patchset. |
| Line 67: | Line 43: |
| {{{ vmplayer}}} |
We look for applicants that can revise patches based on feedback from mentors. If you get feedback on a patch, change the code and send a revised patch. Don't just go onto the next patch. We value applicants that consistently send or revise patches every day, or every other day, rather than being sporadic about when patches are sent. Our best interns made the application process a part of their daily routine: prepare a patchset early in the day, go about their lives, and revise the patchset based on feedback received later in the day. Rinse and repeat. |
| Line 70: | Line 45: |
| We also value clear, concise communication. If you have a setup issue, tell us the exact failure mode, how to reproduce the failure, and what you've done to try and trouble shoot the failure. Please ensure that when you ask a question on IRC, you remain connected to the channel until someone answers your question. If no one answers in a couple hours, send the question to the mailing list. | |
| Line 71: | Line 47: |
| = Download our Linux VM image = | We look for applicants that have a knack for seeking documentation and resources their own, while still knowing when to ask questions. If you have been stuck on a problem for more than a day, seek help! We love to see applicants ask questions on IRC and the mailing list, and we especially appreciate applicants that help each other out. Helping out someone who is struggling means you get to share your knowledge, and the act of writing down what you know will solidify that knowledge in your mind. It also shows the Outreachy mentors that you're learning new skills, and are willing to share that knowledge. Bonus points if you make a kernelnewbies account and correct or add knowledge to this wiki. To edit the wiki, create an account, and then send an email to the opw-kernel mailing list with the subject "[KERNEL NEWBIES ACCESS] username", where username is your kernel newbies username. |
| Line 73: | Line 49: |
| Before you start the VM, you need to make some adjustments to the emulated hardware. FIXME talk about increasing the amount of RAM to at least 2GB, unless the maximum recommended amount of RAM is less than 2GB. | During the intern selection process, mentors will often already have a particular applicant in mind they want to pick. This applicant has often worked directly with the mentor, asked them questions, or sent them a detailed timeline for their project. Often times one particular project is very popular, because the mentor is highly responsive on the mailing list, and applicants like working with them. In that case, that project may be the first or second choice for many of the Outreachy applicants. Therefore, it is important to list several projects you are interested in, and make sure to work on small tasks from at least 2-3 Outreachy mentors. |
| Line 75: | Line 51: |
| = Configure kernel drivers = | There are also a few factors outside your control that may impact whether you are selected for an Outreachy internship. We try to ensure that the timezone difference between mentors and interns is acceptable. If the project requires specialized hardware, and it is difficult to get packages through customs in your country, you may not be selected for that project. An Outreachy internship is a full-time commitment, so we cannot accept you if you're working a full-time job, or taking more than one or two classes during the internship period. If there are many very good candidates, you may not be selected to be an Outreachy intern this round. We encourage you to apply next round, since you'll have a head start over the other candidates. |
| Line 77: | Line 53: |
| = Compile and install the kernel = = Make a driver change = = Test your changes = = Create a patch = = Submit a patch = TODO: * Outline of what this tutorial covers * If you run into any issues, ask on the opw irc channel, or email sarah.a.sharp at linux.intel.com * Find out which drivers you have installed (maybe plug in any USB devices on hand) * Make small change in one of the drivers (e.g. run checkpatch over them, or fix some grammer in the printks) * Or maybe pick a driver in staging and run checkpatch on it * Test your patch (may need to enable debugging) * Make a patch (link to art of patch description creation) * Send patch to kernel newbies mailing list as RFC (perhaps we need a separate mailing list?) |
Good luck, future Linux kernel developers! |
Hooray! Thanks for your interest in working on the Linux kernel. The next step is to [:OutreachyApply:apply] to Outreachy, and use this tutorial to create your first patch to the Linux kernel.
Intro
If you run into any issues with this tutorial, please ask questions on the #kernel-outreachy IRC channel on irc.oftc.net, or on the [https://groups.google.com/forum/#!forum/outreachy-kernel outreachy-kernel mailing list]. Please make sure to set your real name in your IRC client, so that we can correlate names and emails with irc handles.
Contribution Instructions
All patches, to be considered must be sent to the [https://groups.google.com/forum/#!forum/outreachy-kernel outreachy-kernel mailing list] (outreachy-kernel@googlegroups.com). In this round, we also ask that you submit your patches to the maintainers of the various staging drivers. Information about this is below. If you have any questions about any aspect of the patch submission process, please ask on the mailing list.
Resending patches
If you find a mistake in your initial patch submission, and you need to correct it, make sure to version your new patch as described in the previous section.
If your patch has not been responded to within three business days (not including weekend days), the mentors may have missed it, and you may want to resend it. Make sure to use RESEND in the subject line if the patch itself has not been changed (meaning no changes in the patch description or body). You can use the --subject-prefix argument to git format-patch to add RESEND, by running
git format-patch --subject-prefix="RESEND PATCH"
That command will create an email you can send with mutt (or your approved mail client) that will have a subject that looks like:
[RESEND PATCH] Foo: Fix these things
If your patch hasn't been responded to within a week, ping a mentor (or jlawall) on the IRC channel. Do not ping mentors immediately after sending patches. We know you're excited/worried about submitting your first patch, but mentors need to take time to properly respond and review patches.
Tips for Applying to be an Outreachy Kernel intern
After you complete the first patch tutorial and get a patch accepted into the Linux kernel, you may wonder what to do next. We recommend getting 3-5 single cleanup patches accepted, and then moving on to create a patchset with several different cleanups for the same staging driver. Please limit your patchsets to no more than 10 patches, unless you've been told to break the patchset down further. Please try to limit your patches to no more than 100 to 200 lines total, to avoid mentors getting patch review fatigue. If you're bored and losing focus when you're tediously creating the patch, it's highly likely the mentors will get tired while reviewing it. 
Once you've gotten 3-5 patchsets accepted, move onto exploring more complex tools, like sparse and coccinelle. Try to tackle some code refactoring, or take on a [:OutreachyTasks:small task]. Mentors will link to their task lists on the [:OutreachyIntro:Outreachy introduction page]. Mentors are more likely to pick you for their project if they see you tackling tasks from that project or asking questions about that project.
Tackling increasingly complex patches mean the Outreachy mentors will get a sense of how good a C programmer you are. It's very easy for beginner C programmers to do some of the more simple checkpatch cleanups, but it takes more skill to complete our mentor's small tasks, or sparse and coccinelle patches. You may find yourself trying to understand advanced C topics, such as [http://stackoverflow.com/questions/1665250/why-declare-a-variable-or-function-static-in-c/1665270#1665270 when to declare a function static]. If you are attempting silence a checkpatch.pl warning, and you don't understand what the warning message means, please ask on IRC or the mailing list before blindly trying to silence the warning. We value applicants that know when they need help, and we are happy to share knowledge and help you expand your skillset.
Please remember that we value consistently clean patches, so make sure to compile your code and ensure that no checkpatch errors or build warnings were added. Do this every single time for every patch revision, immediately before you send your patches out. We value applicants that learn fast enough to avoid making the same mistakes twice. It's a good practice to keep a log of improvements people have suggested for your previous patches, and double check that before submitting a new patch or patchset.
We look for applicants that can revise patches based on feedback from mentors. If you get feedback on a patch, change the code and send a revised patch. Don't just go onto the next patch. We value applicants that consistently send or revise patches every day, or every other day, rather than being sporadic about when patches are sent. Our best interns made the application process a part of their daily routine: prepare a patchset early in the day, go about their lives, and revise the patchset based on feedback received later in the day. Rinse and repeat.
We also value clear, concise communication. If you have a setup issue, tell us the exact failure mode, how to reproduce the failure, and what you've done to try and trouble shoot the failure. Please ensure that when you ask a question on IRC, you remain connected to the channel until someone answers your question. If no one answers in a couple hours, send the question to the mailing list.
We look for applicants that have a knack for seeking documentation and resources their own, while still knowing when to ask questions. If you have been stuck on a problem for more than a day, seek help! We love to see applicants ask questions on IRC and the mailing list, and we especially appreciate applicants that help each other out. Helping out someone who is struggling means you get to share your knowledge, and the act of writing down what you know will solidify that knowledge in your mind. It also shows the Outreachy mentors that you're learning new skills, and are willing to share that knowledge. Bonus points if you make a kernelnewbies account and correct or add knowledge to this wiki. To edit the wiki, create an account, and then send an email to the opw-kernel mailing list with the subject "[KERNEL NEWBIES ACCESS] username", where username is your kernel newbies username.
During the intern selection process, mentors will often already have a particular applicant in mind they want to pick. This applicant has often worked directly with the mentor, asked them questions, or sent them a detailed timeline for their project. Often times one particular project is very popular, because the mentor is highly responsive on the mailing list, and applicants like working with them. In that case, that project may be the first or second choice for many of the Outreachy applicants. Therefore, it is important to list several projects you are interested in, and make sure to work on small tasks from at least 2-3 Outreachy mentors.
There are also a few factors outside your control that may impact whether you are selected for an Outreachy internship. We try to ensure that the timezone difference between mentors and interns is acceptable. If the project requires specialized hardware, and it is difficult to get packages through customs in your country, you may not be selected for that project. An Outreachy internship is a full-time commitment, so we cannot accept you if you're working a full-time job, or taking more than one or two classes during the internship period. If there are many very good candidates, you may not be selected to be an Outreachy intern this round. We encourage you to apply next round, since you'll have a head start over the other candidates.
Good luck, future Linux kernel developers!