README.devel

   1
   2  Notes for util-linux developers
   3  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4
   5 AUTOTOOLS:
   6
   7      * "./autogen.sh" generates all files needed to compile and install the code
   8        (run it after checkout from git)
   9
  10      * "make distclean" removes all unnecessary files, but the code can still be
  11        recompiled with "./configure; make"
  12
  13      * "make dist-gzip" (or -bzip2) creates a tarball that can be configured and
  14        compiled without running "./autogen.sh"
  15
  16
  17 PATCHES:
  18
  19      * send your patches to the mailing list or to the upstream maintainer
  20        (see the AUTHORS and README files)
  21
  22      * diff -u
  23
  24      * don't include generated (autotools) stuff to your patches
  25        (hint: use git-clean [-X])
  26
  27      * patches are delivered via email only.  Downloading them from internet
  28        servers is a pain.
  29
  30      * one patch per email, with the changelog in the body of the email.
  31
  32      * many small patches are favoured over one big. Break down is done on
  33        basis of logical functionality; for example #endif mark ups, compiler
  34        warning and exit codes fixes all should be individual small patches.
  35
  36      * Subject: [PATCH] subsystem: description
  37
  38      * if someone else wrote the patch, they should be credited (and blamed)
  39        for it. To communicate this, add a line:
  40
  41           From: John Doe <jdoe@wherever.com>
  42
  43      * add a Signed-off-by line (hint: use "git commit -s")
  44
  45        The sign-off is a simple line at the end of the explanation for the
  46        patch, which certifies that you wrote it or otherwise have the right to
  47        pass it on as a open-source patch.  The rules are pretty simple: if you
  48        can certify the below:
  49
  50            By making a contribution to this project, I certify that:
  51
  52            (a) The contribution was created in whole or in part by me and I
  53                have the right to submit it under the open source license
  54                indicated in the file; or
  55
  56            (b) The contribution is based upon previous work that, to the best
  57                of my knowledge, is covered under an appropriate open source
  58                license and I have the right under that license to submit that
  59                work with modifications, whether created in whole or in part
  60                by me, under the same open source license (unless I am
  61                permitted to submit under a different license), as indicated
  62                in the file; or
  63
  64            (c) The contribution was provided directly to me by some other
  65                person who certified (a), (b) or (c) and I have not modified it.
  66
  67            (d) I understand and agree that this project and the contribution
  68                are public and that a record of the contribution (including all
  69                personal information I submit with it, including my sign-off) is
  70                maintained indefinitely and may be redistributed consistent with
  71                this project or the open source license(s) involved.
  72
  73        then you just add a line saying
  74
  75                Signed-off-by: Random J Developer <random@developer.example.org>
  76
  77        using your real name (sorry, no pseudonyms or anonymous contributions.)
  78
  79
  80      * for more details see:
  81
  82        The perfect patch
  83                 http://userweb.kernel.org/~akpm/stuff/tpp.txt
  84
  85 CODING STYLE:
  86
  87      * the preferred coding style is based on the linux kernel Documentation/CodingStyle.
  88        For more details see:
  89
  90        http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/CodingStyle
  91
  92
  93 SCM (source code management):
  94
  95      git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git util-linux
  96
  97
  98     * maintenance (stable) branch
  99         - created for every <major>.<minor> release
 100         - branch name: stable/v<major>.<minor>
 101
 102     * bugfix branch
 103         - created for <major>.<minor>.<maint> release for critical/security bugs only
 104         - this branch is optional
 105         - branch name: stable/v<major>.<minor>.<maint>
 106
 107     * master branch
 108         - the status of this branch is: "it works for me". It means useful
 109           but not well tested patches.
 110         - it's source for occasional snapshots
 111         - for long-term development or invasive changes should be an active
 112           development forked into a separate branch (topic branches) from the
 113           tip of "master".
 114
 115     * A new tag object is created for:
 116         - every release, tag name: v<version>
 117
 118
 119     * KNOWN BUGS:
 120         - tag v2.13.1 is typo. Please, ignore this tag.
 121