ELPA commit freeze

ELPA commit freeze

[Stefan Monnier]

I think I'm about ready to switch ELPA to use Git.  So please, refrain
to commit to the `elpa' branch until I announce the availability of the
new Git repository.

If someone can provide a better Git branch than Andreas's on repo.or.cz,
speak now or forever hold your peace.


        Stef

Re: ELPA commit freeze

[Andreas Schwab]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> If someone can provide a better Git branch than Andreas's on repo.or.cz,
> speak now or forever hold your peace.

I have updated it with the latest commit from the bzr elpa branch.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: ELPA commit freeze

[Dmitry Gutov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I think I'm about ready to switch ELPA to use Git.  So please, refrain
> to commit to the `elpa' branch until I announce the availability of the
> new Git repository.
>
> If someone can provide a better Git branch than Andreas's on repo.or.cz,
> speak now or forever hold your peace.

Like I said, I'm quite willing to make a repo with packages imported as
subtrees from upstream repositories. Without a hosting, though.

The reason I haven't done it yet, is, like I mentioned, many upstream
repos differ quite a bit from their conterparts in packages/, and as a
result those packages will probably fail to build.

Re: ELPA commit freeze

[Stefan Monnier]

>> If someone can provide a better Git branch than Andreas's on repo.or.cz,
>> speak now or forever hold your peace.
> I have updated it with the latest commit from the bzr elpa branch.

Thank you, I've moved the Bzr branch to old-branches.  The new one
should be in place later today,


        Stefan

Re: ELPA commit freeze

[Stefan Monnier]

> Like I said, I'm quite willing to make a repo with packages imported as
> subtrees from upstream repositories. Without a hosting, though.

I'll definitely add those, don't worry.  "Better" would imply redoing
the history piece by piece, "git merge"ing from the external at the
point where the Bzr code had a merge.


        Stefan

Re: ELPA commit freeze

[Xue Fuqiao]

On Wed, Aug 14, 2013 at 10:42 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:
>>> If someone can provide a better Git branch than Andreas's on repo.or.cz,
>>> speak now or forever hold your peace.
>> I have updated it with the latest commit from the bzr elpa branch.
>
> Thank you, I've moved the Bzr branch to old-branches.  The new one
> should be in place later today,

Thank you, and don't forget to update admin/notes/elpa.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: ELPA commit freeze

[Stefan Monnier]

OK, ELPA is open for business again.  It has moved to:

   git://bzr.sv.gnu.org/emacs/elpa

for anonymous read-only access, and

   git+ssh://bzr.sv.gnu.org/srv/git/emacs/elpa

for read/write access.
   
The metadata currently includes the merge history for ack, coffee-mode,
company, eldoc-eval, f90-interface-browser, ggtags, ioccur, js2-mode
and websocket.

So bringing in fresh changes from an external Git branch should be as
simple as

   git merge -s subtree coffee-mode/master

I should have some cron job doing such merges automatically, but it's
not ready yet.


        Stefan

Re: ELPA commit freeze

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 15 Aug 2013 00:18:54 -0400
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> OK, ELPA is open for business again.  It has moved to:
> 
>    git://bzr.sv.gnu.org/emacs/elpa
> 
> for anonymous read-only access, and
> 
>    git+ssh://bzr.sv.gnu.org/srv/git/emacs/elpa
> 
> for read/write access.

Git rocks, as usual: the latter doesn't work for me on MS-Windows, I
get this:

  $ git clone git+ssh://bzr.sv.gnu.org/srv/git/emacs/elpa
  Cloning into 'elpa'...
  fatal: Could not read from remote repository.

  Please make sure you have the correct access rights
  and the repository exists.

(I do succeed to pull and push from/to the GNU Make repository on
Savannah, and also from Gawk and Gnulib, so my git setup should be
OK.)

I eventually succeeded using this URL instead:

  eliz@bzr.savannah.gnu.org:/srv/git/emacs/elpa.git

(Isn't it terribly confusing that a git repo is on a server whose name
begins with "bzr"?)

Re: ELPA commit freeze

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>   $ git clone git+ssh://bzr.sv.gnu.org/srv/git/emacs/elpa

Worksforme.  Do you have "Host *.sv.gnu.org User eliz" in your
.ssh/config?

> (Isn't it terribly confusing that a git repo is on a server whose name
> begins with "bzr"?)

Just s/bzr/git/ (they are all the same anyway).

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: ELPA commit freeze

[Eli Zaretskii]

> From: Andreas Schwab <schwab@suse.de>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> Date: Thu, 15 Aug 2013 17:29:34 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >   $ git clone git+ssh://bzr.sv.gnu.org/srv/git/emacs/elpa
> 
> Worksforme.

It also worked for me on fencepost.gnu.org, a GNU/Linux machine
(sorry, forgot to tell).  Go figure.

> Do you have "Host *.sv.gnu.org User eliz" in your
> .ssh/config?

