We’ve got our Ag-C Soil Survey protocol module to a place where we’re looking to do a beta release with limited functionality so that partners utilizing Farmier can test it out. I’ve been exploring the release process and wanted to reach out to the community to ask some questions about the release process, as well as invite any suggestions about best practices we should keep in mind.
I have a few main questions that I’d like your thoughts on as I try to understand the release process:
Our code currently lives in GitHub. From my exploration around farmOS and associated modules, it looks like there’s a general pattern to develop in GitHub and then copy to Drupal.org. Based on this topic from a couple of years ago, it looks like some projects use GitHub Actions to push to Drupal.org on release. I imagine this can also be extended to a GitHub Action that runs to push the code to Drupal.org on PR merge if you want to provide a dev version. Is there a standard or tried-and-true pattern that you would recommend?
Once the module is on Drupal.org, I know you can use composer and drush to install via the server CLI. But how does this work for farmOS instances on Farmier? I found this thread from a couple of years ago about enabling modules; what is the state of the farmOS setup wizard? Does the wizard work for newly established modules?
Our module only works in farmOS v3.3+. What version of farmOS are the instances on Farmier running?
Are there any best practices for, suggestions for, or examples of releasing a module with limited functionality?
Sorry if any of those questions are vague or if I missed an answer somewhere else. Thanks in advance for your help!
Yea the main reason(s) we recommend publishing on drupal.org is it gives you a few things automatically:
Drupal.org maintains its own Composer repository, which means any modules published there can be pulled into a Drupal project via composer require drupal/[module-name]. The alternative is to manually publish to the global https://packagist.org/ repository.
Drupal.org projects are automatically integrated into https://localize.drupal.org/ which means that the community can contribute translations to it, and users can download those translations using the core Drupal localization modules, without any effort required by the maintainers of the module.
You can mark your module as part of the farmOS “ecosystem”, so that it appears in this list: https://www.drupal.org/project/farm/ecosystem - That’s currently the best way to get a list of all community-contributed farmOS modules.
Farmier basically maintains a custom Composer project with it’s own composer.json file (based on GitHub - farmOS/composer-project), which also includes a “curated” set of community contributed modules. I maintain this manually right now, so all additions/updates need to go through me. I would like to make this more automated in the future, but there are some considerations to that, and so that’s just how it works right now.
Some of the considerations include:
Security: any module code hosted on my server has the potential to introduce security vulnerabilities. Therefore I review all code (and updates) to modules that I include on Farmier to ensure they don’t introduce anything that could cause issues.
Maintenance: every module installed on a farmOS instance is another dependency that, if it stops being maintained, can become a blocker for future upgrades (eg: if the module supports farmOS 3.x, but farmOS 4.x is released and the module doesn’t get updated).
Support and user expectations: users of Farmier will usually come to me first if something isn’t working as expected. So adding modules adds to my support responsibilities.
I’ve also been giving thought to the future, and how to make it easier for everyone involved (module maintainers, Farmier users, and myself) to make these things available! There are certainly ways to automate pieces of it (eg: requiring automated tests and linting of contrib modules, automating the build an deployment process more, etc). And I can add language / warnings to the module installation page to set expectations with users (eg: “This is a community maintained module. It may be uninstalled automatically in the future if it stops being maintained.” etc.)
In the meantime, and for your module specifically, I’d be happy to work with you to get it deployed to some beta testers! Happy to coordinate on this directly via email.
The “Setup Wizard” is sort of tangential to all of this. If a module is included via composer require ... (and it sets package: farmOS Contrib in it’s *.info.yml), then it will automatically appear in the farmOS Community Modules list on /setup/modules. This currently exists and works. The longer term plan with the “Setup Wizard” is to provide better guidance to new users about which modules they might want to install for certain purposes.
Farmier is running the latest version of farmOS (3.3.3). I generally update all instances to the latest version shortly after it’s released.
Hope that all clarifies what the process might look like for your module! Happy to help deploy it to some beta testers! Send me an email and we can coordinate.
Thanks for your answer @mstenta! I will definitely send you an email once we’re ready for release. Are there any base requirements for modules, even ones limited in scope and users, that we should be aware of as we prepare for this release?
Generally speaking, it should be able to include the module simply via Composer (no special dependencies or manual setup steps), and it should be able to install/uninstall it in a standard/default farmOS instance (it should implement hook_uninstall() to clean up after itself if necessary).
If you provide any configuration entities via config/install, make sure that they include dependencies.enforced.modules and list the module itself as an enforced dependency. This ensures that the configuration entities are deleted when the module is uninstalled. You can refer to all the farmOS core modules to see what they look like in that regard.
Also always a good idea to incorporate phpcs and phpstan linting into your development workflow to make sure the code follows best practices. I will run these myself when I review as well, since sometimes they flag potential security concerns. Automated tests are always a bonus.
@paul121 made this template repository for contrib modules that includes some GitHub Action workflows for common things like running automated test, phpcs, phpstan, testing the module install, etc, so that might help…
This is super helpful info, @mstenta! Thanks so much for sending it and the template. Thanks for putting that together @paul121! I’ll get on making any necessary changes and will let you know when we need your assistance, Mike, probably around the end of February.
Just to address one point of your original question that I don’t think was covered yet…
I created that topic you’re referencing on making farmOS modules that require a build step.
There are two things going on in my projects that work that way:
Some kinds of code - like complex Javascript projects - need to be built prior to inclusion in the farmOS module. At least at the time I created that thread (possibly still), pushing the output of that build process to Drupal.org as part of releases was the only way to create a farmOS module that could be installed without extra/unusual setup instructions.
Personally, I find GitHub a lot more user friendly (for issues, build workflows, etc) than the project hosting on Drupal.org (even though it is backed by GitLab and I like and use GitLab in other contexts ). So I host my primary development on GitHub and use GitHub actions to push the code/releases to Drupal.org.
You could do #2 - keep using GitHub and just push your source code to Drupal.org - even if you don’t have code that requires #1 above. However, keep in mind that this (hosting your primary development repos elsewhere) might require a bit more work since Drupal.org does provide things like Automated Drupal 10 compatibility fixes which would need a slightly more manual process to merge resulting patches.
@Symbioquine thanks so much for this additional information and for noting that merging patches will be extra work–I’ll be sure to keep that in mind. I also appreciate the examples you linked in that topic; it will make setting up the GitHub Actions much easier!
@mstenta I have a follow up question with regards to making sure the module installs and uninstalls cleanly. Our module creates plan records, which there’s no obvious way to delete for module uninstall. So right now our module uninstalls cleanly when there’s no data, but once a user creates a plan (which automatically creates associated plan records), it can’t be easily uninstalled due to the resulting plan records. Perhaps this is an entirely different topic, but I’m curious how you all have handled this in other modules that use plan records or, if there aren’t any examples yet, how you might imagine doing so.
Great question @ktohalloran! I almost wrote about this in my last comment…
This is something we haven’t really tackled yet, to be honest. In theory, a module that provides entity types (eg: a log type or an asset type) should probably delete all entities of that type when the module is uninstalled. I believe Drupal provides some mechanism to prevent a module from being uninstalled if there is content in the database that it’s responsible for, but we should double check that.
We don’t currently do this in any of the core (or contrib) farmOS modules. And maybe we should be. This might be worthy of a broader best-practice discussion topic.
If this is true (if I’m remembering correctly), then it means modules CAN’T delete all content in hook_uninstall(), because the module can’t be uninstalled, so hook_uninstall() will never run.
If that’s the case, then the user would need to manually delete all records before they can uninstall.
Ah maybe you’ve already seen the Drupal core behavior I’m talking about!
Perhaps the best thing to do would be to automatically delete all plan_record entities when a plan that they reference is deleted. Maybe this should be a farmOS core behavior, now that I think about it.
With that, then the user would just need to delete their plans before they uninstall the module.
Perhaps the best thing to do would be to automatically delete all plan_record entities when a plan that they reference is deleted. Maybe this should be a farmOS core behavior, now that I think about it.
Great, thank you @mstenta! I’ll look into deleting the plan records on plan delete as you suggest. I had hesitated to pursue a tactic like this without asking for guidance because I couldn’t find an existing example and thought maybe it was a bad practice–it’s interesting to know this could actually be its own best practice topic.
@ktohalloran My gut says that this should probably be a core farmOS behavior, so maybe hold off on adding it to your module. It will be easier to have a general event subscriber in farmOS that deletes plan_record entities when an associated plan is deleted than for every module to do it themselves.
). So I host my primary development on GitHub and use GitHub actions to push the code/releases to 