Add plz-media-type and plz-event-source to GNU ELPA when stabilized

Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Roman Scherer]

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


Hello Emacs Developers,

I am writing you to ask if we could include the ~plz-media-type~ [1]
and the ~plz-event-source~ [2] libraries to GNU ELPA, once Andrew
Hyatt and I declare them as releasable.

At the moment those 2 libraries are "vendored" (we copied 2 files) in
the llm [3] library. Andrew and I would like to ship them via the llm
library to users for now, and once we are confident there are no
serious issues we would like to release them to GNU ELPA. We plan to
do so in Q4 of 2024.

These libraries are designed to handle HTTP responses based on the
content type header and process the response in a way specific to the
media type. One example of this is to process a HTTP response in the
text/event-stream format (aka server sent events) and handle the
events as they arrive.

Both libraries use Adam Porter's plz library and I wrote them to
support Andrew Hyatt in his work on the llm library. We are planning
to add support to the llm library to make HTTP requests with
curl. This should solve reliability issues that Andrew saw, and allows
me to use the llm library with LLMs that sit behind the proxy of my
employer, who supported my work on this.

They also simplified the code in the llm library that handles the
various response formats that are in use by all those LLMs deployed
out there. The libraries are designed to be extendable and could be
used by Emacs packages that, as of today, implement their own way to
handle for example, server sent events in a streaming way.

*plz-media-type:*

This library builds upon the ~plz.el~ HTTP library and provides a
mechanism to process responses based on their content type headers. It
defines classes for parsing and processing the HTTP body of some
standard MIME types like JSON, XML, HTML. It also contains classes
that can handle formats like newline delimited JSON, or JSON arrays in
a streaming way. Those last formats are often used by LLMs. The
library is designed to be extendable (you can replace and bring your
own media type class) and frees users from writing their own process
filter functions.

*plz-event-source:*

This library provides a media type class, parser, and event source
implementation for the Server-Sent Events (SSE) protocol. The media
type class can be used with the ~plz-media-type~ library. We use it in
the llm library to process HTTP responses for LLMs that return a MIME
type of text/event-stream.

I won't spend any significant time on re-designing the API (we went
through many iterations) or making it compatible with url-retrieve
right now, in case someone is suggesting this. This project was partly
sponsored by my employer while I was on a 3 month working group and we
want to use the llm library with curl. My time on this is reaching an
end I would like to bring it over the finish line. I am committed to
support Andrew should any bugs or significant issues come up.

Andrew Hyatt asked me to write to you to get the green light for
publishing those libraries to GNU ELPA, once we think they are
stable. We plan to do this in about half a year.

If you agree on eventually releasing those libraries to GNU ELPA, we
plan to merge the "plz" branch of the llm library into master soon and
release it to a wider audience. One package that would immediately
benefit is Ellama [4] which I thoroughly tested while working on this.

My employer and I already did the copyright assignment paperwork,
which has been completed a month ago.

Wdyt?

Thanks, Roman.

[1] https://github.com/r0man/plz-media-type
[2] https://github.com/r0man/plz-event-source
[3] https://github.com/ahyatt/llm/tree/plz
[4] https://github.com/s-kostyaev/ellama

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Philip Kaludercic]

Roman Scherer <roman.scherer@burningswell.com> writes:

> Hello Emacs Developers,
>
> I am writing you to ask if we could include the ~plz-media-type~ [1]
> and the ~plz-event-source~ [2] libraries to GNU ELPA, once Andrew
> Hyatt and I declare them as releasable.

We can add the libraries to ELPA right now, if you mark the package
version as something that shouldn't be released.  This appears to be the
case right now, as the versions end in -pre.  As soon as you change
this, the packages would be released on ELPA.

The only question I have, from a very superficial understanding, is why
you don't want to upstream these into the library called "plz" itself?
Is that unfeasible or did Adam reject the changes?

Quickly scanning the code made it seem OK, all I would suggest not using
the README for both the repository README file and the manual.  Also, if
possible I'd avoid tracking the generated .info file in the repository
itself.

> At the moment those 2 libraries are "vendored" (we copied 2 files) in
> the llm [3] library. Andrew and I would like to ship them via the llm
> library to users for now, and once we are confident there are no
> serious issues we would like to release them to GNU ELPA. We plan to
> do so in Q4 of 2024.
>
> These libraries are designed to handle HTTP responses based on the
> content type header and process the response in a way specific to the
> media type. One example of this is to process a HTTP response in the
> text/event-stream format (aka server sent events) and handle the
> events as they arrive.
>
> Both libraries use Adam Porter's plz library and I wrote them to
> support Andrew Hyatt in his work on the llm library. We are planning
> to add support to the llm library to make HTTP requests with
> curl. This should solve reliability issues that Andrew saw, and allows
> me to use the llm library with LLMs that sit behind the proxy of my
> employer, who supported my work on this.
>
> They also simplified the code in the llm library that handles the
> various response formats that are in use by all those LLMs deployed
> out there. The libraries are designed to be extendable and could be
> used by Emacs packages that, as of today, implement their own way to
> handle for example, server sent events in a streaming way.
>
> *plz-media-type:*
>
> This library builds upon the ~plz.el~ HTTP library and provides a
> mechanism to process responses based on their content type headers. It
> defines classes for parsing and processing the HTTP body of some
> standard MIME types like JSON, XML, HTML. It also contains classes
> that can handle formats like newline delimited JSON, or JSON arrays in
> a streaming way. Those last formats are often used by LLMs. The
> library is designed to be extendable (you can replace and bring your
> own media type class) and frees users from writing their own process
> filter functions.
>
> *plz-event-source:*
>
> This library provides a media type class, parser, and event source
> implementation for the Server-Sent Events (SSE) protocol. The media
> type class can be used with the ~plz-media-type~ library. We use it in
> the llm library to process HTTP responses for LLMs that return a MIME
> type of text/event-stream.
>
> I won't spend any significant time on re-designing the API (we went
> through many iterations) or making it compatible with url-retrieve
> right now, in case someone is suggesting this. This project was partly
> sponsored by my employer while I was on a 3 month working group and we
> want to use the llm library with curl. My time on this is reaching an
> end I would like to bring it over the finish line. I am committed to
> support Andrew should any bugs or significant issues come up.
>
> Andrew Hyatt asked me to write to you to get the green light for
> publishing those libraries to GNU ELPA, once we think they are
> stable. We plan to do this in about half a year.
>
> If you agree on eventually releasing those libraries to GNU ELPA, we
> plan to merge the "plz" branch of the llm library into master soon and
> release it to a wider audience. One package that would immediately
> benefit is Ellama [4] which I thoroughly tested while working on this.
>
> My employer and I already did the copyright assignment paperwork,
> which has been completed a month ago.
>
> Wdyt?
>
> Thanks, Roman.
>
> [1] https://github.com/r0man/plz-media-type
> [2] https://github.com/r0man/plz-event-source
> [3] https://github.com/ahyatt/llm/tree/plz
> [4] https://github.com/s-kostyaev/ellama
>

-- 
	Philip Kaludercic on peregrine

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Roman Scherer]

[-- Attachment #1.1: Type: text/plain, Size: 3187 bytes --]


Hi Philip,

thanks for answer. 

Philip Kaludercic <philipk@posteo.net> writes:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
>> Hello Emacs Developers,
>>
>> I am writing you to ask if we could include the ~plz-media-type~ [1]
>> and the ~plz-event-source~ [2] libraries to GNU ELPA, once Andrew
>> Hyatt and I declare them as releasable.
>
> We can add the libraries to ELPA right now, if you mark the package
> version as something that shouldn't be released.  This appears to be the
> case right now, as the versions end in -pre.  As soon as you change
> this, the packages would be released on ELPA.

Ok, I'm fine with this. Both packages have -pre in their version, and I
made sure there aren't any tags in Git. What would actually trigger
release, a change in the version of the Emacs Lisp file, or a Git tag,
or both?

I also attached two patches for elpa that add the packages. I tried
building them locally and the resulting tarballs look fine to me.

This is the file listing of both of them:

 -rw-rw-r--   roman/roman     30814 plz-media-type-0.1pre0.20240428.92556/plz-media-type.el
 -rw-rw-r--   roman/roman     19238 plz-media-type-0.1pre0.20240428.92556/README-elpa
 -rw-rw-r--   roman/roman       428 plz-media-type-0.1pre0.20240428.92556/plz-media-type-pkg.el
 -rw-rw-r--   roman/roman     19229 plz-media-type-0.1pre0.20240428.92556/README.org
 -rw-rw-r--   roman/roman     19587 plz-media-type-0.1pre0.20240428.92556/plz-media-type.info

 -rw-rw-r--   roman/roman      4821 plz-event-source-0.1pre0.20240428.114418/plz-event-source.info
 -rw-rw-r--   roman/roman      4358 plz-event-source-0.1pre0.20240428.114418/README-elpa
 -rw-rw-r--   roman/roman      5578 plz-event-source-0.1pre0.20240428.114418/README.org
 -rw-rw-r--   roman/roman     18249 plz-event-source-0.1pre0.20240428.114418/plz-event-source.el
 -rw-rw-r--   roman/roman       436 plz-event-source-0.1pre0.20240428.114418/plz-event-source-pkg.el

> The only question I have, from a very superficial understanding, is why
> you don't want to upstream these into the library called "plz" itself?
> Is that unfeasible or did Adam reject the changes?

We were initially considering this, but both packages contain now more
code than Adam would like to add to plz. At least for now, but I guess
we keep it that way. The average plz user might not be interested in all
of the code.

We upstreamed a small change that allows setting a process filter to
plz, which we needed to make it possible to handle the response in a
streaming way.

> Quickly scanning the code made it seem OK, all I would suggest not using
> the README for both the repository README file and the manual.  Also, if
> possible I'd avoid tracking the generated .info file in the repository
> itself.

I removed the generated .info files now from both repositories and
generate them now through the ELPA build process.

I haven't split the README and the manual just yet. It's done in the
same way as in the plz repository. I would actually prefer to have this
also shown on the README.

Why do you suggest splitting them? What are the benefits of it?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-Add-plz-media-type.patch --]
[-- Type: text/x-diff, Size: 873 bytes --]

