Community plugin contributions & versioning

[Kirottu]

So there are a few things that should be addressed as Anyrun becomes more popular and more users & developers flock in.

The first of them is community contributed plugins. Adding them into the main repository in the long term is probably not feasible, some of them may be specialized and not really something the average user may need. They are also a maintenance burden where generally the maintenance of the plugins falls on me to handle after they've been merged, even if I am not that experienced with the codebase of the plugin.

The second issue is versioning. The approach of just making everyone use the latest code at all times (like anyrun-git on the AUR) has worked fine-ish for now but with more complexity and moving pieces, the risks of something breaking down accidentally is much higher and could affect well, everyone who keeps their system up to date. There are a few ways to go about this:

• Versioning Anyrun and all the plugins included in this repo with the same version number, and all bumped simultaneously. This would be easier regarding packaging and maintaining as everything would basically continue as they would continue as they already have.
• Versioning (and hence also packaging) each plugin and Anyrun separately, so plugins can get updated at their own pace and target a version of Anyrun.

I would really appreciate any feedback and suggestions on this matter, so any ideas you may have are welcome in this discussion.

[abenz1267]

For more general plugins, . F.e. my websearch plugin or the hyprlandwindows one, having them in the main repository seems fine to me.

Regarding maintenance: i think you could just handle this differently. F.e. i honestly don't come looking at the issues here, unless i have an issue or suggestion. What you could do is:

• issues regarding plugins must include a mention of the original author. Maybe even add a comment with the original author to the lib.rs so one can quickly see who did it.

Just today i noticed someone is having an issue with the websearch plugin. At the same time i also noticed you've changed it. Which is of course fine. So what would have been the process here, if it wasn't in the main repo? You forking my plugin from my repo, making a PR? The issues itself would hopefully have gotten reported to the source-repo of the plugin.

How would such plugins be distributed properly without being cumbersome to discover and install etc?

Also: i think it's much safer to have plugins in here instead of wherever. If a plugin gets abandoned for whatever reason, that could become a pita. You end up getting forks of forks of forks. I'm not sure if i'd go down that path.

[Kirottu]

Another option for the plugins would be a repo like anyrun-contrib that would have the community contributed plugins, where their authors could be listed in some way so that they could be contacted in case problems arise.

As for the distribution of plugins, with this the anyrun-contrib plugins could be distributed in another package.

[abenz1267]

Yes, i thought about that option as well. Might eventually be the most sensible one. Also: if there's consensus plugins could move from anyrun-contrib to anyrun. Maybe. Maybe not :D.

[NachtaktiverHalbaffe]

Just seeing this pinned issue. The Home Assistant project uses manifest.json files for the integrations, where also the code owner/maintainer is included. AFAIK they managed to integrate it into Github issues that the maintainer is automatically added to an issue and mentioned when a issue to that integration is opened.
Maybe this could be a starting point, a manifest file with the maintainer, compatible versions, deprecation warning etc. to the plugin and integrating it into the Github workflows and some infromative measures like deprecations warnings in the application itself.

Also longterm I would recommend to ensure that the included plugins have some maintainer (intentionally the creator, but can also be you if you are willing to be the maintainer) who is "responsible" for keeping that particular plugin working. If the maintainer leaves the plugin abonded and no new mainainer is found when problems occur then remove the plugin. Theres no point of a having a broken plugin in the repo if it cant be maintained (and the burden of maintanance of external contributed plugins shouldnt fall automatically on you if you cant or dont want to maintain it by yourself).

Otherwise I would prefer to have the plugin in this repo, maybe creating some guidelines that updates due to issues etc. are done through PR of branches which gets created and used for issues until they are resolved.

All of this is of course my point of new, I'm still on a junior level when it comes to programming and OSS and Rust isnt my domain

[Sntx626]

I'm heavily leaning towards putting the plugins into a seperate repo (all of them).

The overall process for us would look like this:

1. Define how plugin repos should look like (maybe provice an official template repo)
2. Put plugins into seperate git repos (potentially maintained by others)
3. In the main repo: have a file (entry) linking to them with a name, brief description and maintainers

If a plugin lost it's maintainers or is broken/insecure it's entry could easily be removed from the main repo. The plugin would then need to maintain itself.

Installing plugins from nix would still be trivial, if they're flakes themselves.
Though every plugin would need to maintain it's own, seperate packages (nix, aur, ...).

I'm willing to setup an example project, if there's interest for it.

PS: At least for me it would make the workflow and iteration on plugins really easy. Furthermore I think it's a good way to satify seperation-of-concerns, since this will also make it easy to go the other way around and replace the core anyrun with let's say an anyrun-tui.

---

Sidenote:
I don't think it's a good idea (because of complexity), but we could also add them to the main repo via git-submodules.

[Kirottu]

@NachtaktiverHalbaffe I don't think an automated system with manifest files like that would really be that feasible, due to being quite complex and out of the scope of this project. But in general who maintains the different plugins should ideally be made pretty clear.

As for placing everything in separate repositories like @Sntx626 suggested, it would make dealing with who maintains what and versioning much easier but installing stuff may be more complicated and the project would be more fragmented. For the "official" plugins made by me, I could create an organization to group all of the repos in the same place on GitHub, and then of course link all the other plugins in the main repo readme. It would be a bit of a chore to convert to that form, but it would probably be sustainable given that we also figure out how to do packaging properly.

If you feel like making an example project template that would contain all the relevant info (about maintainer, version support, etc.), I'd like to see it.

[Sntx626]

I'll cook up an example.

[Sntx626]

I've put together this example github organisation.
And checked it can be build and used, by adding it to my system config (c.f. this diff).

Please keep in mind that this is rather proof-of-concept and nothing final.
I've also changed some parts more than they might need to have been changed...

If you like it that way we can talk about how we'll realise it for the real anyrun.
I intend to delete the repos/org once we've deciced and possibly transitioned.

Feel free to ask questions if things aren't clear.

[Kirottu]

The descriptions of the "core repositories" in the org README are not exactly correct, but otherwise that structure does look pretty nice to me. How does everyone else feel about that template?

Aside from deciding on the final structure, contribution guidelines (issue templates, how to add plugins to the plugin list, etc.) should also be created to make this all a lot more manageable.

[Sntx626]

Yes, the readme looks better, than it is accurate. It's written by our favorite artificial intern, since I didn't want to invest too much time on secondary details and focus on the structure / getting it to work.

Though I should mention that one of the bigger changes I made was in terms of dependencies.
anyrun_plugin has solely become a template repository for new plugins. All plugins no longer depend on anyrun_plugin, but rather on anyrun_interface and anyrun_macros directly (thinking about it, I should replace the src/lib.rs in anyrun_plugin with the example plugin code from anyrun's readme).

How should we proceed?

1. Does @Kirottu create a new organization with a proper name (anyrun seems to be taken) and invite us to work on it? Or do we keep the current organization, change it's name and I invite @Kirottu and anyone interested in working on it? (After we're done we should probably also replace the anyrun repo with this one to preserve the commit history).
2. Do we create a github project (or something similar) to track the missing tasks, or do we stick to discussions in this issue?
3. Whats the plan for the contribution guiidelines?
   1. @Kirottu do you have anything specific in mind / an example of a repo doing it "right"?
   2. What do other think?
   3. Do we enforce GPLv3 for all plugins listed in the org?
   4. ...
4. Document what's been changed over the current anyrun
5. Do we want to support core plugins directly in the org (as it is the case right now)?
   1. What plugins are core-plugins, what plugins should be moved out?

[abenz1267]

This looks super fine to me, nothing to add really.

Do we want to support core plugins directly in the org (as it is the case right now)?
What plugins are core-plugins, what plugins should be moved out?

