[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] new-master bc0d691 049/128: Merge the two README. Update copyrigh
From: |
Stefan Monnier |
Subject: |
[elpa] new-master bc0d691 049/128: Merge the two README. Update copyright_exceptions. |
Date: |
Mon, 14 Dec 2020 15:39:29 -0500 (EST) |
branch: new-master
commit bc0d691dd9683b2433487b636b0ef1d4ece0a05a
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>
Merge the two README. Update copyright_exceptions.
---
README | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 93 insertions(+), 24 deletions(-)
diff --git a/README b/README
index 1eafa3d..9cf7ad7 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 ";;; <file> --- <description>") 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 <pkg>.el file
+ in the format used for single-file packages: the <pkg>-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/<pkg>' 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/<pkg>' 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/.
- [elpa] new-master 34abb9b 113/128: README: Mention that the copyright in ELPA is with the FSF, (continued)
- [elpa] new-master 34abb9b 113/128: README: Mention that the copyright in ELPA is with the FSF, Stefan Monnier, 2020/12/14
- [elpa] new-master 274a403 115/128: Add 'packages/org-edna/' from commit 'd5bce9db875a7ab2b085aca265ff7f3350d224ba', Stefan Monnier, 2020/12/14
- [elpa] new-master 8b45e8c 022/128: Add SML-mode., Stefan Monnier, 2020/12/14
- [elpa] new-master deda3ae 032/128: Sync with enwc/master, Stefan Monnier, 2020/12/14
- [elpa] new-master 9590444 027/128: Thanks go to Lars Andersen., Stefan Monnier, 2020/12/14
- [elpa] new-master aa5dc11 044/128: update link in README, Stefan Monnier, 2020/12/14
- [elpa] new-master e9be6a4 055/128: Merge commit 'aecfbcbc10cf03ec94062ac3e590f8118e5a0434', Stefan Monnier, 2020/12/14
- [elpa] new-master 6cafef1 054/128: bump version to 0.1.1, Stefan Monnier, 2020/12/14
- [elpa] new-master baea9b9 059/128: * wcheck-mode: New package., Stefan Monnier, 2020/12/14
- [elpa] new-master ba3901a 048/128: more tutorial, Stefan Monnier, 2020/12/14
- [elpa] new-master bc0d691 049/128: Merge the two README. Update copyright_exceptions.,
Stefan Monnier <=
- [elpa] new-master 49bca02 065/128: Use GPL3, Stefan Monnier, 2020/12/14
- [elpa] new-master 2beb505 068/128: Add 'packages/load-relative/' from commit '15ffaa9ebf1b7bbfcc307d1716eec135253b3b8d', Stefan Monnier, 2020/12/14
- [elpa] new-master d2d8dd0 080/128: Better generated HTML pages, Stefan Monnier, 2020/12/14
- [elpa] new-master 794fc1a 078/128: * COPYING: New file, fix #27., Stefan Monnier, 2020/12/14
- [elpa] new-master da496fc 070/128: Merge commit '7fe5510edce15f5733552bb4d9de4f5ab1e0de76', Stefan Monnier, 2020/12/14
- [elpa] new-master 2b4f166 084/128: Merge commit 'cce1d8b50b1ceccb80c20398cd659db3a6348aac' as 'packages/gnome-c-style', Stefan Monnier, 2020/12/14
- [elpa] new-master 797f5f7 077/128: README: Fix typos., Stefan Monnier, 2020/12/14
- [elpa] new-master c7dc876 088/128: Initial commit., Stefan Monnier, 2020/12/14
- [elpa] new-master 07174b2 087/128: Fix a typo in the readme, Stefan Monnier, 2020/12/14
- [elpa] new-master 64a0b94 098/128: Add 'packages/org-edna/' from commit 'ce425a365cc305142a6ec7ec95ebe5fd636100e3', Stefan Monnier, 2020/12/14