From 97062a3b91b6cd289ace830229c4a6f8e84845a1 Mon Sep 17 00:00:00 2001
Message-ID: <97062a3b91b6cd289ace830229c4a6f8e84845a1.1714307767.git.roman@burningswell.com>
From: Roman Scherer <roman@burningswell.com>
Date: Sun, 28 Apr 2024 14:35:20 +0200
Subject: [PATCH 1/2] Add plz-media-type

---
 elpa-packages | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 4a0c1bd..2babaf7 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -587,6 +587,9 @@
   :release-branch "stable"
   :ignored-files ("LICENSE")
   :doc "README.org")
+ (plz-media-type        :url "https://github.com/r0man/plz-media-type"
+  :doc "README.org"
+  :ignored-files ("LICENSE"))
  (plz-see		:url "https://github.com/astoff/plz-see.el"
   :readme "README.org")
  (poke			:url "https://git.savannah.gnu.org/git/poke/poke-el.git"
-- 
2.41.0


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.3: 0002-Add-plz-event-source.patch --]
[-- Type: text/x-diff, Size: 1044 bytes --]

From 6c6fe27f2406635634f2ec15b62a7a526b17d48e Mon Sep 17 00:00:00 2001
Message-ID: <6c6fe27f2406635634f2ec15b62a7a526b17d48e.1714307767.git.roman@burningswell.com>
In-Reply-To: <97062a3b91b6cd289ace830229c4a6f8e84845a1.1714307767.git.roman@burningswell.com>
References: <97062a3b91b6cd289ace830229c4a6f8e84845a1.1714307767.git.roman@burningswell.com>
From: Roman Scherer <roman@burningswell.com>
Date: Sun, 28 Apr 2024 14:35:51 +0200
Subject: [PATCH 2/2] Add plz-event-source

---
 elpa-packages | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 2babaf7..9cc9cf5 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -587,6 +587,9 @@
   :release-branch "stable"
   :ignored-files ("LICENSE")
   :doc "README.org")
+ (plz-event-source        :url "https://github.com/r0man/plz-event-source"
+  :doc "README.org"
+  :ignored-files ("LICENSE"))
  (plz-media-type        :url "https://github.com/r0man/plz-media-type"
   :doc "README.org"
   :ignored-files ("LICENSE"))
-- 
2.41.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Philip Kaludercic]

Roman Scherer <roman.scherer@burningswell.com> writes:

> Hi Philip,
>
> thanks for answer. 
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Roman Scherer <roman.scherer@burningswell.com> writes:
>>
>>> Hello Emacs Developers,
>>>
>>> I am writing you to ask if we could include the ~plz-media-type~ [1]
>>> and the ~plz-event-source~ [2] libraries to GNU ELPA, once Andrew
>>> Hyatt and I declare them as releasable.
>>
>> We can add the libraries to ELPA right now, if you mark the package
>> version as something that shouldn't be released.  This appears to be the
>> case right now, as the versions end in -pre.  As soon as you change
>> this, the packages would be released on ELPA.
>
> Ok, I'm fine with this. Both packages have -pre in their version, and I
> made sure there aren't any tags in Git. What would actually trigger
> release, a change in the version of the Emacs Lisp file, or a Git tag,
> or both?

The ELPA build server only tracks changes to the Elisp files, Git tags
are ignored.

> I also attached two patches for elpa that add the packages. I tried
> building them locally and the resulting tarballs look fine to me.
>
> This is the file listing of both of them:
>
>  -rw-rw-r--   roman/roman     30814 plz-media-type-0.1pre0.20240428.92556/plz-media-type.el
>  -rw-rw-r--   roman/roman     19238 plz-media-type-0.1pre0.20240428.92556/README-elpa
>  -rw-rw-r--   roman/roman       428 plz-media-type-0.1pre0.20240428.92556/plz-media-type-pkg.el
>  -rw-rw-r--   roman/roman     19229 plz-media-type-0.1pre0.20240428.92556/README.org
>  -rw-rw-r--   roman/roman     19587 plz-media-type-0.1pre0.20240428.92556/plz-media-type.info
>
>  -rw-rw-r--   roman/roman      4821 plz-event-source-0.1pre0.20240428.114418/plz-event-source.info
>  -rw-rw-r--   roman/roman      4358 plz-event-source-0.1pre0.20240428.114418/README-elpa
>  -rw-rw-r--   roman/roman      5578 plz-event-source-0.1pre0.20240428.114418/README.org
>  -rw-rw-r--   roman/roman     18249 plz-event-source-0.1pre0.20240428.114418/plz-event-source.el
>  -rw-rw-r--   roman/roman       436 plz-event-source-0.1pre0.20240428.114418/plz-event-source-pkg.el

Thanks!

>> The only question I have, from a very superficial understanding, is why
>> you don't want to upstream these into the library called "plz" itself?
>> Is that unfeasible or did Adam reject the changes?
>
> We were initially considering this, but both packages contain now more
> code than Adam would like to add to plz. At least for now, but I guess
> we keep it that way. The average plz user might not be interested in all
> of the code.
>
> We upstreamed a small change that allows setting a process filter to
> plz, which we needed to make it possible to handle the response in a
> streaming way.

OK, my only concern was that this wasn't even discussed at all.

