From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12169 invoked by alias); 14 Oct 2017 14:45:03 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 41892 Received: (qmail 25353 invoked by uid 1010); 14 Oct 2017 14:45:03 -0000 X-Qmail-Scanner-Diagnostics: from mail-oi0-f66.google.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.99.2/21882. spamassassin: 3.4.1. Clear:RC:0(209.85.218.66):SA:0(-1.4/5.0):. Processed in 3.528953 secs); 14 Oct 2017 14:45:03 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-1.4 required=5.0 tests=BAYES_00,FREEMAIL_FROM, HTML_MESSAGE,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL, RCVD_IN_SORBS_SPAM,SPF_PASS,T_DKIM_INVALID autolearn=no autolearn_force=no version=3.4.1 X-Envelope-From: julien.nicoulaud@gmail.com X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:in-reply-to:references:from:date:message-id:subject:to; bh=0FX+W+1xlVYxq86oAmf6yOODy87BMuIQcMFLTyxASSo=; b=TrEs2uo4QhezTPdKenwrxA/j3xL4obKGupcOCQGVG4tn6lAdZ1q4xtVvV8TbW8ypRW zFP0GSGOcGoJypJDGBykwynxxmQ3puylYSaLzKHsIFxZTd1C6xrPTKrY0E++hFKqPJEZ FCqZfgrhPgXHr1SnsOruwcycnztRLBHheW0DvvSaxlVCRxZhNk2ToKUOa7i6JA9pXgDn Y4m+yVbUNzxKAQxbbCrm2CNscUL3INOpC2N1KeB9SK6oauvJMED9BUxT1lP3z6TqdX+/ PjCW8JXDxbxjUe/l6S+7sBVmw7VXWtXkbXQJaazlQS9y33dX1EeV/WcmOLOGV4LC5udk 5fRQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to; bh=0FX+W+1xlVYxq86oAmf6yOODy87BMuIQcMFLTyxASSo=; b=LTpDFp05g524fTDzm4J3KD2yQioLLukxQtyCBS0dCV9a+eqEBhTveceJmJarhotKRI 4zmszSUYOkcP9V0tOnBH6aVCAcbOJys7qzQvrOG4FtjAuCc41l2Tz+Mu0hqoE/KSqsmJ 7OgXMjQQ1y7l7ZuFG56wkyuf8xuHZAP3LgYsptPdFRUcZn6xkl0Tgis9pjcVCUm9Bw2G T3MANeO5wnZfcmFEf7HSkXm2GCiAklPMuX0HGpIBuvFov2Zj28OZEFaq1tw43DId1q0x nWh9FG+UaPw1ElxBuHbVurzJ07b1BRMDKgp/ZOMWnuJ1524pWu8h5QLDxuweu0/wJAgE cuMQ== X-Gm-Message-State: AMCzsaWxlj41jDKwtVlOrbQhhOyO4/mea/JwD1Nw3Nmw6GI8hnqPUh83 JjrO46SPzjUn94/QZ5eeIV29jINZpYk7i1plTVOuJGn8 X-Google-Smtp-Source: ABhQp+RZRfxpMIdMAWxWuZEIA0/mgCRcdsLLyP6CISkIwkt/T5obQPYzRi3n2jIXODKim6+d8nkyHCjhMcisVOrPX6g= X-Received: by 10.202.173.203 with SMTP id w194mr2735353oie.305.1507992296239; Sat, 14 Oct 2017 07:44:56 -0700 (PDT) MIME-Version: 1.0 In-Reply-To: <7240.1507973844@thecus.kiddle.eu> References: <7240.1507973844@thecus.kiddle.eu> From: Julien Nicoulaud Date: Sat, 14 Oct 2017 16:44:15 +0200 Message-ID: Subject: Re: GH:zsh-users/zsh-completions. To: Oliver Kiddle , Mailing-list zsh-workers , zsh-workers@closedmail.org Content-Type: multipart/alternative; boundary="001a113cf59c2438e7055b82d1ef" --001a113cf59c2438e7055b82d1ef Content-Type: text/plain; charset="UTF-8" Hi Oliver, Thanks for reaching out to me, those are some valid points and I have been aware of the issues with this repo for a long time, but could not really find the time to address it, sorry about that. I added zsh-workers in copy, I hope you don't mind. zsh-completions started eight years ago now, with zsh-syntax-highlighting. Those were just some personal experimentations, but at some points both started to get a bit a popularity, so I decided to try to make it "community" projects and moved it to an organization. Both projects continued evolving from this point and got many contributions, and that is pretty much it, there is no agenda. As a side note, I named the organization "zsh-users" and I realized after a while this was a poor choice, as it sounds too "official". Many users get confused and think this is part of the zsh project (especially with the git mirror of the zsh repo). I am open to suggestions regarding this, and if the zsh team wants me to rename the org, I will do it. Anyway, a few thoughts about zsh-completions: - I believe the release rythm of zsh (~once a year) is a bit too slow for completions. We do ~monthly releases, and I think most users importing it via a "plugin manager" actually directly use the master branch, which is fine IMHO for completions. By the time a compdef lands in a zsh release, it can be already obsolete or need bugfixes. I think this is the biggest point for having compdefs in a separate repo than the shell itself. - I believe a significant part of the contributions we had were because the project is hosted on github. It attracts an audience of contributors that are not familiar with the "classic way" (mailing list, IRC, patches, and different process for a each project), and it makes it very easy for "drive-by" contributions and learning by example, which fits well to completions. It also easy to review/provide feedback and iterate on patches (eg: https://github.com/zsh-users/zsh-completions/pull/512) - The initial idea was indeed for zsh-completions to be an "incubator", and contribute the compdefs on the mailing-list. The previous point also applies to me, it asks me more work to extract a compdef from the repo, create a patch against zsh, send it to the mailing list, and follow up. I do not spend a lot of time on this project, and I quickly realized that was not something I would be able to do on a regular basis, so I did not do it at all. - If I send a compdef to zsh, what happens then ? We have to wait a least for the next release of zsh to delete it from zsh-completions. But then, not all distros update to the latest release of zsh, or the compdef could have evolved in zsh-completions in the meanwhile, so I can see this could be become quite a headache to manage (for users as well). - zsh-completions has a lower quality standard than the completions in zsh itself. For instance, some compdefs are partial, some compdefs use awk/grep/sed/tr instead of the shell builtins, some compdefs use the low level API (compadd, etc) instead of the high level one. We often accept it as "better than nothing". - Some completions are for projects with a very small userbase. Do we really want to bloat the zsh repo, and user installations with hundreds of compdefs they don't use ? - I do not have a strong opinion about licensing. I used this rule because we got many pull requests from people just copy-pasting someone else's work without any attribution. I think your proposition is good, we can use the Zsh license as the default one. - My opinion about including completions directly in the upstream project is mixed. Either the project already does it, and this is fine. But in my experience, when they do not by themselves, contributing a compdef often results in endless discussions in bug trackers and poor maintainance... IMHO, to write a completion, the knowledge of zsh is more important than the knowledge of the command itself, so it feels natural to me that completions are written by "zsh experts" rather than "project XXXX experts". Another point against completions in upstream project is that it makes work a bit harder for packaging (for instance, there is no real clean way to handle this in python's setup.py, so each project ends with a more or less custom solution). So the main points are: - release cycle different than zsh's one - newbie/occasional/one time contributor friendly thanks to: - github - lower quality standard Here are some ideas to improve things: - Get some core zsh contributors involved in zsh-completions - Split completions from the main zsh repo to another one, with: 1. frequent, regular releases 2. some clear guidelines for contributing compdefs, and for becoming a patch reviewer 3. github contributing workflow (either by hosting it on github, or auto-posting patches from a github mirror, etc) This idea of having a "zsh-contrib" repo actually applies to more than just completions: prompts, ZLE widgets, etc. - (slightly unrelated) Improve the tooling around completions: 1. Maybe define some standard metadatas that can be included in compdefs, and that can be exploited by other tooling (eg: version of program) 2. I could see your project used to build a permanent webapp/dashboard, with the status for each command (does it have a completion ? where ? for which version ?). 3. Work on tooling to lint and unit test completions (eg to invoke a compdef programatically, and return matches in an array). I have some unpushed stuff I started working on for zsh-completions, to run basic checks on pull requests. I realize that's a lot of points, but I hope it helps moving things forward :) Cheers, Julien 2017-10-14 11:37 GMT+02:00 Oliver Kiddle : > I'm one of the people who regularly maintain the completion functions > distributed with zsh. I've been aware of your function collection on > github for a while and I think it would be worth giving some thoughts to > how we can best improve the completion situation for zsh as a whole. > > Right at the start of README.md is the assertion that "scripts are meant > to be contributed to the Zsh project when stable enough". As far as I > can tell there hasn't been much, or even any, flow of functions to zsh. > > I'll start by pointing out something which is perhaps a minor nitpick: > licensing. You encourage people to include a license which is good but > if eventual inclusion in zsh is an aim then why not encourage the use > of the zsh license. Above any arguments about copyleft vs. permissive > licences, I always prefer to keep things simple by sticking to whatever > licence a project is currently using. I know Peter has accepted some > functions with alternate licenses but I'm not fond it. It's also sort > of ugly having a license at the top of every file. Why not nominate > the zsh licence as the default license and include a LICENSE file for > it. Then simply state that where a function deviates from it that it > should include its own license. If the intention is to include it in the > upstream project then their license should be preferred. > > One of the problems when people contribute a function, either to zsh, > zsh-users/zsh-completions, or some other project is that they often view > it as a job done and never bother to come back with improvements or > fixes. An advantage of keeping them in the author's own github repo is > that they might be more inclined to maintain it. The disadvantage is > that it is harder for users to find, especially if there are multiple > forks. Perhaps something like git submodules or subtree could be used to > link them in from a master repository? > > I've experimented with contributing some functions upstream over the > past year. Sometimes it works great and the function gets updated by the > people who know the upstream command best. All too often it gets little > attention or my pull requests sit ignored. A staging repository such as > zsh-completions could be good as a temporary home for these. > > I'm also concerned about how much feedback people get. Or more > specifically encouraging a one-time committer to become more involved > while also improving the quality of each newly submitted function by > making a few iterations right at the beginning. We've not always done a > great job on zsh-workers but the people best placed to give feedback are > there. > > Did you create zsh-completions in the first place or did you > inherit it? If so, why? - as opposed to sending contributions to the > mailing list. > > If you're not aware of it, I'll just mention > https://github.com/okapia/zsh-helpoutput > I had been keeping the output of --help for commands in CVS going back > years. The idea is to automate detection of changes in upstream > commands. Things had got fairly bad but I've been trying to get the > functions included in zsh into better shape. > > I'd be interested in any ideas you may have on how we can do things > better. > > Oliver > --001a113cf59c2438e7055b82d1ef--