Re: feature/package+vc 04c4c578c7 3/4: Allow for packages to be installed directly from VCS

[Philip Kaludercic <philipk@posteo.net>]

Philip Kaludercic <philipk@posteo.net> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>> Yes, but the list of packages that are proposed are just a subset of the
>>> packages that are already in the archive?
>>
>> Oh, I thought they were packages that weren't part of the archive
>> already.  But in that case, I think it's fine.
>
> Good.  So if there is a principal interest in the feature, I would start
> writing the documentation.

I've pushed the documentation to feature/package+vc but forgot to ping
this thread.  For the sake of convenience, and to recapitulate the new
features, this is what it would look like:

--8<---------------cut here---------------start------------->8---
@node Package from Source
@section Package from Source
@cindex package source vcs git @c "git" is not technically correct
                               @c but it is a popular term

  By default @code{package-install} will download a Tarball from a
package archive and install the files therein contained.  Most of the
time this is just what you want.  One exception is when you decide to
hack on the source code of a package, and would like to share these
changes with other users.  In that case you usually want to fetch and
work on the upstream source, so that you can prepare a usable patch.

@findex package-vc-install
  One way to do this is to use @code{package-vc-install}, to fetch the
source code for a package directly from source.  The command will also
automatically ensure that all files are byte-compiled and auto-loaded,
just like with a regular package.  From this point on the package can
be regarded just like any other package, that can be updated (using
@code{package-update}), deleted (using @code{package-delete}) and
viewed in the package listing.

@findex package-contact-maintainer
@findex package-report-bug
@findex package-vc-prepare-patch
  With the source checkout, you might want to reproduce a bug against
the current development head or implement a new feature to scratch an
itch.  If the package metadata indicates that a maintainer can be
contacted via Email, you can use the commands
@code{package-contact-maintainer} to send them a message, or
@code{package-report-bug} to report a bug that will include all the
user options that you have customised.  Patches can be sent out using
@code{package-vc-prepare-patch}, that makes use of
@code{vc-prepare-patch} under the hold (@pxref{Preparing Patches}).

@findex package-vc-link-directory
@findex package-vc-refresh
  If you maintain your own packages you might want to use a local
checkout instead of cloning a remote repository.  This can be done
using @code{package-vc-link-directory}, that creates a symbolic link
from the package directory (@pxref{Package Files}) to your checkout
and initialises the code.  Note that if changes are made such as
adding autoloads, you should use @code{package-vc-refresh} to repeat
the initialisation.
--8<---------------cut here---------------end--------------->8---