>> Quickly scanning the code made it seem OK, all I would suggest not using
>> the README for both the repository README file and the manual.  Also, if
>> possible I'd avoid tracking the generated .info file in the repository
>> itself.
>
> I removed the generated .info files now from both repositories and
> generate them now through the ELPA build process.

1+

> I haven't split the README and the manual just yet. It's done in the
> same way as in the plz repository. I would actually prefer to have this
> also shown on the README.
>
> Why do you suggest splitting them? What are the benefits of it?

The different files have different audiences.  I'd say:

- The README is an introduction to anyone who just checked out a
  repository (or found it on some Website), and wants to know what it is
  about.  It should just be a starting point, linking to other resources
  (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
  possible.

- The documentation is for people who have installed a package and want
  to know the exact details of how something works or is done.  It is
  not something that would usually interest someone who hasn't
  downloaded and installed a package.

- The package description (C-h P foo RET) is a brief explanation of what
  a package does and provides.  It should focus on the questions the
  user might have when they first encounter the package:

  * If the name is not indicative, what is the package even about.
  
  * What is the core functionality and how is it used.

  * Who is the target audience.

  * What are the entry points to the package.

  * What differentiates the package from other similar packages.

  or other questions like these.  It should NOT include:

  * A table of contents

  * Installation instructions of any kind (there is a install button in
    the package description buffer)

  * Extensive details on how to configure the package

  * Screenshots, as these are currently not displayed

  * Changelog information

  and instead try and to keep it short and simple.  It is just a sales
  pitch, not a lecture.

Sadly a number of packages just use the same README.org file for all
these things, confusing the separate audiences.  If anything, it is
acceptable to mix the first two, but the third should certainly not
result in a 500+ line buffer (as is currently the case with "plz").  The
easiest way to address the last point is just to use the commentary
section in the main file to generate the description of the package,
which we can configure in elpa.git.

-- 
	Philip Kaludercic on peregrine

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Roman Scherer]

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


Hi Philip,

Philip Kaludercic <philipk@posteo.net> writes:

>
> The different files have different audiences.  I'd say:
>
> - The README is an introduction to anyone who just checked out a
>   repository (or found it on some Website), and wants to know what it is
>   about.  It should just be a starting point, linking to other resources
>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>   possible.
>
> - The documentation is for people who have installed a package and want
>   to know the exact details of how something works or is done.  It is
>   not something that would usually interest someone who hasn't
>   downloaded and installed a package.
>
> - The package description (C-h P foo RET) is a brief explanation of what
>   a package does and provides.  It should focus on the questions the
>   user might have when they first encounter the package:
>
>   * If the name is not indicative, what is the package even about.
>   
>   * What is the core functionality and how is it used.
>
>   * Who is the target audience.
>
>   * What are the entry points to the package.
>
>   * What differentiates the package from other similar packages.
>
>   or other questions like these.  It should NOT include:
>
>   * A table of contents
>
>   * Installation instructions of any kind (there is a install button in
>     the package description buffer)
>
>   * Extensive details on how to configure the package
>
>   * Screenshots, as these are currently not displayed
>
>   * Changelog information
>
>   and instead try and to keep it short and simple.  It is just a sales
>   pitch, not a lecture.
>
> Sadly a number of packages just use the same README.org file for all
> these things, confusing the separate audiences.  If anything, it is
> acceptable to mix the first two, but the third should certainly not
> result in a 500+ line buffer (as is currently the case with "plz").  The
> easiest way to address the last point is just to use the commentary
> section in the main file to generate the description of the package,
> which we can configure in elpa.git.

Ok, thanks for the explanation. I will then split the README and the
manual up. I will do this in the next days.

I looked a bit around and will probably do something similar to what
Protesilaos does in his packages. This one being an example:

https://github.com/protesilaos/ef-themes

Roman

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Philip Kaludercic]

Roman Scherer <roman.scherer@burningswell.com> writes:

> Hi Philip,
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
>>
>> The different files have different audiences.  I'd say:
>>
>> - The README is an introduction to anyone who just checked out a
>>   repository (or found it on some Website), and wants to know what it is
>>   about.  It should just be a starting point, linking to other resources
>>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>>   possible.
>>
>> - The documentation is for people who have installed a package and want
>>   to know the exact details of how something works or is done.  It is
>>   not something that would usually interest someone who hasn't
>>   downloaded and installed a package.
>>
>> - The package description (C-h P foo RET) is a brief explanation of what
>>   a package does and provides.  It should focus on the questions the
>>   user might have when they first encounter the package:
>>
>>   * If the name is not indicative, what is the package even about.
>>   
>>   * What is the core functionality and how is it used.
>>
>>   * Who is the target audience.
>>
>>   * What are the entry points to the package.
>>
>>   * What differentiates the package from other similar packages.
>>
>>   or other questions like these.  It should NOT include:
>>
>>   * A table of contents
>>
>>   * Installation instructions of any kind (there is a install button in
>>     the package description buffer)
>>
>>   * Extensive details on how to configure the package
>>
>>   * Screenshots, as these are currently not displayed
>>
>>   * Changelog information
>>
>>   and instead try and to keep it short and simple.  It is just a sales
>>   pitch, not a lecture.
>>
>> Sadly a number of packages just use the same README.org file for all
>> these things, confusing the separate audiences.  If anything, it is
>> acceptable to mix the first two, but the third should certainly not
>> result in a 500+ line buffer (as is currently the case with "plz").  The
>> easiest way to address the last point is just to use the commentary
>> section in the main file to generate the description of the package,
>> which we can configure in elpa.git.
>
> Ok, thanks for the explanation. I will then split the README and the
> manual up. I will do this in the next days.

