[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] new-master c778396 108/128: * README: Recommend "externals" and a
From: |
Stefan Monnier |
Subject: |
[elpa] new-master c778396 108/128: * README: Recommend "externals" and add some recommendations |
Date: |
Mon, 14 Dec 2020 15:39:42 -0500 (EST) |
branch: new-master
commit c778396366d9fe19e3c5da311d5482ec6279f27c
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@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-devel@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:
- [elpa] new-master c1a9997 085/128: Merge commit '1054ea1bc5b07a1438a18c1b33f4266b28ff9d77', (continued)
- [elpa] new-master c1a9997 085/128: Merge commit '1054ea1bc5b07a1438a18c1b33f4266b28ff9d77', Stefan Monnier, 2020/12/14
- [elpa] new-master 4041990 081/128: * README: Add submission guideline, Stefan Monnier, 2020/12/14
- [elpa] new-master b586c0e 076/128: * README: Revert change about package.el headers, Stefan Monnier, 2020/12/14
- [elpa] new-master 6a044b5 091/128: Merge branch 'master' into new-website, Stefan Monnier, 2020/12/14
- [elpa] new-master 2e8f5ad 089/128: Updated v1.05 for Savannah and GNU ELPA, Stefan Monnier, 2020/12/14
- [elpa] new-master bf0be51 092/128: Website footer improvement, Stefan Monnier, 2020/12/14
- [elpa] new-master 82fbc4f 096/128: Added copyright and licensing information to all files, Stefan Monnier, 2020/12/14
- [elpa] new-master 55116c1 099/128: Add explicit instructions for new external packages, Stefan Monnier, 2020/12/14
- [elpa] new-master e8a6d9d 103/128: * README: Clarify the right fix for check_copyrights failure, Stefan Monnier, 2020/12/14
- [elpa] new-master 80420ec 105/128: * README: Don't clone a clone., Stefan Monnier, 2020/12/14
- [elpa] new-master c778396 108/128: * README: Recommend "externals" and add some recommendations,
Stefan Monnier <=
- [elpa] new-master c1d5f54 101/128: Add 'packages/paced/' from commit '223809ea68c8d86aef2b61a946d61497125ba250', Stefan Monnier, 2020/12/14
- [elpa] new-master 347030d 114/128: Add contact details to front page (Bug#34460), Stefan Monnier, 2020/12/14
- [elpa] new-master 397c236 116/128: Update copyright year in index.html, Stefan Monnier, 2020/12/14
- [elpa] new-master 288237d 120/128: * README: Clarify deployment process., Stefan Monnier, 2020/12/14
- [elpa] new-master 8668586 119/128: ; Update copyright year, Stefan Monnier, 2020/12/14
- [elpa] new-master 6b83e5e 118/128: * html/index.html: Minor improvement to wording., Stefan Monnier, 2020/12/14
- [elpa] new-master 56ffb2c 123/128: * README: Fix typos., Stefan Monnier, 2020/12/14
- [elpa] new-master 7e40b0b 125/128: * COPYING: Update URLs., Stefan Monnier, 2020/12/14
- [elpa] new-master ee03829 127/128: Finalize the new master branch, Stefan Monnier, 2020/12/14
- [elpa] new-master 861a8c2 038/128: initial commit, echo server working, Stefan Monnier, 2020/12/14