[nongnu] elpa-admin 2307841 196/439: * README: Expand instructions

[Philip Kaludercic]

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: