code.delx.au - gnu-emacs-elpa/blob - packages/README

   1 This directory contains most of the source code of the GNU ELPA packages.
   2
   3 Each directory in here corresponds to a package, which can be
   4 either a single-file package or a multifile package.
   5
   6 A nightly cron job refreshes the GNU ELPA archive from this repository.
   7
   8 This cron job only creates a new package when the "version" (as specified in
   9 the foo-pkg.el or in the "Version:" header) of a package is modified.
  10 This means that you can safely work on the next version here without
  11 worrying about the unstable code making it to GNU ELPA, and simply update
  12 the "version" when you want to release the new code.
  13
  14 * Format
  15
  16 Each package should follow the ELPA packaging conventions, but there are
  17 some differences due to the way the deployment script creates the packages
  18 and the web-pages from this source code:
  19 - Multi-file packages can put the package metadata in the main <pkg>.el file
  20   in the format used for single-file packages, in which case the script
  21   will auto-generate the <pkg>-pkg.el file.
  22 - the "URL:" header (or :url property) can be used to specify the home page
  23   of the package, if it's maintained externally.
  24 - A "News:" section (or "NEWS" file) can/should be used to list the
  25   user-visible changes of each version.
  26 - The "Package-Type: simple" header can be used to force the creation
  27   of a single-file package even when there are several Elisp files in
  28   the source (the other files will simply be ignored).
  29
  30 * External branches
  31
  32 Some packages are maintained in external branches.  These should be
  33 appropriately listed in the `externals-list' file.
  34 There are two different cases: subtrees and externals.
  35
  36 In both cases, a copy of the code is kept in the `elpa' repository and
  37 should be sync'd with the upstream every once in a while.  This copy may
  38 include local changes, tho ideally these should be kept to a minimum.
  39
  40 In the `subtree' case, the copy of the code is kept here in the
  41 corresponding `packages/<pkg>' directory.  You should be able to "git
  42 merge -s subtree" from the upstream branch.
  43
  44 In the `external' case, the copy of the code is not kept here but in the
  45 `externals/<pkg>' branch in the `elpa' repository.
  46 You can check out all the external packages into the `packages' directory
  47 with the command:
  48
  49    make externals