I have its PuTTY equivalent, the auto-login username is set to "eliz".
(There's no ~/.ssh/config in PuTTY.)  Maybe git needs something else
in its own config files?

> > (Isn't it terribly confusing that a git repo is on a server whose name
> > begins with "bzr"?)
> 
> Just s/bzr/git/ (they are all the same anyway).

Yes.

Thanks.

Re: ELPA commit freeze

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> Maybe git needs something else in its own config files?

No, it just calls ssh to do the remote work.  Try GIT_TRACE=1 to see
what it calls.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: ELPA commit freeze

[Eli Zaretskii]

> From: Andreas Schwab <schwab@suse.de>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Thu, 15 Aug 2013 18:04:02 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Maybe git needs something else in its own config files?
> 
> No, it just calls ssh to do the remote work.  Try GIT_TRACE=1 to see
> what it calls.

  $ GIT_TRACE=1 git clone git+ssh://bzr.savannah.gnu.org/srv/git/emacs/elpa
  trace: built-in: git 'clone' 'git+ssh://bzr.savannah.gnu.org/srv/git/emacs/elpa'

  Cloning into 'elpa'...
  trace: run_command: 'D:\usr\putty\plink.exe' '-batch' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''
  fatal: Could not read from remote repository.

  Please make sure you have the correct access rights
  and the repository exists.

Re: ELPA commit freeze

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>   trace: run_command: 'D:\usr\putty\plink.exe' '-batch' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''

And what does it say without -batch?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: ELPA commit freeze

[Stefan Monnier]

> (Isn't it terribly confusing that a git repo is on a server whose name
> begins with "bzr"?)

Sorry, that was just a typo.


        Stefan

Re: ELPA commit freeze

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Thu, 15 Aug 2013 18:42:43 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >   trace: run_command: 'D:\usr\putty\plink.exe' '-batch' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''
> 
> And what does it say without -batch?

It asks for login name (even though the PuTTY session includes a user
name, and if I connect directly via PuTTY, PuTTY doesn't ask for a
user name).  After I type the user name (see below), it shows some
data you see below, and hangs.

  $ 'D:\usr\putty\plink.exe' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''
  login as: eliz
  009b4b34f9d0c918c452cfc0cd4605f3e6d6f2eab50f HEAD multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag multi_ack_detailed
  00497a022dc33920a19c05e7785eda8d9e6e9dcf131d refs/heads/externals/dismal
  003f4b34f9d0c918c452cfc0cd4605f3e6d6f2eab50f refs/heads/master
  0000

Re: ELPA commit freeze

[Eli Zaretskii]

> Date: Thu, 15 Aug 2013 20:06:01 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> > From: Andreas Schwab <schwab@linux-m68k.org>
> > Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> > Date: Thu, 15 Aug 2013 18:42:43 +0200
> > 
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> > >   trace: run_command: 'D:\usr\putty\plink.exe' '-batch' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''
> > 
> > And what does it say without -batch?
> 
> It asks for login name (even though the PuTTY session includes a user
> name, and if I connect directly via PuTTY, PuTTY doesn't ask for a
> user name).  After I type the user name (see below), it shows some
> data you see below, and hangs.
> 
>   $ 'D:\usr\putty\plink.exe' 'bzr.savannah.gnu.org' 'git-upload-pack '\''/srv/git/emacs/elpa'\'''
>   login as: eliz
>   009b4b34f9d0c918c452cfc0cd4605f3e6d6f2eab50f HEAD multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag multi_ack_detailed
>   00497a022dc33920a19c05e7785eda8d9e6e9dcf131d refs/heads/externals/dismal
>   003f4b34f9d0c918c452cfc0cd4605f3e6d6f2eab50f refs/heads/master
>   0000

I found the reason: it was indeed the lack of username, and that was
because the PuTTY session was not called by the exact name of the
server, but by some variation thereof.

Thanks a lot for you help.

Re: ELPA commit freeze

[Glenn Morris]

Stefan Monnier wrote:

> OK, ELPA is open for business again.  It has moved to:
>
>    git://bzr.sv.gnu.org/emacs/elpa

So we have

git.savannah.gnu.org/emacs.git

which is a read-only mirror of the bzr repo, and is what you get if you
click on the "Source Code" "Use Git" link on

http://savannah.gnu.org/projects/emacs/

and also

git.savannah.gnu.org/emacs

which is a real repo with the elpa branch, that cannot be discovered
from http://savannah.gnu.org/projects/emacs/ AFAICS?

That's a bit confusing...

Re: ELPA commit freeze

[Stefan Monnier]

> That's a bit confusing...

Yup.  If someone knows how to tweak Savannah so that it includes
a pointer to the elpa repository, I'd be happy to hear it.


        Stefan

Re: ELPA commit freeze

[Glenn Morris]

Stefan Monnier wrote:

> If someone knows how to tweak Savannah so that it includes a pointer
> to the elpa repository, I'd be happy to hear it.

I'm guessing that you can edit the text on

  http://savannah.gnu.org/projects/emacs/

that says "For information about Emacs... read these instructions" via
your Savannah account page somehow. You could mention elpa there
(probably safe to remove the sentence about CVS while you are it).

Re: ELPA commit freeze

[Stefan Monnier]

>> If someone knows how to tweak Savannah so that it includes a pointer
>> to the elpa repository, I'd be happy to hear it.
> I'm guessing that you can edit the text on
>   http://savannah.gnu.org/projects/emacs/
> that says "For information about Emacs... read these instructions" via
> your Savannah account page somehow. You could mention elpa there
> (probably safe to remove the sentence about CVS while you are it).

Indeed, I added a pointer to the Git repository of ELPA in there.
Better than nothing,


        Stefan

Re: ELPA commit freeze

[Glenn Morris]

Stefan Monnier wrote:

> Indeed, I added a pointer to the Git repository of ELPA in there.
> Better than nothing,

Yeah. AFAIK the "use git" etc links are auto-generated by Savannah and
cannot be customized.

Re: ELPA commit freeze

[Dmitry Gutov]

On 14.08.2013 17:43, Stefan Monnier wrote:
>> Like I said, I'm quite willing to make a repo with packages imported as
>> subtrees from upstream repositories. Without a hosting, though.
>
> I'll definitely add those, don't worry.  "Better" would imply redoing
> the history piece by piece, "git merge"ing from the external at the
> point where the Bzr code had a merge.

I've just tried 'git subtree push --prefix=packages/js2-mode <upstream 
repo>', and it didn't work, saying because the push wouldn't be 
fast-forward (which it should be).

Doing 'git subtree split --prefix=<...> -b js2-mode && git co js2-mode' 
showed the history from the old elpa branch, plus your last two commits 
that touched this dir.

Similarly, plain 'git log -- packages/js2-mode' shows the old history, 
and does not include the commits from the upstream repo.

Then I did 'git subtree pull --prefix=packages/js2-mode <upstream>', it 
succeeded, 'git subtree push' still didn't work after that, but 'git 
subtree split ... -b js2-mode' followed by 'git co js2-mode' and 'git 
push' succeeded, pushing the whole damn elpa history to 
git@github.com:mooz/js2-mode.git.

Clearly, there's something wrong with the current configuration.

Further, I'm still not receiving notifications for commits made in 
elpa/packages/js2-mode. Should I explicitly add a "Maintainer:" header?

Re: ELPA commit freeze

[Stefan Monnier]

> Similarly, plain 'git log -- packages/js2-mode' shows the old history, and
> does not include the commits from the upstream repo.

I have added the metadata of the branches I know, but have not (yet)
updated those packages to be in sync with the latest commit of
those branches.

> Then I did 'git subtree pull --prefix=packages/js2-mode <upstream>', it
> succeeded, 'git subtree push' still didn't work after that, but 'git subtree
> split ... -b js2-mode' followed by 'git co js2-mode' and 'git push'
> succeeded, pushing the whole damn elpa history to
> git@github.com:mooz/js2-mode.git.

I'd suggest you ask the "git subtree" guy why one would work while the
other didn't and why the whole elpa history got carried over to the
split tree.

> Further, I'm still not receiving notifications for commits made in
> elpa/packages/js2-mode. Should I explicitly add a "Maintainer:" header?

AFAIK noone committed to that branch (other than yourself, but the
email is not sent to the guy who did the push, since presumably he
knows about those changes already).


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 19.08.2013 05:39, Stefan Monnier wrote:
>> Similarly, plain 'git log -- packages/js2-mode' shows the old history, and
>> does not include the commits from the upstream repo.
>
> I have added the metadata of the branches I know, but have not (yet)
> updated those packages to be in sync with the latest commit of
> those branches.

I don't understand why you're talking about branches. I mean the 
packages/js2-mode directory. And yes, plain 'git log' shows its whole 
history (aside from a couple of latest commits), plus histories of other 
projects and ELPA itself.

But the history of packages/js2-mode directory, which should be (almost) 
identical with the upstream, isn't.

>> Then I did 'git subtree pull --prefix=packages/js2-mode <upstream>', it
>> succeeded, 'git subtree push' still didn't work after that, but 'git subtree
>> split ... -b js2-mode' followed by 'git co js2-mode' and 'git push'
>> succeeded, pushing the whole damn elpa history to
>> git@github.com:mooz/js2-mode.git.
>
> why the whole elpa history got carried over to the
> split tree.

The packages/js2-mode subtree history is wrong, so the wrong history got 
pushed. I could try to pose these questions to apenwarr, but we're 
dealing with a complex repository here, and the subtrees were not added 
the recommended way (AFAICT), so there's little motivation for him to 
answer.

>> Further, I'm still not receiving notifications for commits made in
>> elpa/packages/js2-mode. Should I explicitly add a "Maintainer:" header?
>
> AFAIK noone committed to that branch (other than yourself, but the
> email is not sent to the guy who did the push, since presumably he
> knows about those changes already).

You did. See 293db6e (Fix up copyrights and the checking code).

Re: ELPA commit freeze

[Stefan Monnier]

> The packages/js2-mode subtree history is wrong,

That's for sure: it pretends that all changes until the conversion to
Git happened directly in `elpa'.

> so the wrong history got pushed.

I'd expect this history to be "the true js2-mode history plus
a redundant copy of that history from the packages/js-2mode directory of
the Bzr branch".  Is that the case, or do you get "the true js-2mode
history plus the complete history of the whole elpa branch".

In the case of a "duplicate history", I think it's about as good as it's
going to get, because of the fact that the "subtree merge" was only made
at the end.  To get something better, we'd have to reconstruct the elpa
branch bit by bit, performing the merges as if they'd been done right
back when we added/updated all those externally maintained branches.

> You did. See 293db6e (Fix up copyrights and the checking code).

I think this was before I fixed the email-massaging scripts to adjust to
the new format.  I'll install one of my pending minor cleanups to the
js2-mode, so we can make sure it works.


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 20.08.2013 08:16, Stefan Monnier wrote:
>> The packages/js2-mode subtree history is wrong,
>
> That's for sure: it pretends that all changes until the conversion to
> Git happened directly in `elpa'.

Aside from that, git log -- packages/js2-mode doesn't show the commits 
from the upstream repo at all, only the merge commit. Can you explain that?
I remember that Bzr somehow omits histories of the merged branches (by 
default?), but 'git log' usually shows all commits that ended up in the 
current branch history.

>> so the wrong history got pushed.
>
> I'd expect this history to be "the true js2-mode history plus
> a redundant copy of that history from the packages/js-2mode directory of
> the Bzr branch".  Is that the case, or do you get "the true js-2mode
> history plus the complete history of the whole elpa branch".

Something along the lines of the latter. Here's what the push contained:

https://github.com/mooz/js2-mode/compare/2c27e3eb847c...05424b8245b6 
(the view is limited to 250 commits, but there were obviously more of 
them). 2c27e3eb847c is the current upstream HEAD.

And here's the report from the automatic build on Travis-CI: 
https://travis-ci.org/mooz/js2-mode/builds/10312341 After checking out 
the new version, it couldn't find .travis.yml, because the tree 
contained the whole elpa:

https://github.com/mooz/js2-mode/tree/05424b8245b62e95e2b376cbc63ed182cb1c8bee

> In the case of a "duplicate history", I think it's about as good as it's
> going to get, because of the fact that the "subtree merge" was only made
> at the end.

Do you think it's too late to rewrite history? Apparently, git 
filter-branch allows to remove a directory from history.

So we could check out the version before externals were introduces, 
erase all their respective directories, then apply all commits made to 
the "administrative" part of the tree, and then add the subtrees 
properly. Some cleanup commits would have to be re-applied, but there's 
not a lot of them.

If it's too late, I suppose we can live with that, but this way we a) 
give up an easy way to sync back, b) accept that we'll see each 
non-upstream commit in externally maintained packages's histories twice: 
once for when it's made, second after it's cherry-picked, committed to 
upstream and then merged back into elpa.

 > To get something better, we'd have to reconstruct the elpa
 > branch bit by bit, performing the merges as if they'd been done right
 > back when we added/updated all those externally maintained branches.

