* Add plz-media-type and plz-event-source to GNU ELPA when stabilized @ 2024-04-27 9:02 Roman Scherer 2024-04-27 13:43 ` Philip Kaludercic 0 siblings, 1 reply; 12+ messages in thread From: Roman Scherer @ 2024-04-27 9:02 UTC (permalink / raw) To: emacs-devel; +Cc: ahyatt [-- 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 --] ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-27 9:02 Add plz-media-type and plz-event-source to GNU ELPA when stabilized Roman Scherer @ 2024-04-27 13:43 ` Philip Kaludercic 2024-04-28 12:56 ` Roman Scherer 0 siblings, 1 reply; 12+ messages in thread From: Philip Kaludercic @ 2024-04-27 13:43 UTC (permalink / raw) To: Roman Scherer; +Cc: emacs-devel, ahyatt 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-27 13:43 ` Philip Kaludercic @ 2024-04-28 12:56 ` Roman Scherer 2024-04-29 6:09 ` Philip Kaludercic 0 siblings, 1 reply; 12+ messages in thread From: Roman Scherer @ 2024-04-28 12:56 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-28 12:56 ` Roman Scherer @ 2024-04-29 6:09 ` Philip Kaludercic 2024-04-29 7:44 ` Roman Scherer 0 siblings, 1 reply; 12+ messages in thread From: Philip Kaludercic @ 2024-04-29 6:09 UTC (permalink / raw) To: Roman Scherer; +Cc: emacs-devel, ahyatt 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-29 6:09 ` Philip Kaludercic @ 2024-04-29 7:44 ` Roman Scherer 2024-04-29 7:46 ` Philip Kaludercic 0 siblings, 1 reply; 12+ messages in thread From: Roman Scherer @ 2024-04-29 7:44 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-29 7:44 ` Roman Scherer @ 2024-04-29 7:46 ` Philip Kaludercic 2024-04-29 7:48 ` Roman Scherer 0 siblings, 1 reply; 12+ messages in thread From: Philip Kaludercic @ 2024-04-29 7:46 UTC (permalink / raw) To: Roman Scherer; +Cc: emacs-devel, ahyatt 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized 2024-04-29 7:46 ` Philip Kaludercic @ 2024-04-29 7:48 ` Roman Scherer 2024-04-29 18:24 ` Add plz-media-type and plz-event-source to GNU ELPA when stabilised Philip Kaludercic 0 siblings, 1 reply; 12+ messages in thread From: Roman Scherer @ 2024-04-29 7:48 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised 2024-04-29 7:48 ` Roman Scherer @ 2024-04-29 18:24 ` Philip Kaludercic 2024-04-29 20:17 ` Roman Scherer 2024-05-01 11:25 ` Roman Scherer 0 siblings, 2 replies; 12+ messages in thread From: Philip Kaludercic @ 2024-04-29 18:24 UTC (permalink / raw) To: Roman Scherer; +Cc: emacs-devel, ahyatt 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised 2024-04-29 18:24 ` Add plz-media-type and plz-event-source to GNU ELPA when stabilised Philip Kaludercic @ 2024-04-29 20:17 ` Roman Scherer 2024-05-01 11:25 ` Roman Scherer 1 sibling, 0 replies; 12+ messages in thread From: Roman Scherer @ 2024-04-29 20:17 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised 2024-04-29 18:24 ` Add plz-media-type and plz-event-source to GNU ELPA when stabilised Philip Kaludercic 2024-04-29 20:17 ` Roman Scherer @ 2024-05-01 11:25 ` Roman Scherer 2024-05-01 11:56 ` Philip Kaludercic 1 sibling, 1 reply; 12+ messages in thread From: Roman Scherer @ 2024-05-01 11:25 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised 2024-05-01 11:25 ` Roman Scherer @ 2024-05-01 11:56 ` Philip Kaludercic 2024-05-01 12:00 ` Roman Scherer 0 siblings, 1 reply; 12+ messages in thread From: Philip Kaludercic @ 2024-05-01 11:56 UTC (permalink / raw) To: Roman Scherer; +Cc: emacs-devel, ahyatt 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised 2024-05-01 11:56 ` Philip Kaludercic @ 2024-05-01 12:00 ` Roman Scherer 0 siblings, 0 replies; 12+ messages in thread From: Roman Scherer @ 2024-05-01 12:00 UTC (permalink / raw) To: Philip Kaludercic; +Cc: emacs-devel, ahyatt [-- 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 --] ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2024-05-01 12:00 UTC | newest] Thread overview: 12+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2024-04-27 9:02 Add plz-media-type and plz-event-source to GNU ELPA when stabilized Roman Scherer 2024-04-27 13:43 ` Philip Kaludercic 2024-04-28 12:56 ` Roman Scherer 2024-04-29 6:09 ` Philip Kaludercic 2024-04-29 7:44 ` Roman Scherer 2024-04-29 7:46 ` Philip Kaludercic 2024-04-29 7:48 ` Roman Scherer 2024-04-29 18:24 ` Add plz-media-type and plz-event-source to GNU ELPA when stabilised Philip Kaludercic 2024-04-29 20:17 ` Roman Scherer 2024-05-01 11:25 ` Roman Scherer 2024-05-01 11:56 ` Philip Kaludercic 2024-05-01 12:00 ` Roman Scherer
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).