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:" header can be used to force the type of package
  27   created (can be either `simple' for single-file packages or `multi' for
  28   tarballs).  By default the type is decided based on whether there are
  29   several Elisp files in the source (the other files will simply be
  30   ignored).
  31 - If you want some files to not be included in the tarball, you can
  32   put a `.elpaignore' file in the root of your package directory, where you
  33   can list patterns of files to ignore (this file is passed to tar's -X).
  34
  35 * External branches
  36
  37 Some packages are maintained in external branches.  These should be
  38 appropriately listed in the `externals-list' file.
  39 There are two different cases: subtrees and externals.
  40
  41 In both cases, a copy of the code is kept in the `elpa' repository and
  42 should be sync'd with the upstream every once in a while.  This copy may
  43 include local changes, tho ideally these should be kept to a minimum.
  44
  45 In the `subtree' case, the copy of the code is kept here in the
  46 corresponding `packages/<pkg>' directory.  You should be able to "git
  47 merge -s subtree" from the upstream branch.
  48
  49 In the `external' case, the copy of the code is not kept here but in the
  50 `externals/<pkg>' branch in the `elpa' repository.
  51 You can check out all the external packages into the `packages' directory
  52 with the command:
  53
  54    make externals
  55
  56 * Public incubation
  57
  58 If you want to develop a package publicly prior to its first release (to
  59 benefit from others' feedback, primarily), but not in an external repo,
  60 you can push to an "ephemeral" branch -- subject to rebase and eventual
  61 removal upon finishing merge -- for the duration of the incubation.