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