[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa-admin 38e81a8 300/439: * README: Recommend "externals" and
From: |
Philip Kaludercic |
Subject: |
[nongnu] elpa-admin 38e81a8 300/439: * README: Recommend "externals" and add some recommendations |
Date: |
Sun, 17 Oct 2021 15:48:24 -0400 (EDT) |
branch: elpa-admin
commit 38e81a84e87a409518b9b6511fbef16cf359f76e
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:
- [nongnu] elpa-admin e2b9274 266/439: [admin int] Simplify ‘archive--write-pkg-file’ calling convention., (continued)
- [nongnu] elpa-admin e2b9274 266/439: [admin int] Simplify ‘archive--write-pkg-file’ calling convention., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 5250761 270/439: * admin/archive-contents.el: Use `git worktree` for externals, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 19a11bc 278/439: Add explicit instructions for new external packages, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin d4f5903 284/439: * README: Clarify the right fix for check_copyrights failure, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin a5d74b0 291/439: * packages/yasnippet: Merge version 0.13.0 from upstream., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 63888f3 292/439: Warn about transfer.fsckObjects, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 0a995ba 296/439: * admin/archive-contents.el (archive--insert-repolinks): Fix further, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 02d8431 297/439: * admin/archive-contents.el (archive--insert-repolinks): Fix further yet, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin b5760e3 298/439: * admin/archive-contents.el (archive--insert-repolinks): Getting there, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin a216465 299/439: * admin/archive-contents.el (archive--insert-repolinks): Whoops, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 38e81a8 300/439: * README: Recommend "externals" and add some recommendations,
Philip Kaludercic <=
- [nongnu] elpa-admin 655d2e7 305/439: Update packages/ack from upstream, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin f25cda3 303/439: * GNUmakefile (%.elc): Use load-prefer-newer, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin f85cb8d 302/439: * README (PACKAGES/Externals): Clarify use, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin a71a25a 306/439: Update packages/darkroom from upstream, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 0c6fbe0 307/439: Update packages/ack from upstream, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin c943660 310/439: Merge commit '98405112baa5ce2a118d1c65184c005d8ddaa1a9', Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 973ee9d 314/439: Merge branch 'master' of git.sv.gnu.org:/srv/git/emacs/elpa, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 9822a67 315/439: README: Mention that the copyright in ELPA is with the FSF, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 14797ea 319/439: * admin/archive-contents.el: Adjust last change, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 9c8cf14 320/439: * admin/archive-contents.el (archive-refresh-pkg-file): Resurrect., Philip Kaludercic, 2021/10/17