emacs-elpa-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[elpa] master 72e71c0: * README: Recommend "externals" and add some reco


From: Stefan Monnier
Subject: [elpa] master 72e71c0: * README: Recommend "externals" and add some recommendations
Date: Tue, 4 Dec 2018 13:07:45 -0500 (EST)

branch: master
commit 72e71c0a70c3e505225e5f8fc090b6ce0945ebe9
Author: Stefan Monnier <address@hidden>
Commit: Stefan Monnier <address@hidden>

    * 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 address@hidden
@@ -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:



reply via email to

[Prev in Thread] Current Thread [Next in Thread]