From 89981d99f8c305841b2dfa78689d7c0426e454e8 Mon Sep 17 00:00:00 2001 From: Artur Malabarba Date: Wed, 14 Oct 2015 11:54:27 +0100 Subject: [PATCH] * 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 ce7fd14e6..f3fd32b34 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//.el. -The file needs to follow the usual coding conventions (most importantly -start with ";;; --- ") and have a "Version:" and -"Maintainer:" pseudo-header. +The file needs to follow the usual coding conventions (most +importantly start with ";;; --- ") 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/. + +It needs to have a file named packages//.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.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 .el file - in the format used for single-file packages: the -pkg.el file is +- Multi-file packages put the package metadata in the main .el file + in the format used for single-file packages: the -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/' 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/' 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/ + +Later, when you make some changes to the remote and want to publish +them here, simply do: + + git subtree pull --prefix=packages/ - git subtree add --prefix=packages/ +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 +- is the remote's url. If you've previously used "git + remote add", then this can be the remote's name. +- is the branch you want to pull (probably "master"). - git subtree pull --prefix=packages/ +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/' branch in the `elpa' repository. +`externals/' branch in the `elpa' repository. You can check out all the external packages into the `packages' directory with the command: -- 2.39.2