I think core plugins should be supported, simply to have a solid OOTB experience. But what could be considered a core-plugin and what not? How to decide? Maybe adoption could be a factor. As in: if 99% of the user-base uses a certain plugin, it should prob. be considered a core-plugin. But this required gathering data somehow...

[Kirottu]

Though I should mention that one of the bigger changes I made was in terms of dependencies. anyrun_plugin has solely become a template repository for new plugins. All plugins no longer depend on anyrun_plugin, but rather on anyrun_interface and anyrun_macros directly (thinking about it, I should replace the src/lib.rs in anyrun_plugin with the example plugin code from anyrun's readme).

I would rather preserve the anyrun_plugin create, as with some of the suggestions in other issues there is room to add more functionality in that crate to reduce code duplication.

Does @Kirottu create a new organization with a proper name (anyrun seems to be taken) and invite us to work on it? Or do we keep the current organization, change it's name and I invite @Kirottu and anyone interested in working on it? (After we're done we should probably also replace the anyrun repo with this one to preserve the commit history).

I think that makes the most sense, this repo can be transferred to that org in that case and the required modifications could be made. I could create a clone of this repo under my account that can be archived.

Do we create a github project (or something similar) to track the missing tasks, or do we stick to discussions in this issue?

That is a solid idea to keep track of things, I am notoriously bad with forgetting about things I need to do so having all the stuff that needs doing in one place seems like a good idea.

Whats the plan for the contribution guiidelines?

For the guidelines I was thinking about issue/PR/plugin templates and general guidance as to how to do things like where issues should be reported, how to submit a plugin into the project (to be added in a list of plugins).

Do we enforce GPLv3 for all plugins listed in the org?

I prefer to have my code licensed with GPLv3, but I really am not that experienced with licenses and how to deal with them so I don't have that much to say about it. If the plugins in the org are the "core" plugins, which would likely mean that the majority are maintained by me it would make sense to just have all of them under the same license.

I think core plugins should be supported, simply to have a solid OOTB experience. But what could be considered a core-plugin and what not? How to decide? Maybe adoption could be a factor. As in: if 99% of the user-base uses a certain plugin, it should prob. be considered a core-plugin. But this required gathering data somehow...

Gathering user data isn't really going to be a feasible option so I'd say we just promote all the plugins that are currently in the main repo to core plugins (except maybe for randr as it is a bit too incomplete to properly fit that, as it only supports Hyprland) as all of them seem generic enough.

Also with the separation of the crates, versioning should be established (everything can start at 0.1.0) and the crates that will be used by plugins and Anyrun should be published on crates.io. This will make compatibility easier to track as well, as the only relevant version for compatibility is the interface crate version.

[Sntx626]

I would rather preserve the anyrun_plugin create, as with some of the suggestions in other issues there is room to add more functionality in that crate to reduce code duplication.

Ok, in that case I'll revert anyrun_plugin back and instead create anyrun_template_plugin as a template repository. I think that should go with a renaming of the plugins. The main repo is an exception.

• Main repo: anyrun
• Anyrun modules: anyrun_<module-name>, i.e. anyrun_interface, anyrun_macros & anyrun_plugin
• Anyrun plugins: anyrun_<plugin-name>_plugin, i.e. anyrun_applications_plugin, anyrun_dictionary_plugin, anyrun_template_plugin,...

I think that makes the most sense, this repo can be transferred to that org in that case and the required modifications could be made. I could create a clone of this repo under my account that can be archived.

Just to avoid misunderstanding: You want to keep the current organization and modify it?
In that case I'll invite you.

That is a solid idea to keep track of things, I am notoriously bad with forgetting about things I need to do so having all the stuff that needs doing in one place seems like a good idea.

We can create a project for that in the org.

For the guidelines I was thinking about issue/PR/plugin templates and general guidance as to how to do things like where issues should be reported, how to submit a plugin into the project (to be added in a list of plugins).

