From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized Date: Mon, 29 Apr 2024 06:09:42 +0000 Message-ID: <87r0eon1i1.fsf@posteo.net> References: <87h6fnmb4b.fsf@burningswell.com> <87frv6q5t5.fsf@posteo.net> <87o79ttzma.fsf@burningswell.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20894"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org, ahyatt@gmail.com To: Roman Scherer Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Apr 29 08:11:01 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1s1KE8-00057T-O1 for ged-emacs-devel@m.gmane-mx.org; Mon, 29 Apr 2024 08:11:00 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s1KD7-000830-Iw; Mon, 29 Apr 2024 02:09:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s1KD4-00082h-7o for emacs-devel@gnu.org; Mon, 29 Apr 2024 02:09:54 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s1KCx-0007SD-DY for emacs-devel@gnu.org; Mon, 29 Apr 2024 02:09:53 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id E87EB240029 for ; Mon, 29 Apr 2024 08:09:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1714370983; bh=zxtAKYi14gZotIN8b5R4ub6G6obGIut005PsY1g8oPE=; h=From:To:Cc:Subject:OpenPGP:Date:Message-ID:MIME-Version: Content-Type:From; b=BY+pmfnL5roIt8P5hxjEcTIIptQ6wmZtwqxlh4LKo4nnanYFvcoOA1dj3zIzH4iJA lKE5ro9zbvFePwcj9DNMdxCFr8w5Nm5ZSM3wf4GG5R6vTi8N0um2Kjv8NnQ3dJbm/5 yiWpS+u+LNo1916JBNiZVvdfBog9C8ynXvHNP0+xpjfzgqbYC0+ailJwt2fL8+HQPP sr5JYvUAQbpdqvkOJaVEoOwxcT+dZUHsjL1RCuUVyN7Zlk8NGTehjJaB4UNfCWnErc V7LynBSJdNlEgC0X+d8deFriG//yMBaDO9TIJ03E4ck70935ofe2Mbdc9Wp04T9/Rh NuknBxnJ2/DDQ== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VSXwk6nLkz9rxG; Mon, 29 Apr 2024 08:09:42 +0200 (CEST) In-Reply-To: <87o79ttzma.fsf@burningswell.com> (Roman Scherer's message of "Sun, 28 Apr 2024 14:56:13 +0200") OpenPGP: id=7126E1DE2F0CE35C770BED01F2C3CC513DB89F66; url="https://keys.openpgp.org/vks/v1/by-fingerprint/7126E1DE2F0CE35C770BED01F2C3CC513DB89F66"; preference=signencrypt Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:318311 Archived-At: Roman Scherer writes: > Hi Philip, > > thanks for answer. > > Philip Kaludercic writes: > >> Roman Scherer 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