I'm not sure which merges you mean, but the way I described we'd give up 
older changes from before conversion to Git, that still aren't merged 
into upstreams now.

>> You did. See 293db6e (Fix up copyrights and the checking code).
>
> I think this was before I fixed the email-massaging scripts to adjust to
> the new format.  I'll install one of my pending minor cleanups to the
> js2-mode, so we can make sure it works.

Ok.

Re: ELPA commit freeze

[Andreas Schwab]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Aside from that, git log -- packages/js2-mode doesn't show the commits
> from the upstream repo at all, only the merge commit. Can you explain
> that?

There are no files matching packages/js2-mode in that branch.  That is a
peculiarity of the subtree merge: it renames all files with a prefix.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: ELPA commit freeze

[Dmitry Gutov]

On 20.08.2013 12:40, Andreas Schwab wrote:
>> Aside from that, git log -- packages/js2-mode doesn't show the commits
>> from the upstream repo at all, only the merge commit. Can you explain
>> that?
>
> There are no files matching packages/js2-mode in that branch.

Could you explain why you're calling the subdirectory (or subtree, to 
look at it another way) a branch?

> That is a peculiarity of the subtree merge: it renames all files with a prefix.

Thanks, that makes sense, I guess. I have checked, it's the same in my 
toy composite repository, and it works fine with 'git subtree push'.

Re: ELPA commit freeze

[Andreas Schwab]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Could you explain why you're calling the subdirectory (or subtree, to look
> at it another way) a branch?

I don't.  A branch is what a merge commit references.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: ELPA commit freeze

[Stefan Monnier]

> So we could check out the version before externals were introduces, erase
> all their respective directories, then apply all commits made to the
> "administrative" part of the tree, and then add the subtrees properly. Some
> cleanup commits would have to be re-applied, but there's not a lot of them.

We could try to do that.  I'm far form convinced it's worth the trouble.

> If it's too late, I suppose we can live with that, but this way we a) give
> up an easy way to sync back, b) accept that we'll see each non-upstream
> commit in externally maintained packages's histories twice: once for when
> it's made, second after it's cherry-picked, committed to upstream and then
> merged back into elpa.

Not that "git subtree push" also duplicates the commits.  It just
automates the process.  So, it's only a) that's lost.


        Stefan

Re: ELPA commit freeze

[Steinar Bang]

>>>>> Eli Zaretskii <eliz@gnu.org>:

>> Do you have "Host *.sv.gnu.org User eliz" in your
>> .ssh/config?

> I have its PuTTY equivalent, the auto-login username is set to "eliz".
> (There's no ~/.ssh/config in PuTTY.)  Maybe git needs something else
> in its own config files?

This is what I do (after having made sure that msysgit uses plink for
SSH support, in the install):
 - Generate a key in PuTTYgen, and save it to a ppk file
 - Copy the "Copy this blah blah" field in PuTTYgen and paste that into
   the ~/.ssh/authorized_keys file on the linux host (note: the
   autorized_keys file must not be writable by group or other)
 - Start PuTTY and:
  - Choose "Session"
  - In the "Hostname" field, put: linuxusername@bzr.sv.gnu.org
    (substitute your own user name for "linuxusername")
  - In the "Saved sessions" field, put bzr.sv.gnu.org
  - Choose "Connection->SSH->Auth"
  - In "Private key file for authentication", select the .ppk file
    created with PuTTYgen
  - Choose "Session"
  - Click on "Save"
  - Click on "Open" to test the SSH connection

If the SSH "Open" works without a hitch, the git clone command should as
well.  Even if the git server doesn't allow logins, you should do the
"Open" anyway, to get PuTTY's question about an unknown host key out of
the way.

Re: ELPA commit freeze

[Eli Zaretskii]

> From: Steinar Bang <sb@dod.no>
> Date: Tue, 20 Aug 2013 20:20:34 +0200
> 
> >>>>> Eli Zaretskii <eliz@gnu.org>:
> 
> >> Do you have "Host *.sv.gnu.org User eliz" in your
> >> .ssh/config?
> 
> > I have its PuTTY equivalent, the auto-login username is set to "eliz".
> > (There's no ~/.ssh/config in PuTTY.)  Maybe git needs something else
> > in its own config files?
> 
> This is what I do (after having made sure that msysgit uses plink for
> SSH support, in the install):

Thanks.  My PuTTY was set up a long time ago, and works ever since,
with many VCSs and servers.  I don't even remember anymore when did I
generate the keys which I use.  And my sessions all include the
auto-login username, so there's no need to use the user name in the
hostname field.

The problem in this case, as I wrote later, was that git invokes plink
with the name of the server, but in a way that causes plink interpret
that as the name of a session.  So for this to work, one needs to have
the session name be the exact copy of the server name.  No other VCS I
have ever worked with, which includes CVS, bzr, and SVN, imposes this
restriction on the PuTTY session names.

This was revealed by using GIT_TRACE=1, a trick suggested by Andreas,
which shows the command(s) that git invokes.  Renaming the session
fixed the problem.

An alternative is to use a slightly different URL instead of
git+ssh://bzr.savannah.gnu.org/srv/git/emacs/elpa, one that includes
the username in it explicitly, which is what I was doing before I
understood the above.

Re: ELPA commit freeze

[Dmitry Gutov]

On 20.08.2013 17:08, Andreas Schwab wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>> Could you explain why you're calling the subdirectory (or subtree, to look
>> at it another way) a branch?
>
> I don't.  A branch is what a merge commit references.

A merge commit references two commits, not branches, but I see what you 
meant, thanks.

Re: ELPA commit freeze

[Dmitry Gutov]

On 20.08.2013 17:45, Stefan Monnier wrote:
>> So we could check out the version before externals were introduces, erase
>> all their respective directories, then apply all commits made to the
>> "administrative" part of the tree, and then add the subtrees properly. Some
>> cleanup commits would have to be re-applied, but there's not a lot of them.
>
> We could try to do that.  I'm far form convinced it's worth the trouble.

Yep, I've tried that, and some of the subtree merges were done quite a 
while ago, e.g. coffee-mode. Maybe it's indeed not worth the trouble.

>> If it's too late, I suppose we can live with that, but this way we a) give
>> up an easy way to sync back, b) accept that we'll see each non-upstream
>> commit in externally maintained packages's histories twice: once for when
>> it's made, second after it's cherry-picked, committed to upstream and then
>> merged back into elpa.
>
> Not that "git subtree push" also duplicates the commits.  It just
> automates the process.  So, it's only a) that's lost.

Yes, I should've checked. So, if git-subtree does not include any 
additional conflict-resolving functionality, I guess sending commits 
from elpa to relevant upstreams by email should be close enough.

I guess the main drawback left is if anyone else looks at the 
description of how elpa is organized, thinks "git subtree!", and spends 
time trying to make it work properly.


That aside, could you look at the following emails? I sent them via 
Yandex's SMTP server accidentally and, as usual, they were bounced back 
from perlin.IRO.UMontreal.CA by timeout.

http://lists.gnu.org/archive/html/emacs-devel/2013-08/msg00521.html
http://lists.gnu.org/archive/html/emacs-devel/2013-08/msg00522.html

Re: ELPA commit freeze

[Stefan Monnier]

>> So we could easily handle
>> a list of exclusions by passing the list to "tar".
> How does this look to you?
> Downsides, so far:
> 1) Incessant "tar: Removing leading `../' from member names" warnings.
> 2) .elpaignore file itself is included. Maybe even not a downside.

Why bother with this "cd $pt; then use ../*; then cd .."?
It doesn't seem to worth the trouble.


        Stefan

Re: ELPA commit freeze

[Stefan Monnier]

> Cases in point:

> http://elpa.gnu.org/packages/ggtags.html
> http://elpa.gnu.org/packages/ack.html
> http://elpa.gnu.org/packages/js2-mode.html

> link to http://elpa.gnu.org/ and mention M-x list-packages, both of
> which are somewhat extraneous.

Please fix those README files in `elpa'.


        Stefan

Re: ELPA commit freeze

[Steinar Bang]

>>>>> Eli Zaretskii <eliz@gnu.org>:

> An alternative is to use a slightly different URL instead of
> git+ssh://bzr.savannah.gnu.org/srv/git/emacs/elpa, one that includes
> the username in it explicitly, which is what I was doing before I
> understood the above.

I've had varying success with using the username in the git URL.
Sometimes it has worked, and sometimes it hasn't, without me being able
to pinpoint the cause (probably caused by different versions of git, but
no proof that this is the case).  At least with msysgit 1.8.* it does
work.

But having a hostname given as username@hostname.hostdomain, with a
matching session name hostname.hostdomain, has always worked ("always"
being "since December 2010").

Re: ELPA commit freeze

[Dmitry Gutov]

On 21.08.2013 07:21, Stefan Monnier wrote:
>>> So we could easily handle
>>> a list of exclusions by passing the list to "tar".
>> How does this look to you?
>> Downsides, so far:
>> 1) Incessant "tar: Removing leading `../' from member names" warnings.
>> 2) .elpaignore file itself is included. Maybe even not a downside.
>
> Why bother with this "cd $pt; then use ../*; then cd .."?
> It doesn't seem to worth the trouble.

So that the paths in .elpaignore don't have to start with the name of 
the package's directory. Because that would be weird.

In one case, for example (f90-iface), the package and repository names 
don't match, and you usually expect a repository checkout to be in a 
directory with the same name.

Re: ELPA commit freeze

[Dmitry Gutov]

On 21.08.2013 07:23, Stefan Monnier wrote:
>> Cases in point:
>
>> http://elpa.gnu.org/packages/ggtags.html
>> http://elpa.gnu.org/packages/ack.html
>> http://elpa.gnu.org/packages/js2-mode.html
>
>> link to http://elpa.gnu.org/ and mention M-x list-packages, both of
>> which are somewhat extraneous.
>
> Please fix those README files in `elpa'.

You mean to make these changes local? I'd rather not have any 
unnecessary local changes, in general, and doing things differently from 
Melpa doesn't seem like a good idea either.

My point is, let's go back to using Commentary from <package-name>.el. 
If any those descriptions seem lacking to you, let's improve them 
instead, and others will be able to benefit from that, too.

Re: ELPA commit freeze

[Stefan Monnier]

> So that the paths in .elpaignore don't have to start with the name of the
> package's directory.

I expect that most of the patterns won't need to include any directory,
so they won't be affected care.

> Because that would be weird.

Slightly, but that seems rather minor.

> In one case, for example (f90-iface), the package and repository names don't
> match, and you usually expect a repository checkout to be in a directory
> with the same name.

No: f90-iface is only the name used on github.  It doesn't appear in the
`elpa' branch.


        Stefan

Re: ELPA commit freeze

[Stefan Monnier]

>> Please fix those README files in `elpa'.
> You mean to make these changes local?

Either that, or make the formulation such that it works in both cases.

> I'd rather not have any unnecessary local changes, in general, and
> doing things differently from Melpa doesn't seem like a good
> idea either.

In which way is it different?

> My point is, let's go back to using Commentary from <package-name>.el. If
> any those descriptions seem lacking to you, let's improve them instead, and
> others will be able to benefit from that, too.

I can't think of any reason why the README file should have any
significantly different content, since its role in places like github is
pretty much the same anyway.
It's OK to include something like

  "When installing straight from the repository, do <blibli>"


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 21.08.2013 23:00, Stefan Monnier wrote:
>>> Please fix those README files in `elpa'.
>> You mean to make these changes local?
>
> Either that, or make the formulation such that it works in both cases.

That would work, assuming this text doesn't show up in 
`describe-buffer', see below.

>> I'd rather not have any unnecessary local changes, in general, and
>> doing things differently from Melpa doesn't seem like a good
>> idea either.
>
> In which way is it different?

They intentionally don't use external README* files for generating 
package-readme.txt. I've mentioned that before:

http://lists.gnu.org/archive/html/emacs-devel/2013-08/msg00428.html

I guess elpa's main difference here is that you also display these texts 
on the elpa.gnu.org/packages/ "homepages".

Maybe they should be different: a homepage can list [different] 
installation options, but the contents of a `describe-package' buffer 
don't need any of them.

>> My point is, let's go back to using Commentary from <package-name>.el. If
>> any those descriptions seem lacking to you, let's improve them instead, and
>> others will be able to benefit from that, too.
>
> I can't think of any reason why the README file should have any
> significantly different content, since its role in places like github is
> pretty much the same anyway.

See above.

Re: ELPA commit freeze

[Dmitry Gutov]

On 21.08.2013 22:56, Stefan Monnier wrote:
>> So that the paths in .elpaignore don't have to start with the name of the
>> package's directory.
>
> I expect that most of the patterns won't need to include any directory,
> so they won't be affected care.

Ok, the smaller patch at the end works, too. Forgive the clunkiness, 
I've no experience with sh programming.

>> Because that would be weird.
>
> Slightly, but that seems rather minor.

And actually, $${pt} includes the package version, so there'll be no way 
to exclude specific filename at the top of the package repository, but 
not inside subdirectories.

I suppose it is a rather peculiar use case, though. Maybe leave it as 
"to be implemented".

diff --git a/GNUmakefile b/GNUmakefile
index 0fac72b..e95bcde 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -49,7 +49,9 @@ process-archive:
  	  for pt in *; do \
  	      if [ -d $$pt ]; then \
  		  echo "Creating tarball $${pt}.tar" && \
-		  tar -cf $${pt}.tar $$pt --remove-files; \
+		  tar -cf $${pt}.tar $$pt \
+		  $$(if [ -f $${pt}/.elpaignore ]; then echo "-X $${pt}/.elpaignore"; 
fi;); \
+		  rm -r $${pt}; \
  	      fi; \
  	  done
  	mkdir -p archive/packages

Re: ELPA commit freeze

[Stefan Monnier]

> Maybe they should be different: a homepage can list [different] installation
> options, but the contents of a `describe-package' buffer don't need any
> of them.

They don't need them, but having them doesn't hurt.


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 22.08.2013 02:56, Stefan Monnier wrote:
>> Maybe they should be different: a homepage can list [different] installation
>> options, but the contents of a `describe-package' buffer don't need any
>> of them.
>
> They don't need them, but having them doesn't hurt.

README.md also may be missing usage information that's in Commentary. 
I've checked, and it's actually the case with all packages I'm 
maintaining (except one, out of 6), whether I'm the author or not.

I've mentioned the issues in which is was discussed, feel free to 
participate.

But if Melpa is going to generate readme.txt from the Commentary, and 
ELPA - from README.md, I'd hate to be forced to keep (more than a bare 
minimum of) duplicate information there.

Take company's README.md, for example. It's barren, but Commentary in 
company.el contains what you'd expect from a description. I'd like to 
keep things that way there.

Re: ELPA commit freeze

[Stefan Monnier]

> README.md also may be missing usage information that's in Commentary.
> I've checked, and it's actually the case with all packages I'm
> maintaining (except one, out of 6), whether I'm the author or not.

Why couldn't that be fixed?  Why should usage info not be in README.md?

> Take company's README.md, for example.  It's barren, but Commentary in
> company.el contains what you'd expect from a description.  I'd like to keep
> things that way there.

We can remove README.md from elpa/packages/company, if you prefer.
Or we could just remove support for elpa/packages/*/README.md so that
those files are systematically ignored.


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 22.08.2013 04:55, Stefan Monnier wrote:
>> README.md also may be missing usage information that's in Commentary.
>> I've checked, and it's actually the case with all packages I'm
>> maintaining (except one, out of 6), whether I'm the author or not.
>
> Why couldn't that be fixed?  Why should usage info not be in README.md?

Because it's customary to put at least something into Commentary, usage 
info seems to be the most natural info to put there, and duplicating 
text is not nice. See my previous emails for better arguments.

>> Take company's README.md, for example.  It's barren, but Commentary in
>> company.el contains what you'd expect from a description.  I'd like to keep
>> things that way there.
>
> We can remove README.md from elpa/packages/company, if you prefer.

Of course I don't.

> Or we could just remove support for elpa/packages/*/README.md so that
> those files are systematically ignored.

That's what I was suggesting. Keep supporting plain README's, unlike 
Melpa, as a backward compatibility measure, and because they're rare anyway.

If you're okay with that, I can make the change.

Note that I still like the idea of using README.md's for pages at 
elpa.gnu.org/packages/*, but that can be implemented later.

Re: ELPA commit freeze

[Stefan Monnier]

>> Why couldn't that be fixed?  Why should usage info not be in README.md?
> Because it's customary to put at least something into Commentary, usage info
> seems to be the most natural info to put there, and duplicating text is not
> nice. See my previous emails for better arguments.

OK.  let's try to take a step back.  You're suggesting that we need
2 places where we put different info (one being the Commentary: and
another being the README.*).

I just don't see it.  If you want to put info in the README, then you
can put all the relevant info in the README, and the Commentary: can
be trivial.  And vice versa.

>>> Take company's README.md, for example.  It's barren, but Commentary in
>>> company.el contains what you'd expect from a description.  I'd like to keep
>>> things that way there.

Why?  Why not move the info from company.el to README.md (where it can
be made prettier while you're at it)?


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 22.08.2013 23:35, Stefan Monnier wrote:
>>> Why couldn't that be fixed?  Why should usage info not be in README.md?
>> Because it's customary to put at least something into Commentary, usage info
>> seems to be the most natural info to put there, and duplicating text is not
>> nice. See my previous emails for better arguments.
>
> OK.  let's try to take a step back.  You're suggesting that we need
> 2 places where we put different info (one being the Commentary: and
> another being the README.*).

That's what often happens already anyway.

> I just don't see it.  If you want to put info in the README, then you
> can put all the relevant info in the README, and the Commentary: can
> be trivial.  And vice versa.

Yes, nothing's stopping us from arranging the information in any 
arbitrary way. Except for social factors.

To have the description recognized by both Elpa and Melpa, currently I'd 
have to keep the same text in README.md and Commentary. And 
`describe-package' buffer from Melpa would end up looking better due to 
not having extraneous info.

To switch Melpa over to preferring text from README.md over Commentary, 
you'd have to make an argument that it would result in better, more 
relevant descriptions for packages that they distribute, overall.

And they are tracking ~300 multi-file and ~2700 single-file packages, so 
it's not like we can easily change a significant portion of them over to 
a different convention.

>>>> Take company's README.md, for example.  It's barren, but Commentary in
>>>> company.el contains what you'd expect from a description.  I'd like to keep
>>>> things that way there.
>
> Why?  Why not move the info from company.el to README.md (where it can
> be made prettier while you're at it)?

It already has a homepage that has all that info. It's prettier than the 
github page due to having some dedicated styling.

Putting the same stuff on the homepage and in README.md would, again, 
result in duplication, or at least some non-trivial work by automating 
the export from the latter into the former. It's doable, but the link 
works just as good.

Re: ELPA commit freeze

[Stefan Monnier]

> To have the description recognized by both Elpa and Melpa, currently I'd
> have to keep the same text in README.md and Commentary.  And
> describe-package' buffer from Melpa would end up looking better due to not
> having extraneous info.

I don't think MELPA is very important here.  I guess you use it so as to
distribute snapshots of the code, but I think we need that for ELPA
anyway (we already have it for Org, tho it's terribly ad-hoc).

So assuming we'll have a "GNU ELPA snapshots" archive (help welcome),
this is a non-problem.

>> Why?  Why not move the info from company.el to README.md (where it can
>> be made prettier while you're at it)?
> It already has a homepage that has all that info. It's prettier than the
> github page due to having some dedicated styling.
> Putting the same stuff on the homepage and in README.md would, again, result
> in duplication, or at least some non-trivial work by automating the export
> from the latter into the former. It's doable, but the link works just
> as good.

You currently have duplication between Commentary: and the homepage.
I'm just suggesting to move that duplication from Commentary: to
README.md.  So duplication-wise it's no worse than what we
currently have.


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 23.08.2013 03:51, Stefan Monnier wrote:
>> To have the description recognized by both Elpa and Melpa, currently I'd
>> have to keep the same text in README.md and Commentary.  And
>> describe-package' buffer from Melpa would end up looking better due to not
>> having extraneous info.
>
> I don't think MELPA is very important here.

Until ELPA supports snapshots and updates faster than in 24 hours, Melpa 
is important, to me at least.

> I guess you use it so as to
> distribute snapshots of the code, but I think we need that for ELPA
> anyway (we already have it for Org, tho it's terribly ad-hoc).

So far I see only one option for Org installation. To distribute 
snapshots, you'd have to use a separate package archive, right? One 
that's also disabled by default? What would be the advantages over 
Melpa? Its audience would likely be (and remain) smaller, for example.

> So assuming we'll have a "GNU ELPA snapshots" archive (help welcome),
> this is a non-problem.

It's either "help welcome" or "a non-problem", can't be both.
I'm not convinced this is something worth doing.

> You currently have duplication between Commentary: and the homepage.
> I'm just suggesting to move that duplication from Commentary: to
> README.md.  So duplication-wise it's no worse than what we
> currently have.

It would be. A README.md, if present, is expected to have Installation 
section and, basically, most of you see on the home page.
So far, what's duplicated is mostly Usage, with some additional info 
added in Commentary.

The Commentary was written before me, by the way. The part about "how to 
write a back-end" probably need to move somewhere.

Re: ELPA commit freeze

[Stefan Monnier]

>> You currently have duplication between Commentary: and the homepage.
>> I'm just suggesting to move that duplication from Commentary: to
>> README.md.  So duplication-wise it's no worse than what we
>> currently have.
> It would be. A README.md, if present, is expected to have Installation
> section and, basically, most of you see on the home page.
> So far, what's duplicated is mostly Usage, with some additional info added
> in Commentary.

Currently your README.md contains nothing but a pointer to the webpage.
Clearly, it's not that important to include every one of those elements.

So nothing prevents you from keeping the same pointer and simply add to
it the Commentary text (which you then remove from Commentary).
Tadaa! no more duplication than what we already have.


        Stefan


PS: I'll remove "README.md" from the list of files to consider, but
I really think it's fundamentally wrong, so it's just
a temporary measure.

Re: ELPA commit freeze

[Dmitry Gutov]

On 23.08.2013 07:12, Stefan Monnier wrote:
> Currently your README.md contains nothing but a pointer to the webpage.
> Clearly, it's not that important to include every one of those elements.

When you see a pointer, you just follow it. Having a piece of text there 
would be different.

> So nothing prevents you from keeping the same pointer and simply add to
> it the Commentary text (which you then remove from Commentary).
> Tadaa! no more duplication than what we already have.

I wouldn't put just the Usage section in README.md together with a link 
to the proper homepage which contains a similar Usage section, in any 
situation, other than to appease the ELPA readme.txt generator.

> PS: I'll remove "README.md" from the list of files to consider,

Thank you.

 > but I really think it's fundamentally wrong, so it's just
> a temporary measure.

Like I mentioned, my reasons are mostly social, so I wouldn't mind 
having a change, provided all parties agree.

But doesn't putting different information in different places make sense 
to you, at least on some level?

For example, http://elpa.gnu.org/packages/company.html includes the 
contents of NEWS.md, which looks great.
It could similarly combine README.md and Commentary.

Re: ELPA commit freeze

[Stefan Monnier]

>> Currently your README.md contains nothing but a pointer to the webpage.
>> Clearly, it's not that important to include every one of those elements.
> When you see a pointer, you just follow it. Having a piece of text there
> would be different.

Ideally, the README would be a copy of the homepage, tho (and the same
text would be used for ELPA's and MELPA's readme.txt).  So you only
need to maintain one text, which is then copied to all places.

> But doesn't putting different information in different places make sense to
> you, at least on some level?

Hmm.... what an idea!?

> For example, http://elpa.gnu.org/packages/company.html includes the contents
> of NEWS.md, which looks great.
> It could similarly combine README.md and Commentary.

OK, that sounds promising, except I don't know how to combine them.
Could you define clearly "the division of work" between the two?
Or maybe we should just concatenate them and let the authors figure
out how to divide the work between the two?

One other issue is that Commentary does not have any markup, and I'd
like to use markup more actively (e.g. converting into HTML when
including it in packages/company.html, and rendering it on-the-fly in
describe-package).
[ Now, obviously we'd need a good on-the-fly rendering, which we don't
  have yet, so maybe the markup format won't be MarkDown anyway.  ]


        Stefan

Re: ELPA commit freeze

[Donald Curtis]

[-- Attachment #1: Type: text/plain, Size: 951 bytes --]

I wasn't able to capture the entire conversation in my head by reading the
archives but I just wanted to chime in on how we (MELPA) see the README vs.
the commentary section. As far as I know, the commentary is what we use to
craft the `describe-package` information. Our impression was that for
single-file packages, the commentary is normally enough to describe the
purpose of the package and normal use-case.

For larger packages, lets say "magit" for example, the commentary should be
a short description of the package and maybe a link to more documentation,
possibly a link to the README.
I can see that in some cases this is a bit of duplicate information, but in
most cases I think the commentary is a bit lighter on details.

Hope this helps give some outsider input. I would agree that "as MELPA"
what we say or feel shouldn't impact the greater Emacs community. I
contribute this information as a user who has thought about packages a lot.

[-- Attachment #2: Type: text/html, Size: 1071 bytes --]

Re: ELPA commit freeze

[Stefan Monnier]

> For larger packages, lets say "magit" for example, the commentary
> should be a short description of the package and maybe a link to more
> documentation, possibly a link to the README.  I can see that in some
> cases this is a bit of duplicate information, but in most cases
> I think the commentary is a bit lighter on details.

I think I understand what you mean.  But I'm not sure this duplication
is necessary.  GNU ELPA has the difference w.r.t MELPA that we're
willing to maintain local patches, if needed, so as to better conform to
our conventions.  In this case I'd like to come up with a convention that
avoids this duplication.


        Stefan

Re: ELPA commit freeze

[Dmitry Gutov]

On 23.08.2013 18:05, Stefan Monnier wrote:
>>> Currently your README.md contains nothing but a pointer to the webpage.
>>> Clearly, it's not that important to include every one of those elements.
>> When you see a pointer, you just follow it. Having a piece of text there
>> would be different.
>
> Ideally, the README would be a copy of the homepage, tho (and the same
> text would be used for ELPA's and MELPA's readme.txt).

I don't know about ideally, but yes, some projects do that.

 > So you only
> need to maintain one text, which is then copied to all places.

It doesn't transfer well to Commentary, though.

>> For example, http://elpa.gnu.org/packages/company.html includes the contents
>> of NEWS.md, which looks great.
>> It could similarly combine README.md and Commentary.
>
> OK, that sounds promising, except I don't know how to combine them.
> Could you define clearly "the division of work" between the two?

One of the patterns I've seen and used is have an overview, feature 
enumeration and brief usage section in README.md, but a more detailed or 
a hands-on usage instructions in Commentary. For example, the latter 
more often lists elisp commands defined by the package, its default 
keybindings, customizable options.

Some rough, inexact examples:

https://github.com/capitaomorte/yasnippet
https://github.com/dgutov/robe
https://github.com/pezra/rspec-mode
https://github.com/ScottyB/ac-js2
https://github.com/dgutov/diff-hl

There's a certain advantage to listing Elisp functions and variables in 
an .el files: when opened in Emacs, they're highlighted the usual way 
given proper markup, you can use the `describe-' commands on them easily 
and jump to their definitions. `describe-function' works well enough in 
markdown-mode too, but any bindings customized for emacs-lisp-mode, won't.

> Or maybe we should just concatenate them and let the authors figure
> out how to divide the work between the two?

Either show Overview (aka README.md), Usage and News under separate 
headings, or add a horizontal menu with these items at the top, so that 
the user only sees one of these at the time.

To make it less prescriptive, we can call the second section/tab 
literally Commentary (so authors can work out the separation of 
information themselves), but I don't have any other suggestions for the 
first section name.

> One other issue is that Commentary does not have any markup, and I'd
> like to use markup more actively (e.g. converting into HTML when
> including it in packages/company.html, and rendering it on-the-fly in
> describe-package).

Since Commentary lives in an .el file, I think it should be an extension 
of the current docstring or comment markup. So we have a way to 
highlight separate symbols, maybe also interpret additionally indented 
blocks of text as code. Lists, similarly to markdown. For subheadings, 
standardize on some scheme with extra leading semicolons. What's 
missing? Links, images?