This sounds great and reminds me of the way nixpkgs handles it (though they've mastered it).
We could draw inspiration form there.

I prefer to have my code licensed with GPLv3, but I really am not that experienced with licenses and how to deal with them so I don't have that much to say about it. If the plugins in the org are the "core" plugins, which would likely mean that the majority are maintained by me it would make sense to just have all of them under the same license.

Sounds good.

Gathering user data isn't really going to be a feasible option so I'd say we just promote all the plugins that are currently in the main repo to core plugins (except maybe for randr as it is a bit too incomplete to properly fit that, as it only supports Hyprland) as all of them seem generic enough.

For simplicity's sake I also say that we should stick with just deciding it for the current plugins.
And I agree that randr should be moved to the community plugins.

Also with the separation of the crates, versioning should be established (everything can start at 0.1.0) and the crates that will be used by plugins and Anyrun should be published on crates.io. This will make compatibility easier to track as well, as the only relevant version for compatibility is the interface crate version.

We should defintely reference to semver.org, the versions would then be tracked through the Cargo.toml of the respective plugins.

Pushing the main repo and anyrun modules to crates.io/lib.rs would also result in the plugins Cargo.toml dependencies for them to no longer point to the git repo and instead to the "published" version.

[Kirottu]

• Main repo: anyrun
• Anyrun modules: anyrun_, i.e. anyrun_interface, anyrun_macros & anyrun_plugin
• Anyrun plugins: anyrun__plugin, i.e. anyrun_applications_plugin, anyrun_dictionary_plugin, anyrun_template_plugin,...

For the naming, I think <plugin name>-plugin is sufficient and the repo for the plugin template could just be plugin-template. I don't think there is much point in namespacing them further. Arguably even the anyrun_* crates could have the anyrun_ prefix removed for the repository names.

Just to avoid misunderstanding: You want to keep the current organization and modify it?
In that case I'll invite you.

I meant that I'll create the org when the plans have been solidified.

We should defintely reference to semver.org, the versions would then be tracked through the Cargo.toml of the respective plugins.

And yes I agree that following semver is a good idea in general, and pointing the repos to published versions of packages reduces the amounts of headaches that git packages introduce when it comes to the Nix flakes.

[Kirottu]

Alright I have now created the organization under the name anyrun-org, and will start making the repos. If you want to help with the setup process I can invite you to the organization @Sntx626.

[Sntx626]

I'd like to contribute, feel free to invite me.

[Kirottu]

Sure, you can create the plugin repositories and I'll create the repositories for the internal crates.

[Sntx626]

Sounds good.

Well have to look into packaging anyrun-org/plugin quickly with crates.io, so that the plugin repos won't have to depend on the git repos.

I've also created a project with tasks to track the progress on moving Kirottu/anyrun -> anyrun-org.

[Kirottu]

I already packaged all the relevant crates (interface, macros, plugin) on crates.io so that is already dealt with.

[Sntx626]

I've transistioned the plugins over to anyrun-org and added a few tasks to the roadmap/project.

What do you think should be worked on next? What could I help you with?

[Kirottu]

If you want to you can start drafting up the issue template and general contributor info. I'll start working with the main repo with the transition branch as soon as I have time to do so.

[Sntx626]

Another thing to think about:
When moving the Kirottu/anyrun repo to the org, should we rename it to anyrun-org/gui instead? Since it's mostly that, all other components were abstracted away from it.

[Kirottu]

I would still have it be named as Anyrun, as it is well, Anyrun. It is the main program after all and it would be much clearer for end users as it will also have the general instructions on how to use Anyrun.

[just1602]

Hello,

I was wondering if you were still planning to move anyrun to the anyrun-org org? The projects on the org don't look in sync with this repo nor super active, so I was wondering where are we supposed to make feature requests / propose feature?

I really like the idea of having a anyrun-org to help @Kirottu and make it possible for people to maintain plugins in a more collaborative and decentralized way, I was just wondering if it was still an ongoing project? If I can help with anything, let me know.

[Kirottu]

Well, the plan was indeed to move the main project to that org, but real life got in the way and in general I haven't found the motivation to fully go through with the migration.

There are a bunch of things that still need to be done, like AUR packages, contribution guidelines, guidelines in general and now due to the repos getting out of sync getting them back into sync. So if you want to help with some of these, and other things in the org project for the migration, it'd be a real help in actually getting the migration done some day.

I can't guarantee properly keeping up with things due to life being pretty busy right now, but I'll try my best.

[just1602]

Nice,

I'll try to check for the following things:

• AUR packages
• Update org repos
• Setup dependabot on org repos, since it'd be nice to have PRs for anyrun-interface and anyrun-macros on every plugin.

---

Update: I've created aur packages for the various plugins, but they're not published yet, since I'd need an anyrun package with a version to go with the plugin aur packages I created using the 0.1.0 release that each plugin has.

I'll also gather all the aur packages code into a anyrun-aur using git subtree, so we're gonna be able to have one repo on the org to receive contributions, but still push to different repos on the aur server.

Once it's gonna be done, I'll also create -git aur packages for all the plugins.

Here's my PR to add dependabot config

[Maytha8]

Hi,
There's interest in packaging anyrun for Debian.
I've opted to handle the packaging, but anyrun (including components and plugins) need to be published to crates.io first (Debian Rust Packaging Team's workflow relies on crates being available in crates.io).
Let me know if there's anything I can do to help with the migration! 😄

