README.submitting-patches

   1 How to get your Socket-CAN changes into the Linux kernel or BerliOS repo
   2 ========================================================================
   3
   4 The Socket-CAN repository at BerliOS [1] allows to build *out-of-tree*
   5 Socket-CAN kernel modules and is mainly useful for old kernel versions
   6 and development. Currently it is based on Subversion but we want to
   7 switch to GIT sooner or later. We try to keep the BerliOS repo in sync
   8 with the kernel by backporting patches from the kernel and vice versa.
   9
  10 If your changes are already mature in terms of functionality and code
  11 quality, you may want to get them immediately into the mainline kernel.
  12 If you feel that's not already the case and some more discussion and
  13 feedback is required, it's useful to prepare and publish a patch for the
  14 BerliOS repo first. Also the requirements for acceptance are not that
  15 strict than for kernel inclusion. If kernel inclusion is your primary
  16 goal, it makes sense to start preparing patches for the kernel
  17 straightaway. An eventual backport to the BerliOS repo is usually quite
  18 simple and does not require a full review, reducing at the same time the
  19 maintainers workload.
  20
  21 Patches for kernel inclusion:
  22 ----------------------------
  23
  24 For kernel inclusion you need to prepare patches against David Millers
  25 "net-next-2.6" GIT tree, which you can get as shown below:
  26
  27   $ git clone \
  28     git://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next-2.6.git
  29
  30 In case you have a bug fix patch for a "-rcX" kernel release, you should
  31 use the tree "net-2.6" instead.
  32
  33 Before publishing you should check the following items:
  34
  35 - Please ensure that the patches comply with the Linux coding style
  36   rules by reading the kernel's "Documentation/CodingStyle" and running
  37   "scripts/checkpatch.pl".
  38
  39 - The patch should contain a proper description and your "signed-off-by"
  40   line.
  41
  42 - Please use a prefix for the subject similar to the following:
  43
  44   "[PATCH net-next-2.6] can: sja1000: ..."
  45
  46 - Please add a version string to the subject for revised patches, e.g.:
  47
  48   "[PATCH net-next-2.6 v2] can: sja1000: ..."
  49
  50   It's also common practice to describe briefly the changes.
  51
  52 - Please send the patches *inline* and take care that your mail client
  53   does *not* mangle the patches. "git-send-email" does a very good job,
  54   especially for a series of patches.
  55
  56 - "Documentation/SubmittingPatches" of the kernel tree contains further
  57   useful information.
  58
  59 The patch should finally be sent to "netdev@vger.kernel.org" [2] with a
  60 CC to "Socketcan-core@lists.berlios.de" [3] and maybe other related
  61 mailing lists, e.g. the Linux-USB mailing lists for CAN USB drivers.
  62
  63 Note that you can use "strip-src" to convert a source file from the
  64 BerliOS repo for kernel inclusion as shown below:
  65
  66   $ cd <path>/trunk
  67   $ ./strip-src -m -i -v2.6.32 \
  68     kernel/2.6/drivers/net/can/sja1000/my_driver.c > \
  69     ../net-next-2.6/drivers/net/can/sja1000/my_driver.c
  70
  71 Patches for the BerliOS repo:
  72 ----------------------------
  73
  74 You can checkout the BerliOS SVN repo [4] as shown below:
  75
  76   $ svn checkout http://svn.berlios.de/svnroot/repos/socketcan/trunk
  77
  78 In principle the same rules apply as for kernel inclusion. But there is
  79 no need to make a CC to the netdev mailing list and the code should deal
  80 with version dependencies as usual using:
  81
  82   #if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,32)
  83   ...
  84   #endif
  85
  86 To allow building the Socket-CAN modules without depending on the kernel
  87 include files, you should use:
  88
  89   #include <socketcan/can...>
  90
  91 instead of:
  92
  93   #include <linux/can...>
  94
  95 Also ND2D(dev) should be used to specify the platform device, e.g.:
  96
  97   dev_dbg(ND2D(dev), "data overrun interrupt\n");
  98
  99 References:
 100 ----------
 101
 102 [1] http://developer.berlios.de/projects/socketcan/
 103 [2] http://vger.kernel.org/vger-lists.html#netdev
 104 [3] http://developer.berlios.de/mail/?group_id=6475
 105 [4] http://developer.berlios.de/svn/?group_id=6475