Splitting sources into other repositories
willghatch opened this issue · 19 comments
Should we consider splitting sources off into other repositories?
We've gotten to the point where we have a lot, and while some are probably widely used (history, git, cdr maybe), others are probably less so. I've recently whipped up some quick sources for personal use (one for todoman, a few for mpd) that are probably a little too uncommonly used and maybe a little too rough to include in the main repository, but I would still like to share them with other users of zaw and those programs.
I think it might be good to include in the readme a solicitation for others to host their own sources and tell us the URLs of their repos, and then have a list of source URLs with descriptions of those sources. That way we could invite more participation without needing to make pull requests and without filling the main repo with lots of sources for programs that aren't often used, while also giving them some visibility.
What do you think, @termoshtt and other interested parties?
As an example of what such repos would look like, I put up my mpd sources here. We could conceivably have several such repos listed in the readme, especially for sources of programs that we the maintainers don't use (eg. we've had a PR for a docker source sitting around forever, but I have not felt motivated to learn docker just to test the source).
👍 Been sitting on a calibre source since forever 😄 .
👍
👍 Good idea.
eg. we've had a PR for a docker source sitting around forever, but I have not felt motivated to learn docker just to test the source
definitely.
In addition, we have no space to tell requirements for each sources as you write in mpd-source.
We could conceivably have several such repos listed in the readme,
We have several choices to list plugins.
For example, unite.vim project creates a wiki page to list plugins
unite-plugins(Japanese).
I cannot find the list for helm, but it has source for plugins.
i.e. we can find plugins in helm.
Since we have to make a commit to update README.md, it will be useful to use wiki page like unite.vim.
Helm has the advantage that emacs has a built-in package manager that can search any/all emacs package repositories for packages named helm-*.
While it's true that the README.md would require PRs to add to, PRs to the README are easy -- they can't break any functionality in the plugin, so they take no time to merge because they require no testing beyond just reading the text. The awesome zsh plugins list has no problem merging lots of requests in no time.
We could really do either the wiki or the readme, but I like the readme because it is connected to the repo, so cloners get a local copy and any fork that people make will get the list too. Since most github repos don't have wikis, and they are usually maintained much less than the readmes, I usually don't check them. However, I suppose just having a link to the wiki in the README would solve most of that (which is the one time I do actually look at github wikis).
PRs to the README are easy
You are true, and I agreed.
Could you list what we have to do to introduce this plugin system?
It will be a short list since there is already a plugin architecture in zaw.
Should we split existing sources?
I think we just need a section that lists available plugins with their URLs and a short description. I think we should advise people to use a plugin manager like zgen (or antigen or their ilk), which makes installing a plugin from any git repo a one-liner in their .zshrc. We should probably also add a short section about how to make a zaw source, and encourage people to follow the plugin convention that the plugin managers use, which should be simple enough.
As for splitting the current sources, I don't know. Most of them are pretty generic to the shell or Unix, and are probably of pretty wide appeal. I think probably the easiest thing to do will be to just add pointers to new ones, and start encouraging people to host them.
@junkblocker, do you have that calibre source as a repo somewhere?
I'll make a quick draft of what this might look like and add a pull request for people to look at.
@willghatch , no it's not in any public repo currently. Here it is in a Gist. Now that we are planning repo structures I think I should hold off on creating one..or I could create one and modify it too..either way is fine. Let me know.
Nice @junkblocker, I've added it to the list.
Thanks, @willghatch ! I personally don't use a plugin manager for zsh so I am looking forward to the addition of plugin creation guidelines. I assume I'll need to rename my sources to calibre.plugin.zsh.
I am also wary of the 'load zaw before this plugin or it will scream at you' caution. It'd be best if that could be avoided. I guess that could be somewhat helped by displaying a warning during load if zaw is not detected unless that's precisely what you are doing anyway :) .
Well, frankly, I think they all handle just having a .zsh file, but all the documentation on them I've read recommends .plugin.zsh because some frameworks require it. I guess the main thing is that if your plugin has a main entry point and multiple files, you should name the main one .plugin.zsh.
I guess that could be somewhat helped by displaying a warning during load if zaw is not detected unless that's precisely what you are doing anyway :) .
I think what we can do is to prepare a template of *.plugin.zsh which include the detection of zaw.
We can use declare to check zaw is loaded:
declare -f -F zaw-register-src \
|| echo "zaw is not loaded, Please load it first" \
&& returnc.f. http://stackoverflow.com/questions/85880/determine-if-a-function-exists-in-bash
That looks good. I think we should probably take whatever source is the simplest, add that check, and add comments about how everything hooks together, and use that as the example.
As for the readme, zaw is the only repo I am aware of that uses restructured text. Almost all use markdown, and the others I see tend to be emacs plugins with .org format. Maybe they're equivalently good, but I think markdown is more approachable, so maybe I will translate it to markdown if nobody minds.
@willghatch Heh, if you want examples, I use rst in all the repos I create (e.g. 1, 2, 3, 4 ) ;) The Python community tends to use that because it's more powerful that anything else and python docs are written in it. In fact calibre is the first one I used markdown for because github's automatic markdown based README generator uses it.
Having said that I am fine with either one. RST on github seems to be a losing battle.
I find && return does not work in above exmaple.
I create a plugin zaw-systemd, which include the check in the entry point zaw-systemd.plugin.zsh.
I think it can be a template for *.plugin.zsh.
The zaw-systemd plugin looks like a good example. As for .rst vs .md, at this point I think I've learned enough .rst for my zaw readme editing needs, and now the readme has an example of the one thing that I couldn't get right for several tries to refer to in-document. I think I'll just leave it for now.
Well, we have been doing this for some time, so I'll close this.