added HOWTO that I'm working on.

1 files changed, 210 insertions, 0 deletions

diff --git a/HOWTO b/HOWTO
new file mode 100644
index 00000000000000..0535f100522f49
--- /dev/null
+++ b/HOWTO
@@ -0,0 +1,210 @@
+HOWTO do Linux kernel development
+
+This is the be-all, end-all document on this topic.  It contains
+instructions on how to become a Linux kernel developer and how to learn
+to work with the Linux kernel development community.
+
+If anything in this document becomes out of date, please send in patches
+to the maintainer of this file, who is listed at the bottom of the
+document.
+
+
+Intro
+-----
+
+So, you want to learn how to become a Linux kernel developer?  Or you
+have been told by your manager, "Go write a Linux driver for this
+device."  This document's goal is to teach you everything you need to
+know to achieve this by describing the process you need to go through,
+and hints on how to work with the community.  It will also try to
+explain some of the reasons why the community works like it does.
+
+What this document does not do, is teach you how to program.  There are
+plenty of good places to learn how to do this, but this is not such a
+place.
+
+First off, please remember that you are trying to learn how to work with
+the existing development community.  You should try to learn as much as
+possible ahead of time, and not expect people to adapt to you, or your
+company's way of doing things, no matter how important you feel your
+task is.
+
+
+Legal Issues
+------------
+
+The Linux kernel source code is released under the GPL.  Please see the
+file, COPYING, in the main directory of the source tree, for details on
+the license.  If you have further questions about the license, please
+contact a lawyer, and do not ask on the Linux kernel mailing list.  The
+people on the mailing lists are not lawyers, and you should not rely on
+their statements on legal matters.
+
+
+Documentation
+------------
+
+The Linux kernel source tree has a huge range of documents that are
+invaluable in learning how to interact with the kernel community.  Here
+is a list of files that are in the kernel source tree that are required
+reading:
+  Documetation/CodingStyle
+    This describes the Linux kernel coding style, and some of the
+    rational behind it.  The main point here is that we have a coding
+    style, and you can not ignore it.
+
+  Documentation/SubmittingPatches
+  Documentation/SubmittingDrivers
+    These files describe in explicit detail, the proper format of how
+    you need to create your change, what needs to be in your email, what
+    kind of email you should send, who to send it to, and everything
+    else you will need to learn in order to submit a change that will be
+    accepted into the main kernel source tree.  If you do not follow
+    these rules, the odds of your patch being accepted are very low.
+
+  Documentation/stable_api_nonsense.txt
+    This file describes the rational behind why the Linux kernel does
+    not have a stable in-kernel api.  If you want to try to come up with
+    a shim-layer for some subsystem, in order to make it easier to adapt
+    your existing code to Linux, or to try to mitigate the rapid change
+    within the Linux kernel source tree, this document describes why
+    such a proposal will fail.
+
+  Documentation/SecurityBugs
+    If you feel you have found a security problem in the Linux kernel,
+    please follow the steps in this document to help notify the kernel
+    developers, and help solve the issue.
+
+  Documentation/ManagementStyle
+    This document describes how the Linux kernel maintainers work.  If
+    you are ever confused as to exactly why a maintainer is not doing
+    what you want them to, refer to this document to help understand how
+    they work, and how to make their lives easier.
+
+  Documentation/stable_kernel_rules.txt
+    This file describes the rules on how the stable kernel releases
+    happen, and what to do if you want to get a change into one of these
+    releases.
+
+  Documentation/kernel-docs.txt
+    A list of external documentation that pertains to kernel
+    development.  Please consult this list, if you do not find what you
+    are looking for within the in-kernel documentation.
+
+
+The kernel also has a large number of documents that can be
+automatically generated from the source code itself.  This includes a
+full description of the in-kernel api, and rules on how to handle
+locking properly.  The documents will be created in the
+Documentation/DocBook/ directory and can be generated as PDF,
+Postscript, HTML, and man pages by running:
+	make pdfdocs
+	make psdocs
+	make htmldocs
+	make mandocs
+respectively from the main kernel source directory.
+
+
+Becoming A Kernel Developer
+---------------------------
+
+If you do not know anything about Linux kernel development, you should
+look at the Linux KernelNewbies project:
+	URL
+It consists of a helpful mailing list, where you can ask almost any type
+of basic kernel development question (make sure to search the archives
+first, before asking something that has already been answered in the
+past.)  It also has a IRC channel that you can use to ask questions in
+real-time, and a lot of helpful documentation that is useful for
+learning about Linux kernel development.
+
+
+If you do not know where you want to start, but you want to look for
+some task to start doing to join into the kernel development community,
+go to the Linux Kernel Janitor's project:
+	URL
+It is a great place to start.  It describes a list of relativly simple
+tasks that need to be cleaned up and fixed within the Linux kernel
+source tree.  Working with the developers in charge of this project, you
+will learn the basics of getting your patch into the Linux kernel tree,
+and possibly point you in the direction of what to go work on next, if
+you do not already have an idea.
+
+
+If you already have a chunk of code that you want to have go into the
+kernel tree, but need some help getting it in the proper form, the
+kernel-mentors project was created to help you out with this.  It is a
+mailing list, and can be found at:
+	URL
+
+
+The development process
+-----------------------
+
+Mailing lists
+-------------
+
+As some of the above documents describe, the majority of the core kernel
+developers participate on the Linux Kernel Mailing list.  Details on how
+to subscribe and unsubscribe from the list, can be found at:
+	URL
+There are archives of the mailing list on the web in many different
+places.  Please use a search engine to find these archives if you wish
+to research what has been discussed in the past.
+
+Most of the individual kernel subsystems also have their own separate
+mailing list where they do their development efforts.  See the
+MAINTAINERS file for a list of what these lists are, for the different
+groups.
+
+
+Working with the community
+--------------------------
+
+The kernel community works differently than most traditional corporate
+development environments.  Here are a list of things that you can try to
+do to try to avoid problems:
+  Good things to say regarding your proposed changes:
+    - "This solves multiple problems."
+    - "This deletes 2000 lines of code."
+    - "Here is a patch that explains what I am trying to describe."
+    - "I tested it on 5 different architectures..."
+    - "Here is a series of small patches that..."
+    - "This increases performance on typical machines..."
+
+  Bad things you should avoid saying:
+    - "We did it this way in AIX/ptx/Solaris, so therefore it must be
+      good..."
+    - "I've being doing this for 20 years, so..."
+    - "It makes this proprietary benchmark go faster"
+    - "This is required for my company to make money"
+    - "This is for our Enterprise product line."
+    - "Here is my 1000 page design document that describes my idea"
+    - "I've been working on this for 6 months..."
+    - "Here's a 5000 line patch that..."
+
+
+Break your changes up
+---------------------
+
+The Linux kernel community does not gladly accept large chunks of code
+dropped on it all at once.  The changes need to be properly introduced,
+discussed, and broken up into tiny, individual portions.  This is almost
+exactly opposite of what companies are used to doing.  Your proposal
+should also be introduced very early in the development process, so that
+you can receive feedback on what you are doing.  It also lets the
+community feel that you are working with them, and not simply using them
+as a dumping ground for your feature.
+
+
+
+
+----------
+Thanks to Randy Dunlap and Gerrit Huizenga for the list of things you
+should and should not say.  Also to XXX for their review and comments on
+early drafts of this document.
+
+
+
+Maintainer: Greg Kroah-Hartman <greg@kroah.com>
+