OK, I can add the packages to elpa.git in the meantime.

> I looked a bit around and will probably do something similar to what
> Protesilaos does in his packages. This one being an example:
>
> https://github.com/protesilaos/ef-themes

If I am not mixing something up, I think I recommended something along
the lines I wrote above to him as well ^^

> Roman
>

-- 
	Philip Kaludercic on peregrine

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Roman Scherer]

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


Hi Philip,

ok, perfect. Thanks for your help on this!

Roman

Philip Kaludercic <philipk@posteo.net> writes:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
>> Hi Philip,
>>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>>
>>> The different files have different audiences.  I'd say:
>>>
>>> - The README is an introduction to anyone who just checked out a
>>>   repository (or found it on some Website), and wants to know what it is
>>>   about.  It should just be a starting point, linking to other resources
>>>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>>>   possible.
>>>
>>> - The documentation is for people who have installed a package and want
>>>   to know the exact details of how something works or is done.  It is
>>>   not something that would usually interest someone who hasn't
>>>   downloaded and installed a package.
>>>
>>> - The package description (C-h P foo RET) is a brief explanation of what
>>>   a package does and provides.  It should focus on the questions the
>>>   user might have when they first encounter the package:
>>>
>>>   * If the name is not indicative, what is the package even about.
>>>   
>>>   * What is the core functionality and how is it used.
>>>
>>>   * Who is the target audience.
>>>
>>>   * What are the entry points to the package.
>>>
>>>   * What differentiates the package from other similar packages.
>>>
>>>   or other questions like these.  It should NOT include:
>>>
>>>   * A table of contents
>>>
>>>   * Installation instructions of any kind (there is a install button in
>>>     the package description buffer)
>>>
>>>   * Extensive details on how to configure the package
>>>
>>>   * Screenshots, as these are currently not displayed
>>>
>>>   * Changelog information
>>>
>>>   and instead try and to keep it short and simple.  It is just a sales
>>>   pitch, not a lecture.
>>>
>>> Sadly a number of packages just use the same README.org file for all
>>> these things, confusing the separate audiences.  If anything, it is
>>> acceptable to mix the first two, but the third should certainly not
>>> result in a 500+ line buffer (as is currently the case with "plz").  The
>>> easiest way to address the last point is just to use the commentary
>>> section in the main file to generate the description of the package,
>>> which we can configure in elpa.git.
>>
>> Ok, thanks for the explanation. I will then split the README and the
>> manual up. I will do this in the next days.
>
> OK, I can add the packages to elpa.git in the meantime.
>
>> I looked a bit around and will probably do something similar to what
>> Protesilaos does in his packages. This one being an example:
>>
>> https://github.com/protesilaos/ef-themes
>
> If I am not mixing something up, I think I recommended something along
> the lines I wrote above to him as well ^^
>
>> Roman
>>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised

[Philip Kaludercic]

Roman Scherer <roman.scherer@burningswell.com> writes:

> Hi Philip,
>
> ok, perfect. Thanks for your help on this!