[peppidesu]

Hi, I have some PRs open that are specific to the applications plugin, so @ me when the migration is done so I can transfer these to the new repo. Thanks!

[Sntx626]

Well, the plan was indeed to move the main project to that org, but real life got in the way and in general I haven't found the motivation to fully go through with the migration.

@Kirottu can you give a general outline on your vision of how the project should look and be managed?

Do you want us to just create issues in the anyrun-org repo for the current tasks on the project board and figure out what we want?

Or do you want to steer the transition yourself?

Do you want to offload the authority of managing the switch to someone else?

---

There are a bunch of things that still need to be done, like AUR packages, contribution guidelines, guidelines in general and now due to the repos getting out of sync getting them back into sync. So if you want to help with some of these, and other things in the org project for the migration, it'd be a real help in actually getting the migration done some day.

The current state of the contribution guidelines can be found here, AUR packages are thanks to @just1602 in the works.

I think with "guidelines in general", the following questions should be answered:

• How do I create a new plugin? (c.f. current README)
• Where do I publish/put the new plugin?
• Who is maintaining what?
• How is lincensing handled between different plugins?
• How can I use insert plugin here with anyrun?

[just1602]

Would it be possible to release a version of anyrun, it would allow me to create the anyrun AUR package and release all the plugins.

After that, I could create -git AUR packages for the plugins and once those are created we would only have to edit the anyrun-git package so it stops to install plugins.

[Kirottu]

@Kirottu can you give a general outline on your vision of how the project should look and be managed?

The plan was to divide the project into separate repositories that can be individually versioned and packaged properly instead of just bundling everything in a single package. With this, different maintainers for different parts of the project would be possible.

I think with "guidelines in general", the following questions should be answered:

• How do I create a new plugin? (c.f. current README)

I think a simple guide for the technical part, as there is already, should be in the appropriate repository/crate.

• Where do I publish/put the new plugin?

I think we should have a list of plugins with the official plugins and community plugins, and entries for the community plugins could be submitted via PRs with a template in place. That template should contain all the relevant parts like a link to the repository, name, description of functionality, etc. If you all have ideas/opinions regarding this feel free to voice them

• Who is maintaining what?

That could be added to either repository descriptions or READMEs.

• How is lincensing handled between different plugins?

I think the licenses of the projects under the main org should ideally be the same.

• How can I use insert plugin here with anyrun?

