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      * Subject: [PATCH] subsystem: description
  33
  34      * if someone else wrote the patch, they should be credited (and blamed)
  35        for it. To communicate this, add a line:
  36
  37           From: John Doe <jdoe@wherever.com>
  38
  39      * add a Signed-off-by line (hint: use "git commit -s")
  40
  41        The sign-off is a simple line at the end of the explanation for the
  42        patch, which certifies that you wrote it or otherwise have the right to
  43        pass it on as a open-source patch.  The rules are pretty simple: if you
  44        can certify the below:
  45
  46            By making a contribution to this project, I certify that:
  47
  48            (a) The contribution was created in whole or in part by me and I
  49                have the right to submit it under the open source license
  50                indicated in the file; or
  51
  52            (b) The contribution is based upon previous work that, to the best
  53                of my knowledge, is covered under an appropriate open source
  54                license and I have the right under that license to submit that
  55                work with modifications, whether created in whole or in part
  56                by me, under the same open source license (unless I am
  57                permitted to submit under a different license), as indicated
  58                in the file; or
  59
  60            (c) The contribution was provided directly to me by some other
  61                person who certified (a), (b) or (c) and I have not modified it.
  62
  63            (d) I understand and agree that this project and the contribution
  64                are public and that a record of the contribution (including all
  65                personal information I submit with it, including my sign-off) is
  66                maintained indefinitely and may be redistributed consistent with
  67                this project or the open source license(s) involved.
  68
  69        then you just add a line saying
  70
  71                Signed-off-by: Random J Developer <random@developer.example.org>
  72
  73        using your real name (sorry, no pseudonyms or anonymous contributions.)
  74
  75
  76      * for more details see:
  77
  78        The perfect patch
  79                 http://userweb.kernel.org/~akpm/stuff/tpp.txt
  80
  81 CODING STYLE:
  82
  83      * the preferred coding style is based on the linux kernel Documentation/CodingStyle.
  84        For more details see:
  85
  86        http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/CodingStyle
  87
  88
  89 SCM (source code management):
  90
  91      git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git util-linux
  92
  93
  94     * maintenance (stable) branch
  95         - created for every <major>.<minor> release
  96         - branch name: stable/v<major>.<minor>
  97
  98     * bugfix branch
  99         - created for <major>.<minor>.<maint> release for critical/security bugs only
 100         - this branch is optional
 101         - branch name: stable/v<major>.<minor>.<maint>
 102
 103     * master branch
 104         - the status of this branch is: "it works for me". It means useful
 105           but not well tested patches.
 106         - it's source for occasional snapshots
 107         - for long-term development or invasive changes should be an active
 108           development forked into a separate branch (topic branches) from the
 109           tip of "master".
 110
 111     * A new tag object is created for:
 112         - every release, tag name: v<version>
 113
 114
 115     * KNOWN BUGS:
 116         - tag v2.13.1 is typo. Please, ignore this tag.
 117