From: Stefan Monnier Date: Thu, 30 Jan 2014 14:00:43 +0000 (-0500) Subject: Merge the two README. Update copyright_exceptions. X-Git-Url: https://code.delx.au/gnu-emacs-elpa/commitdiff_plain/d108f0602af508e89e035863ab1a9b2b427ab232 Merge the two README. Update copyright_exceptions. --- diff --git a/README b/README index 1eafa3ddd..9cf7ad709 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -Copyright (C) 2010-2011 Free Software Foundation, Inc. +Copyright (C) 2010-2011, 2014 Free Software Foundation, Inc. See the end of the file for license conditions. @@ -23,44 +23,112 @@ for testing purposes). This directory holds the package sources, with one subdirectory for each package. +Each directory in here corresponds to a package, which can be +either a single-file package or a multifile package. + +A nightly cron job refreshes the GNU ELPA archive from this repository. + +This cron job only creates a new package when the "version" (as specified in +the "Version:" header) of a package is modified. This means that you can +safely work on the next version here without worrying about the unstable +code making it to GNU ELPA, and simply update the "version" when you want to +release the new code. + ** To add a package: *** Add a simple (1-file) package as packages/NAME/NAME.el. +The file needs to follow the usual coding conventions (most importantly +start with ";;; --- ") and have a "Version:" and +"Maintainer:" pseudo-header. + *** Add a multi-file package as a directory, packages/NAME. +It needs to have a file named packages/NAME/NAME.el which follows the same +rules as above. + *** Commit your changes the usual way ("git add", "git commit", etc). Changes in the Git repository do not immediately propagate to the user-facing archive (what users see when they do `M-x list-packages'). -That is done by deploying the archive. - +That is done by deploying the archive, which happens automatically +once a day, and the changes are only reflected when the "Version:" +header changes. + +** Format + +Each package should follow the ELPA packaging conventions, but there are +some differences due to the way the deployment script creates the packages +and the web-pages from this source code: +- Multi-file packages put the package metadata in the main .el file + in the format used for single-file packages: the -pkg.el file is + auto-generated from it. +- Every package should have both a "Version:" *and* a "Maintainer:". +- the "URL:" header can be used to specify the home page + of the package, if it's maintained externally. +- A "News:" section (or "NEWS" file) can/should be used to list the + user-visible changes of each version. +- The "Package-Type:" header can be used to force the type of package + created (can be either `simple' for single-file packages or `multi' for + tarballs). By default the type is decided based on whether there are + several Elisp files in the source. +- If you want some files to not be included in the tarball, you can + put a `.elpaignore' file in the root of your package directory, where you + can list patterns of files to ignore (this file is passed to tar's -X). + +** External branches + +Some packages are maintained in external branches. These should be +appropriately listed in the `externals-list' file. +There are two different cases: subtrees and externals. + +In both cases, a copy of the code is kept in the `elpa' repository and +should be sync'd with the upstream every once in a while. This copy may +include local changes, tho ideally these should be kept to a minimum. + +In the `subtree' case, the copy of the code is kept here in the +corresponding `packages/' directory. You should be able to "git +merge -s subtree" from the upstream branch. + +In the `external' case, the copy of the code is not kept here but in the +`externals/' branch in the `elpa' repository. +You can check out all the external packages into the `packages' directory +with the command: + + make externals + +** Public incubation + +If you want to develop a package publicly prior to its first release (to +benefit from others' feedback, primarily), but not in an external repo, +you can push to an "ephemeral" branch -- subject to rebase and eventual +removal upon finishing merge -- for the duration of the incubation. * DEPLOYMENT -** To deploy the package repository locally: +** To install all the packages "in place": - make + make externals + make This compiles and generates autoloads for all the packages in the -packages/ directory. The resulting archive is the same packages/ -directory. - -** To deploy the package repository as a remotely-accessible archive: +packages/ directory. You can then add that directory, e.g. with: - make archive +(eval-after-load 'package + '(add-to-list 'package-directory-list ".../elpa/packages")) -or - - make archive-full +** To deploy the package repository as a remotely-accessible archive: -This deploys the packages to the archive/ directory. Unlike "make -site", this makes a full copy of the packages, and tars up multi-file -packages. + git clone .../elpa + mkdir build + cd build + ln -s ../elpa/admin + ln -s ../elpa/GNUmakefile + admin/update-archive.sh -A full deployment also copies the admin scripts to archive/admin, and -fetches externally hosted packages (currently, the Org daily builds) -and adds them to the archive. +This deploys the packages to the staging/ directory (sibling of "build"). +Unlike "make", this makes a full copy of the packages, tars up +multi-file packages, and doesn't byte-compile any files. ** To access a deployed archive @@ -77,13 +145,14 @@ archives" are useful for debugging: ** Notes specific to elpa.gnu.org The way things are set up on this machine, we refresh the archive by -logging in (login access set up by FSF admins), and +a cron job. You can do it by hand by logging in (access set up by FSF +admins), and -su elpa -cd ~elpa/elpa -bzr up + su elpa + cd ~elpa/build + admin/update-archive.sh -Then make a full archive deployment, as discussed above. The symlink +Which makes a full archive deployment, as discussed above. The symlink /var/www/packages points to the staging package directory under /home/elpa/. diff --git a/copyright_exceptions b/copyright_exceptions index c41d0ea0e..aa9da629e 100644 --- a/copyright_exceptions +++ b/copyright_exceptions @@ -57,8 +57,8 @@ ./auctex/tex-fold.el: ("(C)" ("copyright")) ./auctex/tex-info.el: '("copyright" nil) ./muse/htmlize-hack.el -./uni-confusables/gen-confusables.el: (insert ";; Copyright (C) 1991-2009, 2010 Unicode, Inc. -./uni-confusables/gen-confusables.el:;; for the copyright and permission notice.\n\n") +./uni-confusables/gen-confusables.el:;; Copyright (C) 1991-2009, 2010 Unicode, Inc. +./uni-confusables/gen-confusables.el:;; for the copyright and permission notice. ./uni-confusables/uni-confusables.el ./uni-confusables/uni-confusables.el:;; Copyright (C) 1991-2009, 2010 Unicode, Inc. ./uni-confusables/uni-confusables.el:;; for the copyright and permission notice. diff --git a/packages/README b/packages/README deleted file mode 100644 index 4c8545a1b..000000000 --- a/packages/README +++ /dev/null @@ -1,61 +0,0 @@ -This directory contains most of the source code of the GNU ELPA packages. - -Each directory in here corresponds to a package, which can be -either a single-file package or a multifile package. - -A nightly cron job refreshes the GNU ELPA archive from this repository. - -This cron job only creates a new package when the "version" (as specified in -the foo-pkg.el or in the "Version:" header) of a package is modified. -This means that you can safely work on the next version here without -worrying about the unstable code making it to GNU ELPA, and simply update -the "version" when you want to release the new code. - -* Format - -Each package should follow the ELPA packaging conventions, but there are -some differences due to the way the deployment script creates the packages -and the web-pages from this source code: -- Multi-file packages can put the package metadata in the main .el file - in the format used for single-file packages, in which case the script - will auto-generate the -pkg.el file. -- the "URL:" header (or :url property) can be used to specify the home page - of the package, if it's maintained externally. -- A "News:" section (or "NEWS" file) can/should be used to list the - user-visible changes of each version. -- The "Package-Type:" header can be used to force the type of package - created (can be either `simple' for single-file packages or `multi' for - tarballs). By default the type is decided based on whether there are - several Elisp files in the source (the other files will simply be - ignored). -- If you want some files to not be included in the tarball, you can - put a `.elpaignore' file in the root of your package directory, where you - can list patterns of files to ignore (this file is passed to tar's -X). - -* External branches - -Some packages are maintained in external branches. These should be -appropriately listed in the `externals-list' file. -There are two different cases: subtrees and externals. - -In both cases, a copy of the code is kept in the `elpa' repository and -should be sync'd with the upstream every once in a while. This copy may -include local changes, tho ideally these should be kept to a minimum. - -In the `subtree' case, the copy of the code is kept here in the -corresponding `packages/' directory. You should be able to "git -merge -s subtree" from the upstream branch. - -In the `external' case, the copy of the code is not kept here but in the -`externals/' branch in the `elpa' repository. -You can check out all the external packages into the `packages' directory -with the command: - - make externals - -* Public incubation - -If you want to develop a package publicly prior to its first release (to -benefit from others' feedback, primarily), but not in an external repo, -you can push to an "ephemeral" branch -- subject to rebase and eventual -removal upon finishing merge -- for the duration of the incubation.