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