Can you just tell me what the names of the manual files will be?  Also,
if possible it would be better if you could track the files to ingore
inside the repository using a .elpaignore file (I just noticed the
patches now, so I didn't see what you were proposing until now).

> Roman
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Roman Scherer <roman.scherer@burningswell.com> writes:
>>
>>> Hi Philip,
>>>
>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>
>>>>
>>>> The different files have different audiences.  I'd say:
>>>>
>>>> - The README is an introduction to anyone who just checked out a
>>>>   repository (or found it on some Website), and wants to know what it is
>>>>   about.  It should just be a starting point, linking to other resources
>>>>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>>>>   possible.
>>>>
>>>> - The documentation is for people who have installed a package and want
>>>>   to know the exact details of how something works or is done.  It is
>>>>   not something that would usually interest someone who hasn't
>>>>   downloaded and installed a package.
>>>>
>>>> - The package description (C-h P foo RET) is a brief explanation of what
>>>>   a package does and provides.  It should focus on the questions the
>>>>   user might have when they first encounter the package:
>>>>
>>>>   * If the name is not indicative, what is the package even about.
>>>>   
>>>>   * What is the core functionality and how is it used.
>>>>
>>>>   * Who is the target audience.
>>>>
>>>>   * What are the entry points to the package.
>>>>
>>>>   * What differentiates the package from other similar packages.
>>>>
>>>>   or other questions like these.  It should NOT include:
>>>>
>>>>   * A table of contents
>>>>
>>>>   * Installation instructions of any kind (there is a install button in
>>>>     the package description buffer)
>>>>
>>>>   * Extensive details on how to configure the package
>>>>
>>>>   * Screenshots, as these are currently not displayed
>>>>
>>>>   * Changelog information
>>>>
>>>>   and instead try and to keep it short and simple.  It is just a sales
>>>>   pitch, not a lecture.
>>>>
>>>> Sadly a number of packages just use the same README.org file for all
>>>> these things, confusing the separate audiences.  If anything, it is
>>>> acceptable to mix the first two, but the third should certainly not
>>>> result in a 500+ line buffer (as is currently the case with "plz").  The
>>>> easiest way to address the last point is just to use the commentary
>>>> section in the main file to generate the description of the package,
>>>> which we can configure in elpa.git.
>>>
>>> Ok, thanks for the explanation. I will then split the README and the
>>> manual up. I will do this in the next days.
>>
>> OK, I can add the packages to elpa.git in the meantime.
>>
>>> I looked a bit around and will probably do something similar to what
>>> Protesilaos does in his packages. This one being an example:
>>>
>>> https://github.com/protesilaos/ef-themes
>>
>> If I am not mixing something up, I think I recommended something along
>> the lines I wrote above to him as well ^^
>>
>>> Roman
>>>
>

-- 
	Philip Kaludercic on peregrine

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised

[Roman Scherer]

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

Hi Philip,

let me try to come up with 2 new patches once I split the README. I will
also add the ignored files to .elpaignore and test it again there.

Roman

On Mon, Apr 29, 2024, 20:24 Philip Kaludercic <philipk@posteo.net> wrote:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
> > Hi Philip,
> >
> > ok, perfect. Thanks for your help on this!
>
> Can you just tell me what the names of the manual files will be?  Also,
> if possible it would be better if you could track the files to ingore
> inside the repository using a .elpaignore file (I just noticed the
> patches now, so I didn't see what you were proposing until now).
>
> > Roman
> >
> > Philip Kaludercic <philipk@posteo.net> writes:
> >
> >> Roman Scherer <roman.scherer@burningswell.com> writes:
> >>
> >>> Hi Philip,
> >>>
> >>> Philip Kaludercic <philipk@posteo.net> writes:
> >>>
> >>>>
> >>>> The different files have different audiences.  I'd say:
> >>>>
> >>>> - The README is an introduction to anyone who just checked out a
> >>>>   repository (or found it on some Website), and wants to know what it
> is
> >>>>   about.  It should just be a starting point, linking to other
> resources
> >>>>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
> >>>>   possible.
> >>>>
> >>>> - The documentation is for people who have installed a package and
> want
> >>>>   to know the exact details of how something works or is done.  It is
> >>>>   not something that would usually interest someone who hasn't
> >>>>   downloaded and installed a package.
> >>>>
> >>>> - The package description (C-h P foo RET) is a brief explanation of
> what
> >>>>   a package does and provides.  It should focus on the questions the
> >>>>   user might have when they first encounter the package:
> >>>>
> >>>>   * If the name is not indicative, what is the package even about.
> >>>>
> >>>>   * What is the core functionality and how is it used.
> >>>>
> >>>>   * Who is the target audience.
> >>>>
> >>>>   * What are the entry points to the package.
> >>>>
> >>>>   * What differentiates the package from other similar packages.
> >>>>
> >>>>   or other questions like these.  It should NOT include:
> >>>>
> >>>>   * A table of contents
> >>>>
> >>>>   * Installation instructions of any kind (there is a install button
> in
> >>>>     the package description buffer)
> >>>>
> >>>>   * Extensive details on how to configure the package
> >>>>
> >>>>   * Screenshots, as these are currently not displayed
> >>>>
> >>>>   * Changelog information
> >>>>
> >>>>   and instead try and to keep it short and simple.  It is just a sales
> >>>>   pitch, not a lecture.
> >>>>
> >>>> Sadly a number of packages just use the same README.org file for all
> >>>> these things, confusing the separate audiences.  If anything, it is
> >>>> acceptable to mix the first two, but the third should certainly not
> >>>> result in a 500+ line buffer (as is currently the case with "plz").
> The
> >>>> easiest way to address the last point is just to use the commentary
> >>>> section in the main file to generate the description of the package,
> >>>> which we can configure in elpa.git.
> >>>
> >>> Ok, thanks for the explanation. I will then split the README and the
> >>> manual up. I will do this in the next days.
> >>
> >> OK, I can add the packages to elpa.git in the meantime.
> >>
> >>> I looked a bit around and will probably do something similar to what
> >>> Protesilaos does in his packages. This one being an example:
> >>>
> >>> https://github.com/protesilaos/ef-themes
> >>
> >> If I am not mixing something up, I think I recommended something along
> >> the lines I wrote above to him as well ^^
> >>
> >>> Roman
> >>>
> >
>
> --
>         Philip Kaludercic on peregrine
>

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

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised

[Roman Scherer]

[-- Attachment #1.1: Type: text/plain, Size: 1215 bytes --]


Hi Philip,

I splitted the README and the manual. I attached 2 new patches which I
created from adding the packages to the elpa repository locally.

I also declare the ignored files now in the .elpaignore file of the
repositories.

The tarballs now cintain this:

 -rw-rw-r--   roman/roman     30814 plz-media-type-0.1pre0.20240501.111146/plz-media-type.el
 -rw-rw-r--   roman/roman      1825 plz-media-type-0.1pre0.20240501.111146/README-elpa
 -rw-rw-r--   roman/roman       429 plz-media-type-0.1pre0.20240501.111146/plz-media-type-pkg.el
 -rw-rw-r--   roman/roman      1329 plz-media-type-0.1pre0.20240501.111146/README.org
 -rw-rw-r--   roman/roman     19165 plz-media-type-0.1pre0.20240501.111146/plz-media-type.info

 -rw-rw-r--   roman/roman      4390 plz-event-source-0.1pre0.20240501.111443/plz-event-source.info
 -rw-rw-r--   roman/roman      1689 plz-event-source-0.1pre0.20240501.111443/README-elpa
 -rw-rw-r--   roman/roman      1140 plz-event-source-0.1pre0.20240501.111443/README.org
 -rw-rw-r--   roman/roman     18249 plz-event-source-0.1pre0.20240501.111443/plz-event-source.el
 -rw-rw-r--   roman/roman       436 plz-event-source-0.1pre0.20240501.111443/plz-event-source-pkg.el

Thanks, Roman.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: v2-0001-Add-plz-media-type.patch --]
[-- Type: text/x-diff, Size: 852 bytes --]

From cc4ccc8bf5a66e30ba40d3b0d355284ad26d5243 Mon Sep 17 00:00:00 2001
Message-ID: <cc4ccc8bf5a66e30ba40d3b0d355284ad26d5243.1714562298.git.roman@burningswell.com>
From: Roman Scherer <roman@burningswell.com>
Date: Sun, 28 Apr 2024 14:35:20 +0200
Subject: [PATCH v2 1/2] Add plz-media-type

---
 elpa-packages | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 4a0c1bd..a56cc6f 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -587,6 +587,8 @@
   :release-branch "stable"
   :ignored-files ("LICENSE")
   :doc "README.org")
+ (plz-media-type        :url "https://github.com/r0man/plz-media-type"
+  :doc "plz-media-type.org")
  (plz-see		:url "https://github.com/astoff/plz-see.el"
   :readme "README.org")
  (poke			:url "https://git.savannah.gnu.org/git/poke/poke-el.git"
-- 
2.41.0


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.3: v2-0002-Add-plz-event-source.patch --]
[-- Type: text/x-diff, Size: 1059 bytes --]

From 1ba92029324d61a1457df8c1540e3bc73debb7e3 Mon Sep 17 00:00:00 2001
Message-ID: <1ba92029324d61a1457df8c1540e3bc73debb7e3.1714562298.git.roman@burningswell.com>
In-Reply-To: <cc4ccc8bf5a66e30ba40d3b0d355284ad26d5243.1714562298.git.roman@burningswell.com>
References: <cc4ccc8bf5a66e30ba40d3b0d355284ad26d5243.1714562298.git.roman@burningswell.com>
From: Roman Scherer <roman@burningswell.com>
Date: Sun, 28 Apr 2024 14:35:51 +0200
Subject: [PATCH v2 2/2] Add plz-event-source

---
 elpa-packages | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index a56cc6f..c4c1d56 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -587,6 +587,8 @@
   :release-branch "stable"
   :ignored-files ("LICENSE")
   :doc "README.org")