I don't quite know where you are going with this, but using plugins should be in ordinary user instructions and plugin specific instructions should be in their respective READMEs.

Right now with the AUR packages being ready to publish (I presume @just1602 created them to use the repositories in the org), I think after updating the code in the repositories of the org to reflect the changes that have happened since, the main repository could be transferred over with minimal effort. After the transfer I would create a clone of the repository with a disclaimer of the project having been moved to the new org and release the initial version of Anyrun allowing the AUR packages to be published.

At this point I think we should just go for it instead of waiting around as well clearly that hasn't worked for me personally at least.

And as always I'd like to hear how you all feel about this and how we should go forward.

[Maytha8]

I've opened PRs anyrun-org/plugin-stdin#1, anyrun-org/plugin-applications#1, and anyrun-org/plugin-dictionary#1 to sync them with this repo.

[Maytha8]

@Kirottu Letting you know that the randr plugin is missing a repo under anyrun-org.

[just1602]

@Kirottu personally, I'm not even sure I'd make a distinction between officials and community plugins. I think I'd simply put every plugin in a separate repo and package maintainer would be able to mark the plugin's packages as suggested, but if someone want to run anyrun only for their custom plugin they use, they could.

Maybe I'm wrong, but I'd try to keep anyrun's defaults as small as possible, so people could only install what they need, and it'd also have the advantage to keep repos and codebases small, which generally help when new people want to contribute.

[Kirottu]

@Kirottu Letting you know that the randr plugin is missing a repo under anyrun-org.

Yes, that was by choice as I don't really think that it would fit the requirements for an official plugin (as in, actually being functional for most of the users and being properly maintained. The Randr plugin right now is really not that great).

@Kirottu personally, I'm not even sure I'd make a distinction between officials and community plugins. I think I'd simply put every plugin in a separate repo and package maintainer would be able to mark the plugin's packages as suggested, but if someone want to run anyrun only for their custom plugin they use, they could.

Maybe I'm wrong, but I'd try to keep anyrun's defaults as small as possible, so people could only install what they need, and it'd also have the advantage to keep repos and codebases small, which generally help when new people want to contribute.

The distinction I am thinking of is that official plugins are placed inside the organization, are maintained by developers actively involved in Anyrun in general and are maintained alongside the main project (but in their own repos of course). The community plugins would be outside the organization and in general a lot more free form in how or if their respective maintainers decide to maintain them.

[just1602]

@Kirottu that sounds great to me!

[Kirottu]

Hello everyone and sorry for the prolonged absence, I had a lot going on but have now finally gotten around to actually working on the migration.

The anyrun-git AUR package needs changes to work with this, so do you mind giving me the ownership of the package so I can implement the needed changes @Bryntet?

[Bryntet]

The anyrun-git AUR package needs changes to work with this, so do you mind giving me the ownership of the package so I can implement the needed changes @Bryntet?

I'll update the package myself in a couple hours :) (not at my computer right now)

If you really want to take the ownership of the package, I would give it to you of course, but I'd rather take the small burden off of your shoulders as a maintainer :)

[Kirottu]

Alright well that works for me, the changes that need to be done are:

• Making the -git package provide anyrun
• Adding a non-git package
• Removing the bundled plugins (and adding dependencies for bare minimum plugins like applications)

I've already published AUR packages for the individual plugins, although some work needs to be done to bring all of them up to date to what the repository currently contains code wise.

[just1602]

@Kirottu I just saw that you create all the plugins package on aur, I was wondering if we could create a repo on anyrun-org that would contains all the AUR package, so people could contribute to those package too, and you could simply have to push them.

A nice tricks to have all packages in one repo is to use git subtree.

[slowsage]

#198 moved all the plugins out (eg: anyrun-dedup/plugin-applications has the latest code from anyrun-org/anyrun). If #198 looks good, I can submit other PRS from https://github.com/orgs/anyrun-dedup/repositories.