[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa-admin 2307841 196/439: * README: Expand instructions
From: |
Philip Kaludercic |
Subject: |
[nongnu] elpa-admin 2307841 196/439: * README: Expand instructions |
Date: |
Sun, 17 Oct 2021 15:48:00 -0400 (EDT) |
branch: elpa-admin
commit 2307841bfb4ff76b3112ad90dd63cf441a2c3c0e
Author: Artur Malabarba <bruce.connor.am@gmail.com>
Commit: Artur Malabarba <bruce.connor.am@gmail.com>
* README: Expand instructions
Reference the info manual when explaining package formats.
Improve the explanation of external packages and the instructions
on subtrees.
---
README | 91 +++++++++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 65 insertions(+), 26 deletions(-)
diff --git a/README b/README
index ce7fd14..f3fd32b 100644
--- a/README
+++ b/README
@@ -36,16 +36,26 @@ release the new code.
** To add a package:
-*** Add a simple (1-file) package as packages/NAME/NAME.el.
+*** Add a simple (1-file) package as packages/<pkg-name>/<pkg-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.
+The file needs to follow the usual coding conventions (most
+importantly start with ";;; <file> --- <description>") as well as the
+package headers required by package.el (see the "Format" subsection
+below).
-*** Add a multi-file package as a directory, packages/NAME.
+For some examples, see
+ (info "(elisp) Simple Packages")
-It needs to have a file named packages/NAME/NAME.el which follows the same
-rules as above.
+*** 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.
+
+It additionally follows the same guidelines described in
+ (info "(elisp) Multi-file Packages")
+with the exception that it is not a tar package (it's a plain
+directory) and it must not contain a "<pkg-name>-pkg.el" file (this
+will be created for you).
*** Commit your changes the usual way ("git add", "git commit", etc).
@@ -60,8 +70,8 @@ header changes.
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
+- Multi-file packages put the package metadata in the main <pkg-name>.el file
+ in the format used for single-file packages: the <pkg-name>-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
@@ -78,38 +88,67 @@ and the web-pages from this source code:
** 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.
+The easiest way to maintain and develop GNU Elpa packages is to just
+edit them right here (in elpa.git). However, some maintainers may
+prefer to use a dedicated repository or branch for the package. There
+are two ways to do that: subtrees and externals.
+
+Such packages should be listed in the `externals-list' file.
-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 both cases, a copy of the code is kept in the `elpa' 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 prefere, then use a subtree.
*** Subtrees
-In the `subtree' case, the copy of the code is kept here in the
-corresponding `packages/<pkg>' directory. You should be able to use:
+In the `subtree' case, the copy of the code is kept here in the master
+branch, inside its corresponding `packages/<pkg-name>' directory just
+as if it were a local package.
+
+In fact, a subtree package is essentially indistinguishable from a
+local package. The only difference is that, instead of developing it
+here, you do it in some remote repository and pull in the changes.
+
+Instead of manually creating the directory, you should be able to use:
+
+ git subtree add --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
+
+Later, when you make some changes to the remote and want to publish
+them here, simply do:
+
+ git subtree pull --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
- git subtree add --prefix=packages/<pkg> <remote-repo> <remote-branch>
+On older git versions "git subtree" might not be available. You can
+try "git merge -s subtree", or just update git.
-to add your package from some remote repo, and then
+- <remote-repo> is the remote's url. If you've previously used "git
+ remote add", then this can be the remote's name.
+- <remote-branch> is the branch you want to pull (probably "master").
- git subtree pull --prefix=packages/<pkg> <remote-repo> <remote-branch>
+If you want the local code to be slightly different from the remote,
+simply commit further changes to it here. Of course, this may trigger
+merge conflicts when you do a "subtree pull" in the future, so it's
+best to avoid these local changes.
-whenever you want to update it. On older git versions you can try "git
-merge -s subtree".
+If someone makes changes to your package on here elpa.git and you want
+to push them to your remote, it's easiest to just copy these changes
+over to the remote repo. Trying to push a subtree with git is likely
+to induce headache.
-When you're adding and pulling, DO NOT --SQUASH!!
+**** When you're adding and pulling, DO NOT --SQUASH!!
Don't worry about flooding elpa.git's commit log with your package's
-commit messages. Your package is part of elpa.git. Squashing
-doesn't help and only gets in the way.
+commit messages. Your package is part of elpa.git. Squashing doesn't
+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>' branch in the `elpa' repository.
+`externals/<pkg-name>' branch in the `elpa' repository.
You can check out all the external packages into the `packages' directory
with the command:
- [nongnu] elpa-admin 84f4eb7 153/439: * wcheck-mode: New package., (continued)
- [nongnu] elpa-admin 84f4eb7 153/439: * wcheck-mode: New package., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin f08292f 152/439: * admin/archive-contents.el: Don't stop at the first incorrect version string., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin faf7826 158/439: publish ada-mode 5.1.6, wisi 1.0.6, new package ada-ref-man, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 6ab28f9 156/439: drop Emacs dependency to 24.3, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 79849d3 167/439: Add 'packages/realgud/' from commit 'd811316e6a0f4eeee8a1347f504c196c86baa2cb', Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 779c1d2 165/439: Add 'packages/loc-changes/' from commit '8447baff7cb4839ef8d1d747a14e5da85d0cee5b', Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 345dc39 189/439: * GNUmakefile: Use LC_ALL rather than LANG, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin d079afa 187/439: Squashed 'packages/pinentry/' changes from 075deb6..b3a45a5, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 97cad46 171/439: Merge commit '3fa56d7925d5b24c5cd11c61bd6b3235e753a055', Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 4a3a7c2 193/439: * README: Improve subtree instructions, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 2307841 196/439: * README: Expand instructions,
Philip Kaludercic <=
- [nongnu] elpa-admin 842d54c 056/439: * admin/archive-contents.el (batch-make-site-dir, archive--write-pkg-file): New functions., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 3afe3ac 060/439: Use org-mode markup in README and rename it to README.org, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 49382d4 067/439: Some tweaks to README, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 49fce77 070/439: Rename README to README.rst, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 303f2c9 075/439: * admin/archive-contents.el (batch-make-site-package): New function., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin febff3e 079/439: Make README more up-to-date, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 6ba7e63 077/439: Try to preserve timestamps. Fix ChangeLog generation., Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin bffc4a6 090/439: Don't create local branches, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 480283a 089/439: Move check_copyright to the makefile, Philip Kaludercic, 2021/10/17
- [nongnu] elpa-admin 81a6a01 088/439: Fix up scripts to build archive from Git, Philip Kaludercic, 2021/10/17