+ (plz-event-source        :url "https://github.com/r0man/plz-event-source"
+  :doc "plz-event-source.org")
  (plz-media-type        :url "https://github.com/r0man/plz-media-type"
   :doc "plz-media-type.org")
  (plz-see		:url "https://github.com/astoff/plz-see.el"
-- 
2.41.0


[-- Attachment #1.4: Type: text/plain, Size: 3519 bytes --]


Philip Kaludercic <philipk@posteo.net> writes:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
>> Hi Philip,
>>
>> ok, perfect. Thanks for your help on this!
>
> Can you just tell me what the names of the manual files will be?  Also,
> if possible it would be better if you could track the files to ingore
> inside the repository using a .elpaignore file (I just noticed the
> patches now, so I didn't see what you were proposing until now).
>
>> Roman
>>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>> Roman Scherer <roman.scherer@burningswell.com> writes:
>>>
>>>> Hi Philip,
>>>>
>>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>>
>>>>>
>>>>> The different files have different audiences.  I'd say:
>>>>>
>>>>> - The README is an introduction to anyone who just checked out a
>>>>>   repository (or found it on some Website), and wants to know what it is
>>>>>   about.  It should just be a starting point, linking to other resources
>>>>>   (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>>>>>   possible.
>>>>>
>>>>> - The documentation is for people who have installed a package and want
>>>>>   to know the exact details of how something works or is done.  It is
>>>>>   not something that would usually interest someone who hasn't
>>>>>   downloaded and installed a package.
>>>>>
>>>>> - The package description (C-h P foo RET) is a brief explanation of what
>>>>>   a package does and provides.  It should focus on the questions the
>>>>>   user might have when they first encounter the package:
>>>>>
>>>>>   * If the name is not indicative, what is the package even about.
>>>>>   
>>>>>   * What is the core functionality and how is it used.
>>>>>
>>>>>   * Who is the target audience.
>>>>>
>>>>>   * What are the entry points to the package.
>>>>>
>>>>>   * What differentiates the package from other similar packages.
>>>>>
>>>>>   or other questions like these.  It should NOT include:
>>>>>
>>>>>   * A table of contents
>>>>>
>>>>>   * Installation instructions of any kind (there is a install button in
>>>>>     the package description buffer)
>>>>>
>>>>>   * Extensive details on how to configure the package
>>>>>
>>>>>   * Screenshots, as these are currently not displayed
>>>>>
>>>>>   * Changelog information
>>>>>
>>>>>   and instead try and to keep it short and simple.  It is just a sales
>>>>>   pitch, not a lecture.
>>>>>
>>>>> Sadly a number of packages just use the same README.org file for all
>>>>> these things, confusing the separate audiences.  If anything, it is
>>>>> acceptable to mix the first two, but the third should certainly not
>>>>> result in a 500+ line buffer (as is currently the case with "plz").  The
>>>>> easiest way to address the last point is just to use the commentary
>>>>> section in the main file to generate the description of the package,
>>>>> which we can configure in elpa.git.
>>>>
>>>> Ok, thanks for the explanation. I will then split the README and the
>>>> manual up. I will do this in the next days.
>>>
>>> OK, I can add the packages to elpa.git in the meantime.
>>>
>>>> I looked a bit around and will probably do something similar to what
>>>> Protesilaos does in his packages. This one being an example:
>>>>
>>>> https://github.com/protesilaos/ef-themes
>>>
>>> If I am not mixing something up, I think I recommended something along
>>> the lines I wrote above to him as well ^^
>>>
>>>> Roman
>>>>
>>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised

[Philip Kaludercic]

Roman Scherer <roman.scherer@burningswell.com> writes:

> Hi Philip,
>
> I splitted the README and the manual. I attached 2 new patches which I
> created from adding the packages to the elpa repository locally.
>
> I also declare the ignored files now in the .elpaignore file of the
> repositories.
>
> The tarballs now cintain this:
>
>  -rw-rw-r--   roman/roman     30814 plz-media-type-0.1pre0.20240501.111146/plz-media-type.el
>  -rw-rw-r--   roman/roman      1825 plz-media-type-0.1pre0.20240501.111146/README-elpa
>  -rw-rw-r--   roman/roman       429 plz-media-type-0.1pre0.20240501.111146/plz-media-type-pkg.el
>  -rw-rw-r--   roman/roman      1329 plz-media-type-0.1pre0.20240501.111146/README.org
>  -rw-rw-r--   roman/roman     19165 plz-media-type-0.1pre0.20240501.111146/plz-media-type.info
>
>  -rw-rw-r--   roman/roman      4390 plz-event-source-0.1pre0.20240501.111443/plz-event-source.info
>  -rw-rw-r--   roman/roman      1689 plz-event-source-0.1pre0.20240501.111443/README-elpa
>  -rw-rw-r--   roman/roman      1140 plz-event-source-0.1pre0.20240501.111443/README.org
>  -rw-rw-r--   roman/roman     18249 plz-event-source-0.1pre0.20240501.111443/plz-event-source.el
>  -rw-rw-r--   roman/roman       436 plz-event-source-0.1pre0.20240501.111443/plz-event-source-pkg.el
>
> Thanks, Roman.

Thank you, I have applied and pushed your patches to elpa.git (note that
I changed the message to conform with the usual commit style).  The
packages should appear on GNU ELPA a few hours after you update the
Version header as discussed before.

-- 
	Philip Kaludercic on peregrine

Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised

[Roman Scherer]

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

Perfect. Thank you!

On Wed, May 1, 2024, 13:56 Philip Kaludercic <philipk@posteo.net> wrote:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
> > Hi Philip,
> >
> > I splitted the README and the manual. I attached 2 new patches which I
> > created from adding the packages to the elpa repository locally.
> >
> > I also declare the ignored files now in the .elpaignore file of the
> > repositories.
> >
> > The tarballs now cintain this:
> >
> >  -rw-rw-r--   roman/roman     30814
> plz-media-type-0.1pre0.20240501.111146/plz-media-type.el
> >  -rw-rw-r--   roman/roman      1825
> plz-media-type-0.1pre0.20240501.111146/README-elpa
> >  -rw-rw-r--   roman/roman       429
> plz-media-type-0.1pre0.20240501.111146/plz-media-type-pkg.el
> >  -rw-rw-r--   roman/roman      1329
> plz-media-type-0.1pre0.20240501.111146/README.org
> >  -rw-rw-r--   roman/roman     19165
> plz-media-type-0.1pre0.20240501.111146/plz-media-type.info
> >
> >  -rw-rw-r--   roman/roman      4390
> plz-event-source-0.1pre0.20240501.111443/plz-event-source.info
> >  -rw-rw-r--   roman/roman      1689
> plz-event-source-0.1pre0.20240501.111443/README-elpa
> >  -rw-rw-r--   roman/roman      1140
> plz-event-source-0.1pre0.20240501.111443/README.org
> >  -rw-rw-r--   roman/roman     18249
> plz-event-source-0.1pre0.20240501.111443/plz-event-source.el
> >  -rw-rw-r--   roman/roman       436
> plz-event-source-0.1pre0.20240501.111443/plz-event-source-pkg.el
> >
> > Thanks, Roman.
>
> Thank you, I have applied and pushed your patches to elpa.git (note that
> I changed the message to conform with the usual commit style).  The
> packages should appear on GNU ELPA a few hours after you update the
> Version header as discussed before.
>
> --
>         Philip Kaludercic on peregrine
>

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