When it comes to the best format and place to store the contrib project list, there could be created a github repo in which contrib modules/tools list could be stored as a json file(s). This approach would provide several benefits:
it should be quite easy to contribute (for example add a new module) through github ui, either by creating a pull request or an issue,
json file format and the list being publicly available from the internet would also allow for some integrations like:
automatically displaying the list on the documentation site,
creating custom source plugin for Project Browser | Drupal.org which would allow installing new contrib modules from the drupal admin ui, without the need to manually execute composer commands.
Any thoughts? Or maybe there already exists such list somewhere and I just didn’t find it?
But I agree, it would be nice to have another place like a repo to store this information. We don’t expect all modules to be listed on Drupal.org. And there is value in having a directory of more custom modules that aren’t necessarily designed for others to use, but are open source and can be referenced as examples or any other reason. Some way of tagging these subtleties would be nice
Thanks for sharing this! I did not know the project was this far along
Yea I had a similar thought… any “official” list we have must have some way of designating “true contrib” modules vs “custom” modules. The expectations are very different between those. “Contrib” means it is intended for general use. “Custom” means it is built for one specific group/user’s needs. Custom modules may have implicit assumptions that don’t apply to other instances (eg: hard-coding asset names/IDs into forms), and there is no guarantee that update hooks are provided.
So at the very least I think the spreadsheet should have a “type” column for “contrib”, “custom”, “unknown”, etc… so that it is clear what the user’s expectations can be.
Anything published to drupal.org is considered “contrib”, and should therefore set the expectation that it is designed for general use and is well maintained.
The other benefit of publishing to drupal.org is it makes it possible to translate the module via strings in localize.drupal.org.
If we were to create such a github repo with this information… maybe we could use the Drupal.org API (assuming this exists?) to find the farmOS ecosystem modules and auto-populate + update all of the “contrib” modules. This could then easily include things like latest versions and release dates of these contrib modules.
Where would you prefer feedback? In this forum topic or in GitHub issues?
Couple of quick thoughts here, to be reorganized/addresses later - and apologies if these sound critical - I mean them as a critique for ALL of us who may be helping to maintain this moving forward…
If the end-goal is to list these modules on farmOS.org (which we should!) then I do NOT think we should include custom modules/projects. Or, if we do, then they should be in a separate page or section that explicitly states that we do NOT recommend installing them. These kinds of projects may be useful to refer to for other developers, but we do not want to create any expectations that they will work for end-users. In general, I think we should be very careful and intentional about which modules we list on farmOS.org and what expectations we set. The risk is that end-users end up confused/frustrated when they think a module will do something and it doesn’t - or worse: it breaks their install.
With the above in mind, I wonder if we should establish a process of consent, whereby we ask module maintainers if they want their module listed, along with a process for developers to propose additions. And make it clear to them that this means setting an expectation with the end-users about the stability of their project. Modules that we “recommend” on farmOS.org should meet a certain set of quality standards, IMO. One of which should be: “this module cleans up after itself when it is uninstalled”. Otherwise we also need to educate end-users on how to test modules in a dev instance before installing them in a production instance, etc. There are a few modules I created that are in this list, which I would NOT recommend anyone install. So just generally I’m worried about quality control and the expectations that we set.
I also worry: “who is going to maintain this?” History has proven that initiatives like this have a lot of interest in the beginning, but can quickly decay and become outdated/unmaintained if no one is staying on top of it. Automating it would be great, but there’s a lot of questions there as well. And I also don’t want anyone to feel obligated to maintain it either. It’s unpaid work. But once we set this ball rolling, maintaining it becomes an obligation for the farmOS community (assuming it becomes part of farmOS.org). I’m just raising that as a consideration - not to dissuade. The “keep it simple” strategy (eg: keeping the list small and focused on contrib modules that are intended for wider use) is one way to minimize this burden.
One idea: maybe we have some additional attribute that let’s maintainers set expectations with a 1-5 scale… something like: 1 = don’t use this module except as an example for developers, 5 = this is actively maintained and intended for general use. Worth noting drupal.org has a similar system for denoting the maintenance status of modules.
This is very cool! I haven’t used the Project Browser module myself. This is something to keep an eye on - and maybe it will be worth considering for inclusion in farmOS core in the future. I tend to be very careful about adding additional modules/dependencies to farmOS core, though (having spent a good chunk of my time over the past 10 years BLOCKED on major upgrades because of them). If we end up considering this for farmOS core I’ll have a lot more questions…
All the critiques aside, THANK YOU for spending time on this! It is really important that we start to organize what the community is working on - so that everyone can see what’s happening! It’s just the little details and considerations to figure out next. Broadly speaking I think this is a great idea.
This one also jumps out at me and raises a question…
First of all, WOW! I didn’t even know that you were working on a 2.x port of this module. That’s great!
Second of all, because this module is maintained by the farmOS community (it is part of the farmOS · GitHub GitHub organization), we should not recommend anyone install a fork of it, because it is creating a potential future conflict when we have the “official” 2.x version available.
Hypothetically (having not actually looked at your 2.x version’s changes): what if the fork’s changes are not accepted, and instead a different approach is taken? We then have two different modules that share the same farm_eggs namespace - and if anyone installed the fork, but wants to switch to the official, their is potential pain/complexity in doing so.
Side note: can we talk about your fork sometime soon?
List of custom modules/projects could be helpful as a reference for developers but also for end users to see what’s possible with farmOS, but I agree that there need to be a clear warning that those are not recommended to install and can cause problems. Putting them on a separate page with a warning on top would be probably the best option. We could also keep it in the repo as a separate list to further emphasize that these are not the same as contrib ones.
When it comes to contrib modules, I think we could require them to be published on drupal.org to be included in the list. This would ensure every contrib module is installable using composer and can have translations contributed using localize.drupal.org.
new contrib module is published to drupal.org and assigned to farmOS ecosystem,
it is automatically added to the list,
github issue is created for manual verification/review of the module,
if it is verified to follow stability/best practices guidelines, recommended property is manually set for it to true.
On the site, we could then display:
list of recommended modules (ones with recommended property manually set),
warning that the following contrib modules were not verified,
list of the remaining contrib modules (ones without recommended property set),
link to the separate page with custom modules.
This approach would allow for adding new contrib modules without maintainers time being the blocking factor, but also set clear expectations which modules are vetted and recommended.
Yeah, at first it was supposed to be only a simple v2 port, mainly for my own use, but later I also implemented some feature request (1, 2, 3) I thought could be useful and then started changing/adding more things and have plans for even more.
It also became a bit of a playground for me for getting familiar with and testing ideas around quick forms and general farmOS apis.
At this point I should probably just change the namespace of my fork and maybe contribute back parts of it to the main repo.
Sure. We can chat on the farmOS element.io chat, I can also drop by on the dev call this week, or we can schedule a one on one call.
Project Browser is one of the Drupal core strategic inititives https://www.drupal.org/about/core/strategic-initiatives/project-browser, so it should be well maintained, and it is planned for inclusion in Drupal core so farmOS will probably gain it as an indirect dependency at some point even if we won’t use it.
I agree with all of @mstenta sentiments! It’s better to be cautious with the expectations we set here. I’m optimistic that such a list wouldn’t be too hard to maintain, especially if we go with an “opt-in” and set nice schemas/standards for what is expected to be contributed to the module (as already being proposed!)
As far as the farmOS.org modules list, perhaps it would be best to start with only the “recommended” contrib modules. IMO I think it’s quite important to have a list of these on farmOS.org. These should also be easiest to maintain - once it is “recommended” I think we assume it will be there for awhile.
I really like this concept! Especially if the “description” is exposed to users, not the number. One tier could be “well maintained with external funding”… Could this be combined with a more generic recommendations or considerations text as well? Some modules might be well maintained also but require a separate API key, service or other special consideration that is best described in a quick sentence.
The more we talk about contrib modules, the more I think we should have a dedicated list for them. It seems that they could even have a slightly different schema too.
So… with farmOS.org in mind, what about this for next steps:
Continue thinking on a schema for contrib/custom modules (maybe consider two separate schemas)
Once we have a good schema, create a repo in the farmOS organization with only recommended contrib modules to start. Also add these to farmOS.org.
@wotnak and others can continue hacking on other contrib/custom module features in a fork/separate repo
Add additional features to core farmOS list & farmOS.org in separate feature requests over time
I think it would be really valuable to have lists of both contrib and custom modules (custom modules/other farmOS related projects) on farmOS.org. But starting slow with good contrib modules makes most sense!
I like this workflow, however I do think that none of this should be “fully automated”. A module shouldn’t be added to the list unless an issue/pr is merged by maintainers. Especially if that goes directly to farmOS.org people could spam it by creating nonsense projects. But we should definitely explore using automation to create those issues/prs as described!
I’m curious if we could leverage the project browser UI on our “Install modules” form… we may not need the complexity of project browser for actually downloading and installing something, but just the UI would be amazing to have.
Thanks for starting & pursuing all of this @wotnak- would love to chat more on the community dev call this week !
@wotnak I forget what the current status is - maybe we could restart the conversation? It would be awesome to get at least a simple first step page up on farmOS.org that shows modules!
Happy to help make a strategy and/or decide on the steps/phased approach via chat or call sometime if that helps!
Maybe the first step could be to just create a static markdown page, on which we could manually list contrib modules. It would quickly bring some value, and can be improved later.
When it comes to the end goals, I would like to create something like the Nuxt Modules page:
the modules are added in a separate repo in which they are described in yaml files, one file per module
then in github action json file is built, which is later used to render modules on the listing page
in the modules repo we could also add some automated actions that would:
update modules metadata
for example short description (from module .info.yml file) or maybe installs count fetched from drupal.org api or stars fetched from drupal.org and github.com depending on where given project is hosted
scan drupal.org to find new contrib modules that were marked as in the farmOS ecosystem and automatically create pr to add them to the repo
