worrying about the unstable code making it to GNU ELPA, and simply update
the "version" when you want to release the new code.
-* External branches:
-
-Some packages have an external upstream branch.
-You should ideally be able to "bzr merge <URL>" from them, and it often
-works, but it generally requires some hand-holding to set it up.
-More specifically, the first "bzr merge" (ideally done when installing the
-package into `elpa') needs to be a "bzr join" since there's no
-common ancestor. Worse, "bzr join" doesn't work so well with bzr-git, so
-you need to do a bit of gymnastics:
-
- git clone <giturl> # Done because bzr-git works better locally
- bzr branch <localgit> tmp
- cd tmp
- bzr mkdir .newroot
- bzr mv * .newroot/
- ... maybe other bzr mv .<blabla> .newroot/ ...
- bzr split .newroot
- mv .newroot .../elpa/packages/<package>
- cd .../elpa/packages/
- bzr join <package>
-
+* Format
+
+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 can put the package metadata in the main <pkg>.el file
+ in the format used for single-file packages, in which case the script
+ will auto-generate the <pkg>-pkg.el file.
+- the "URL:" header (or :url property) can be used to specify the home page
+ of the package, if it's maintained externally.
+- A "News:" section (or "NEWS" file) can/should be used to list the
+ user-visible changes of each version.
+- The "Package-Type: simple" header can be used to force the creation
+ of a single-file package even when there are several Elisp files in
+ the source (the other files will simply be ignored).
+
+* 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.
+
+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 the `subtree' case, the copy of the code is kept here in the
+corresponding `packages/<pkg>' directory. You should be able to "git
+merge -s subtree" from the upstream branch.
+
+In the `external' case, the copy of the code is not kept here but in the
+`externals/<pkg>' branch in the `elpa' repository.
+You can check out all the external packages into the `packages' directory
+with the command:
+
+ make externals