README

   1
   2                                   util-linux
   3
   4                 util-linux is a random collection of Linux utilities
   5
   6      Note: for the years 2006-2010 this project was named "util-linux-ng".
   7
   8 COMPILE & INSTALL:
   9
  10       See Documentation/howto-compilation.txt.
  11
  12 MAILING LIST:
  13
  14       E-MAIL:  util-linux@vger.kernel.org
  15       URL:     http://vger.kernel.org/vger-lists.html#util-linux
  16       ARCHIVE: https://lore.kernel.org/util-linux/
  17
  18       The mailing list will reject email messages that contain:
  19        - more than 100K characters
  20        - html
  21        - spam phrases/keywords
  22       See: http://vger.kernel.org/majordomo-info.html#taboo
  23
  24 IRC CHANNEL:
  25
  26       #util-linux at freenode.net:
  27
  28       irc://chat.freenode.net/util-linux
  29
  30       The IRC channel and Mailing list are for developers and project
  31       maintainers. For end users it is recommended to utilize the
  32       distribution's support system.
  33
  34 BUG REPORTING:
  35
  36       E-MAIL: util-linux@vger.kernel.org
  37       Web:    https://github.com/karelzak/util-linux/issues
  38
  39       This project has no resources to provide support for distribution specific
  40       issues. For end users it is recommended to utilize the distribution's
  41       support system.
  42
  43 NLS (PO TRANSLATIONS):
  44
  45       PO files are maintained by:
  46           http://translationproject.org/domain/util-linux.html
  47
  48 VERSION SCHEMA:
  49
  50       Standard releases:
  51           <major>.<minor>[.<maint>]
  52              major = fatal and deep changes
  53              minor = typical release with new features
  54              maint = maintenance releases; bug fixes only
  55
  56       Development releases:
  57          <major>.<minor>-rc<N>
  58
  59 SOURCE CODE:
  60
  61  Download archive:
  62           https://www.kernel.org/pub/linux/utils/util-linux/
  63
  64  See also:
  65      Documentation/howto-contribute.txt
  66      Documentation/howto-build-sys.txt
  67      Documentation/howto-pull-request.txt
  68
  69  SCM (Source Code Management) Repository:
  70
  71     Primary repository:
  72           git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
  73
  74     Backup repository:
  75           git clone git://github.com/karelzak/util-linux.git
  76
  77     Web interfaces:
  78           http://git.kernel.org/cgit/utils/util-linux/util-linux.git
  79           https://github.com/karelzak/util-linux
  80
  81       Note: the GitHub repository may contain temporary development branches too.
  82
  83       The kernel.org repository contains master (current development) and stable/*
  84       (maintenance) branches only. All master or stable/* changes are always pushed
  85       to both repositories at the same time.
  86
  87     Repository Branches: 'git branch -a'
  88           master branch
  89            - current development
  90            - the source for stable releases when deemed ready.
  91            - day-to-day status is: 'it works for me'. This means that its
  92              normal state is useful but not well tested.
  93            - long-term development or invasive changes in active development are
  94              forked into separate 'topic' branches from the tip of 'master'.
  95
  96           stable/ branches
  97            - public releases
  98            - branch name: stable/v<major>.<minor>.
  99            - created from the 'master' branch after two or more release
 100              candidates and the final public release. This means that the stable
 101              releases are committed, tagged, and reachable in 'master'.
 102            - these branches then become forked development branches. This means
 103              that any changes made to them diverge from the 'master' branch.
 104            - maintenance releases are part of, and belong to, their respective
 105              stable branch. As such, they are tags(<major>.<minor>.<maint>) and
 106              not branches of their own. They are not part of, visible in, or
 107              have anything to do with the 'master' development branch. In git
 108              terminology: maintenance releases are not reachable from 'master'.
 109            - when initially cloned (as with the 'git clone' command given above)
 110              these branches are created as 'remote tracking branches' and are
 111              only visible by using the -a or -r options to 'git branch'. To
 112              create a local branch use the desired tag with this command:
 113              'git checkout -b v2.29.2 v2.29.2'
 114
 115     Tags: 'git tag'
 116            - a new tag object is created for every release.
 117            - tag name: v<version>.
 118            - all tags are signed by the maintainer's PGP key.
 119
 120     Known Bugs:
 121         - don't use tag v2.13.1 (created and published by mistake),
 122           use v2.13.1-REAL instead.
 123
 124 WORKFLOW EXAMPLE:
 125
 126  1) development (branch: <master>)
 127
 128  2) master release (tags: v2.29-rc1, v2.29-rc2, v2.29, branch: <master>)
 129
 130  3) development (work on v2.30, branch: <master>)
 131
 132  4) fork -- create a new branch <stable/v2.29> based on tag v2.29
 133
 134      4a) new patches or cherry-pick patches from <master> (branch: <stable/v2.29>)
 135
 136      4b) stable release (tag: v2.29.1, branch: <stable/v2.29>)
 137
 138      4c) more patches; another release (tag: v2.29.2, branch: <stable/v2.29>)
 139
 140  5) master release v2.30 (branch: <master>)
 141     ...
 142
 143 where 3) and 4) happen simultaneously.
 144