branch: elpa-admin
commit 38e81a84e87a409518b9b6511fbef16cf359f76e
Author: Stefan Monnier <monn...@iro.umontreal.ca>
Commit: Stefan Monnier <monn...@iro.umontreal.ca>
* README: Recommend "externals" and add some recommendations
(Coding Style): New subsection.
(External branches): Recommend "externals" over "subtree".
(Externals): Use `git worktree`.
---
README | 41 ++++++++++++++++++++++++++---------------
1 file changed, 26 insertions(+), 15 deletions(-)
diff --git a/README b/README
index 4318bad..8c85210 100644
--- a/README
+++ b/README
@@ -44,7 +44,7 @@ release the new code.
** To add a package: (submission, submit)
-Adding a basic package is very simple. There are thorough
+Adding a basic package is very simple. There are thorough
instructions below, but the gist of it is that you:
1. Notify emacs-de...@gnu.org.
@@ -98,7 +98,9 @@ For some examples, see
*** Add a multi-file package as a directory, packages/<pkg-name>.
It needs to have a file named packages/<pkg-name>/<pkg-name>.el which follows
the
-same rules as above.
+same rules as above. Note that if your package is large, we recommend you
+add it as an "external" into its own branch, see below discussion of
+external branches.
It additionally follows the same guidelines described in
(info "(elisp) Multi-file Packages")
@@ -149,25 +151,34 @@ and the web-pages from this source code:
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).
+** Coding style
+
+We do not impose a particular coding style on GNU ELPA packages, but of
+course we recommend the coding style used in Emacs's own source code.
+Furthermore we recommend the following:
+- Use `cl-lib` rather than `cl` if it all possible.
+- Use lexical-binding if it all possible.
+- Try and fix the warnings emitted when compiling the package with a recent
Emacs.
+
** External branches
The above instructions are enough to add regular packages, those that
-are maintained primarily here in the repository. The instructions
-below are for those maintainers who prefer to use a dedicated
-repository or branch for the package.
+are maintained primarily here in the repository and are fairly small.
+The instructions below are for those maintainers who prefer to use a dedicated
+repository or branch for the package or for largish packages.
-There are two ways to do that: subtrees and externals.
+There are two ways to do that: "subtrees" and "externals".
Either way, such packages should always be listed in the
`externals-list' file.
-In both cases, a copy of the code is kept in the `elpa' repository
+In both cases, a copy of the code is kept in the `elpa.git' repository
(not necessarily in the master branch) and should be sync'd with the
upstream every once in a while. This copy may include local changes,
although these should be kept to a minimum.
-If know you don't want a local package, but don't know which of these
-two options you prefer, then use a subtree.
+If you don't know which of these two options you prefer, then use an
+"external" (and also if your package is large).
*** Subtrees
@@ -213,14 +224,14 @@ help and only gets in the way.
*** Externals
-In the `external' case, the copy of the code is not kept here but in the
-`externals/<pkg-name>' branch in the `elpa' repository.
+In the `external' case, the copy of the code is not kept in `master` but in the
+`externals/<pkg-name>' branch in the `elpa.git' repository.
-To add a new externals package, first add this `elpa' repository as a
+To add a new externals package, first add this `elpa.git' repository as a
new remote in your existing repository. Then push a local branch to a
-new remote branch in `elpa', named externals/<pkgname>. For example:
+new remote branch in `elpa.git', named externals/<pkgname>. For example:
- git push elpa master:externals/<pkgname>
+ git push elpa <mybranch>:externals/<pkgname>
Then edit the `externals-list' file as mentioned above, and push that
change to `elpa's master branch.
@@ -234,7 +245,7 @@ You can check out a specific external PACKAGE into the
`packages'
directory with these commands:
cd packages
- git clone --reference .. --single-branch --branch externals/PACKAGE $(git
config remote.origin.url) PACKAGE
+ git worktree add PACKAGE externals/PACKAGE
If you already have a packages/PACKAGE directory with a previous
checkout, you can update it like this:
