Make ELPA and nongnu elpa more accessible

Make ELPA and nongnu elpa more accessible

[Fu Yuan]

I think both ELPA could use some improvement on accessibility, eg, change the raw readme file to a html, mention nongnu on ELPA and vice versa, add a link to readme on nongnu ELPA, etc. I plan to clone it and add/edit some html files. Is there anything I need to know before I start?

Yuan 

Yuan

Re: Make ELPA and nongnu elpa more accessible

[Stefan Monnier]

> I think both ELPA could use some improvement on accessibility, eg, change
> the raw readme file to a html,

I'm OK with generating an HTML version from some source version
(e.g. README.org or README.md), but I definitely have no intention of
editing/reading an HTML version of that file.

The intended audience is expected to be using Emacs, so the format
should be Emacs-friendly which HTML isn't.

[ Hmm... now that I reread the above I wonder if I have misunderstood.
  I'm talking about the (elpa|nongnu).git/README and admin/README.  ]

> mention nongnu on ELPA and vice versa, add a link to readme on nongnu
> ELPA, etc.

Sounds good (IIRC there are already suggestions/patches to do some of
that, which I have in my TODO list, and now that I can log into
elpa.gnu.org again I'm hoping to get to it soon ;-).


        Stefan

Re: Make ELPA and nongnu elpa more accessible

[Yuan Fu]

> On Aug 3, 2021, at 10:49 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> I think both ELPA could use some improvement on accessibility, eg, change
>> the raw readme file to a html,
> 
> I'm OK with generating an HTML version from some source version
> (e.g. README.org or README.md), but I definitely have no intention of
> editing/reading an HTML version of that file.
> 
> The intended audience is expected to be using Emacs, so the format
> should be Emacs-friendly which HTML isn't.
> 
> [ Hmm... now that I reread the above I wonder if I have misunderstood.
>  I'm talking about the (elpa|nongnu).git/README and admin/README.  ]

index.html is the html file that I intend to edit. As for README, I think it is targeted towards developer/admin of ELPA, rather than someone who just want to add his package to ELPA. And it obscures the fact that adding your package to ELPA is extremely easy. 

I want to add a guide for those who has a package on github and want to add it to ELPA, which I assume to be the majority. Some thing like this:

Emacs elpa and nongnu elpa starter guide

* Difference between GNU ELPA and NONGNU ELPA

To distribute a package on GNU ELPA, author and contributors need to
sign the copyright assignment, NONGNU ELPA doesn’t pose that
requirement.

* Add a package hosted on GitHub/GitLab to GNU ELPA

1. Update file header to comply to the [[standard format][some link]] (copyright notice, etc)
2. Send an email to emacs-devel@gnu.org to sign the copyright
assignment (and ask contributors to do the same, if their contribution
is larger than 15 lines of code)
3. Send an email to emacs-devel@gnu.org asking to add your package to
GNU ELPA, and wait for administrator to review your package and add it
for you.

* Add a pacakge hosted on GitHub/GitLab to NONGNU ELPA

Like the procedure for GNU ELPA but without step two.

* Update your package on GNU ELPA

(I believe you only need to add a tag, is that right?)

* (maybe) talk about GNU ELPA-devel and NONGNU ELPA-devel

Yuan

Re: Make ELPA and nongnu elpa more accessible

[Bozhidar Batsov]

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

I think those are all wonderful ideas! I can relate to the problem you're trying to solve, as I was confused on some of those points just a couple of days ago. 

On Wed, Aug 4, 2021, at 5:26 AM, Yuan Fu wrote:
> 
> 
> > On Aug 3, 2021, at 10:49 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> > 
> >> I think both ELPA could use some improvement on accessibility, eg, change
> >> the raw readme file to a html,
> > 
> > I'm OK with generating an HTML version from some source version
> > (e.g. README.org or README.md), but I definitely have no intention of
> > editing/reading an HTML version of that file.
> > 
> > The intended audience is expected to be using Emacs, so the format
> > should be Emacs-friendly which HTML isn't.
> > 
> > [ Hmm... now that I reread the above I wonder if I have misunderstood.
> >  I'm talking about the (elpa|nongnu).git/README and admin/README.  ]
> 
> index.html is the html file that I intend to edit. As for README, I think it is targeted towards developer/admin of ELPA, rather than someone who just want to add his package to ELPA. And it obscures the fact that adding your package to ELPA is extremely easy. 
> 
> I want to add a guide for those who has a package on github and want to add it to ELPA, which I assume to be the majority. Some thing like this:
> 
> Emacs elpa and nongnu elpa starter guide
> 
> * Difference between GNU ELPA and NONGNU ELPA
> 
> To distribute a package on GNU ELPA, author and contributors need to
> sign the copyright assignment, NONGNU ELPA doesn’t pose that
> requirement.
> 
> * Add a package hosted on GitHub/GitLab to GNU ELPA
> 
> 1. Update file header to comply to the [[standard format][some link]] (copyright notice, etc)
> 2. Send an email to emacs-devel@gnu.org to sign the copyright
> assignment (and ask contributors to do the same, if their contribution
> is larger than 15 lines of code)
> 3. Send an email to emacs-devel@gnu.org asking to add your package to
> GNU ELPA, and wait for administrator to review your package and add it
> for you.
> 
> * Add a pacakge hosted on GitHub/GitLab to NONGNU ELPA
> 
> Like the procedure for GNU ELPA but without step two.
> 
> * Update your package on GNU ELPA
> 
> (I believe you only need to add a tag, is that right?)
> 
> * (maybe) talk about GNU ELPA-devel and NONGNU ELPA-devel
> 
> Yuan
> 

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

Re: Make ELPA and nongnu elpa more accessible

[Stefan Monnier]

> index.html is the html file that I intend to edit. As for README, I think it
> is targeted towards developer/admin of ELPA,

Actually, it's not.  (instead, it's been largely written by
developer/admin of ELPA, and the result shows :-(  Part of the reason
also is that it used to be impossible to build a single tarball at
a time, so a developer who wanted to test the build of its own package
had to setup a complete ELPA archive).

> rather than someone who just want to add his package to ELPA.

Note that this someone will start thinking all they need to know is how
to write the `elpa-packages` spec, but soon enough they'll also need to
learn about how elpa.gnu.org decides to build a new package and which
commit is used to build a particular version.  And they may also want to
check the result of building the tarball before a release (or to test
their spec), so they may also want to know about `make build/<PKG>`, ...

Which is why the README has a lot of info.

> And it obscures the fact that adding your package to ELPA is
> extremely easy.

Yes, it's in dire need of love.  Patches welcome.

Note also that we have 3 READMEs:
- one for GNU ELPA
- one for NonGNU ELPA
- one for the elpa-admin scripts (i.e. that's the one that should
  describe the format of the `elpa-packages` specs, the rules about
  `Version:`, etc...).

The READMEs for GNU ELPA and NonGNU ELPA should be reasonably short and
focus on the differences between the two: mostly the respective URLs and
the rules that we want packages to abide to w.r.t. Free Software
and copyright.


        Stefan

Re: Make ELPA and nongnu elpa more accessible

[Philip Kaludercic]

Fu Yuan <casouri@gmail.com> writes:

> I think both ELPA could use some improvement on accessibility, eg,
> change the raw readme file to a html, mention nongnu on ELPA and vice
> versa, add a link to readme on nongnu ELPA, etc. I plan to clone it
> and add/edit some html files. Is there anything I need to know before
> I start?

Should HTML files really be added to the repository itself? If there is
no way to view the rendered results in a git browser, it seems no better
than using a plain-text readable markup format like Org and converting
that to HTML.

-- 
	Philip Kaludercic