Repository template for contrib modules

We should give some thought to creating a repository template for farmOS contrib modules. The template could be used to bootstrap a repository with best practices outlined in the official module development documentation and the excellent thread @mstenta started: Approaching farmOS Module Development

A few motivations for this template and features it could provide:

  • Provide a reusable configuration for tests/ci infrastructure (mainly phpcs and phpunit)
  • If possible, bootstrap composer.json and the module directory + module.info.yml file with farmOS conventions (eg: package: farmOS Contrib)
  • Bootstrap a README.md with a consistent template for describing the module functionality in the context of farmOS

For “contributed” modules, it would also be great if the template could help support our publishing documentation by making the module available as a “project” on drupal.org. I know @Symbioquine has done some work in this regard, I believe a github action that “syncs” the github repo with the project at git.drupalcode.org?

Personally, I would like to see projects adhere to the drupal.org workflows as much as possible. Maintaining two separate repos + issue queues is weird. Projects hosted on drupal.org can currently use the Drupal CI infrastructure but will eventually use the Gitlab CI (currently available as opt-in for alpha feedback Using GitLab CI instead of Drupal CI [#3261803] | Drupal.org). And, we already recommend using the drupal infrastructure for publishing!

That said, I totally acknowledge that only using the drupal.org workflow has its limitations. Gitlab CI would be great, but it is still early. Github repos likely get better exposure and arguably a better UX. I just want us to keep it in mind - documenting and discussing our ideal workflows is a valuable contribution back to the Drupal community, something we are a part of!

2 Likes

I’ve started a template repository here: GitHub - paul121/farm_contrib_template: Template for farmOS contrib modules

I’m also experimenting with using a simple action to sync a contrib repository with Drupal.org: farm_myfarmkey/push-to-drupal.yml at 1.x · paul121/farm_myfarmkey · GitHub This is based on the action @Symbioquine created except I’m using a Gitlab “Project Access Token” instead of an SSH key for simplicity. Curious if anyone has thoughts on this strategy, the access token should be stored as a secret in the Github repo so there shouldn’t be any chance of it being leaked. Aside from the usual nuances of github actions it was quite easy to put together! :sweat_smile:

4 Likes

I tried to apply this template to the custom module I’m working, adding new files (.gitignore, .github/ and CHANGELOG.md) to the existing repository.

But after merge I noticed the branch names. I actually have “main” as working branch but if I create a new repository by “Use this template”, it creates a 1.x branch (the run-tests.yml is specting that).

Is there some kind of convention? I mean, should farmos-7.x modules have an 1.x branch and farmos-2.x modules have a 2.x? Or are module branches numbers used to release upgrades of that module (2.1, 2.2, 3.1,…) ?

I’m sure that I must create a new “main” branch following the numeration, and adapt the “run-tests.yml” to match that new branch, but I’m not sure what number should I use or if I must change the “run-test” every release to match the new release number.

Was fun when I merged the pull request and failed the changelog.md test :rofl:

2 Likes

Is there some kind of convention? I mean, should farmos-7.x modules have an 1.x branch and farmos-2.x modules have a 2.x? Or are module branches numbers used to release upgrades of that module (2.1, 2.2, 3.1,…) ?

Good question @c4ndel4 - the convention I have used is basically:

farmOS v1’s core branch was 7.x-1.x (where 7.x is the Drupal version and 1.x is the farmOS version) - because that was standard practice for Drupal modules/themes/distributions up until recently, when Drupal.org began supporting semantic versioning. So farmOS v2’s branch is 2.x.

farmOS modules followed the same pattern, where the v1 branches were 7.x-1.x. Modules that have been ported to v2 now use 2.x branches (because they are essentially the second version of that module). Modules that are starting on farmOS v2 are typically using a 1.x branch (because it is the first version of the module).

You are free to do whatever you like! 1.x is just the standard convention we tend to use for new modules, so that’s what the template suggests.

Ok, makes sense.
I started this module by copy-pasting the farm_ledger, that has only a 2.x branch and I was confused.

Haha yea that one is confusing. It was a module in farmOS v1 that we separated out to a standalone project. So I decided to use 2.x instead of 1.x in that instance.

@c4ndel4 good question and yes re: the changelog enforcement, if that won’t be necessary for you, kick it out! Maybe I should update the wording to be an “A la carte contrib template” :slight_smile:

1 Like

The changelog enforcement is not necesary for this practice module, but was a good first example in Github Actions.

The daily scheduled test were getting annoying, so I tried an old cron trick to set the execution for each 31 feb, but the result was that the action run each 5 minutes. Finally I had to remove the schedule.

Another action that could fit in the template is some kind of ping to the farmos web and notify that there’s a new module in XXX. These last days I discovered a lot of modules across different repositories (mainly from other forum users) but didn’t find any place that list them all.

Thanks for taking the time to help make things easier to other users.

2 Likes

Appreciate the feedback @c4ndel4!

I think this would get you a monthly cron job on the 31st day: 0 0 31 * * Crontab.guru - The cron schedule expression editor

Also modules that are added to drupal.org can list themselves as being a part of the farmOS ecosystem: Ecosystem modules for farmOS | Drupal.org This is a decent system to use for now, but it would be great to list these somewhere on farmOS.org as well.

1 Like

I tried the ‘0 5 31 2 *’ that crontab guru also thinks is " At 05:00 on day-of-month 31 in February.", but github executed the action each 5 minutes.

This is one of the things I’m finding frustrating: there’s a lot of documentation and resources for drupal but it’s difficult to find. This “ecosystem” page it’s not linked from the main “project/farm” page. Now I can see that every project inside drupal has that ecosystem page (it’s mapping routes so makes sense) but none of them links to it. It’s a convention that you are suposed to know, but nobody talks about it :man_mage:

1 Like