emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[ELPA] Instructions on adding external packages


From: Artur Malabarba
Subject: [ELPA] Instructions on adding external packages
Date: Wed, 14 Oct 2015 13:23:02 +0100

Dear all,

Since I understand the previous instructions were quite concise, I've
expanded Elpa's readme to better explain how to create an Elpa package
as a subtree.

I'm posting the new explanation here because of a very recent thread
asking about this specific subject. Also, I hope someone familiar with
the external branch workflow can expand on those instructions as well.

Best,
Artur Malabarba

-----

** External branches

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
(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 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>

On older git versions "git subtree" might not be available.  You can
try "git merge -s subtree", or just update git.

- <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").

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.

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!!

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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]