Problem/Motivation

Paraphrasing from Slack https://drupal.slack.com/archives/CGKLP028K/p1780185330490939

The Drupal AI project recently added GitLab Description Templates for different types of issues (e.g. bug report, feature request) and merge requests: https://git.drupalcode.org/project/ai/-/tree/1.x/.gitlab?ref_type=heads

Now, other projects in the AI ecosystem are starting to copy them (example from AI Best Practices), but the problem with that is these templates all end up being "forks" of each other.

If the "upstream" Drupal AI project makes future improvements to their issue/MR templates, we won't necessarily know about that, and their changes won't get reflected in ours without manual syncing. And now we are set up to create terrible UX for AI ecosystem contributors because when they're in AI project A the issue forms are like this but when they're in AI project B they are subtly different and given there are like 457 different AI modules (give or take ;)) this is going to spin out of control, fast. :\

Important note for AI haters: 🤣 While these templates originated in the Drupal AI project, these improved templates look to me to be genuinely useful to any project, not just AI ecosystem modules.

Proposed resolution

I asked new smarty-pants Claude Opus 8.4 about this problem, and its recommendation was actually to set default templates at the instance level (see: Instance template repository) by pointing it at a project with shared governance (akin to what we do for coding standards) that sets up "reasonable defaults" for everyone, with individual projects being able to override them only when/if that makes sense.

For example, AIBP might want to make a skill.md or eval.md file for things particular to our project, but not all Drupal projects; that's fine, and what the feature is intended to do.

Claude even discovered we apparently already have such a thing at https://git.drupalcode.org/project/gitlab_templates but that right now it's purely scoped for CI/CD and not issue/MR templates.

Proposed resolution is therefore two-fold:

1. Either expand the remit of https://git.drupalcode.org/project/gitlab_templates or create a different "canonical" project to hold issue/MR templates (I suspect there can be only one though, based on the name of the setting).
2. Populate it with the templates from the Drupal AI module as a starting point.

Remaining tasks

User interface changes

API changes

Data model changes

Comments

webchick created an issue. See original summary.

webchick’s picture

Priority: Normal » Major

Tentatively bumping to "major" because if we get in front of this, we somewhat contain the UX blast radius moreso than once the copy/pasta of these rules has proliferated throughout 100+ modules.

drumm’s picture

We should probably have at least a little consensus from project maintainers that the templates are generally good for most Drupal.org projects before deciding to suggest them for all projects. I believe there is not an opt-out for any given project.

There is also Drupal.org’s old issue summary template that we may want https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-an-.... Personally, as a maintainer, I see that these things are all good to consider, but most issues don’t need all the sections, as shown by this issue (rightfully) skipping 2/3 of them.

The AI project’s templates have a couple things which I’m not sure about for all projects. For example, https://git.drupalcode.org/project/ai/-/blob/1.x/.gitlab/issue_templates... Feature requests often have Workarounds?

dww’s picture

On a technical level, can it work exactly like .gitlab-ci.yml and our existing templates project? There’s no site wide setting. The absolute source of truth is every project’s own directory. But it’s easy to include the global templates if you want them, and ideally alter / tweak / extend after including. I don’t know GL internals to know if this is possible. But if so, it solves the “there is no opt out” of the global setting.

webchick’s picture

I did not know how to parse that (sorry, still learning :D), so I did some digging into it with Claude, and it sounds like:

How the existing CI pattern works

Right now, every project has its own .gitlab-ci.yml file in its repo. That file is the source of truth for that project. But the first line of most projects' .gitlab-ci.yml is essentially:

yamlinclude:
  - project: 'project/gitlab_templates'
    file: '/includes/include.drupalci.main.yml'

That include pulls in the shared, centrally-governed config from the gitlab_templates project. Then a project can add its own lines below to tweak or override what it inherited. So you get: shared defaults + local control + no forced inheritance. If a project doesn't want the global stuff, it just doesn't write the include line, so there's an "opt-out" — nothing is imposed instance-wide.

The bad news

GitLab's include: mechanism is a feature of the CI/CD pipeline engine specifically. Description templates (issue/MR templates) don't have an equivalent include directive. They're just Markdown files that GitLab discovers by their location — .gitlab/issue_templates/*.md and .gitlab/merge_request_templates/*.md in the project's repo. There's no native "include the templates from that other project and extend them" syntax for description templates. So the literal answer to dww's "can it work exactly like .gitlab-ci.yml?" is no, not natively. (sad panda)

GitLab does have other mechanisms, but neither matches exactly:

  1. Instance template repository (this issue) — exists, works, but it's the "no opt-out" instance-wide setting drumm flagged, and on a self-managed instance the relevant inheritance features sit behind Premium/Ultimate tiers. (Do we have that?)
  2. Group-level templates — also exists, also Premium, and Drupal.org's project structure isn't organized into the GitLab groups this would need. But, we could add an "ai" group for the all the AI projects, for example, and have them all use the same templates, avoiding the massively sprawling UX issue.
  3. Port the The CI include: model to task descriptions and probably submit it upstream because this seems like something anyone would want to use.

^ I have not validated that this is true, but Claude wasn't able to find an existing upstream issue in a quick scan.

dww’s picture

Assuming these canonical templates are not changing very often, how about this?

A new default CI job (from gitlab_templates 😉) that offers to copy the tree from the shared copy into that project's own template directory.

? It would allow using CI customizations to then apply project-specific modifications, leave existing other templates untouched, etc.

dww’s picture

It could default to weekly, but you can trigger manually if needed. Doesn't have to run very often. Would be a very cheap / quick CI job. It allows everyone who wants the shared templates to easily get them, and keep them updated if they change. No changes to our GitLab instance needed. Full opt-in. We already have an easy mechanism to share the feature with all of contrib.

dww’s picture

p.s. The job could have a variable that controls which upstream repo of templates to merge. All the projects of type X that want to merge from a different shared set than the global default could easily do so. Basically solves point 2 from comment #5, too.

webchick’s picture

Back to @drumm in #3 as I parse what dww just said. :D

We should probably have at least a little consensus from project maintainers that the templates are generally good for most Drupal.org projects before deciding to suggest them for all projects. I believe there is not an opt-out for any given project.

As you point out, Drupal.org already ships a default issue template, and also forces a defined set of issue types as well, regardless of project. So this would more or less be carrying over our existing model, just instead of the "sledgehammer" approach of using the exact same set of headings to bug reports, feature requests, and meta issues alike... we get templates that are versioned, per-type, and customizable per-project.

My recommendation would be that we do the following (in this order):

  1. Ship what's in the AI project as a global default ~now-ish, so we can stop the template fragmentation that's actively happening right now, and also to show to newly migrated folks that GitLab gives us a chance to do things better than before. (Win!) Consider this starting point part of the GitLab migration.
  2. Open an issue in the Coding Standards project (maybe?), as this already has some governance around it for discussing, deciding, and notifying about new contribution norms.
  3. In that discussion, review the templates that are now already in GitLab as a starting point and make whatever recommended changes. Crucially, this consensus building now becomes an "edit job ("Let's remove 'Workarounds' from feature requests, that feels weird") not an "invent the standard from scratch" job. That's important because a) smart people already did a bunch of thinking on this topic, and they've put it into practice with dozens of contributors, and it makes sense to not throw out their work, b) now the reviewers / deciders of what the default templates should be can see+feel the forms themselves directly vs. trying to understand from more abstract Markdown how they would work once rendered.

That seems to satisfy the requirements to have community discussion/consensus around critical contributor workflow things (agreed) without allowing the fragmentation that currently is happening to compound with every new project that's migrated over.

cmlara’s picture

so we can stop the template fragmentation that's actively happening right now, and also to show to newly migrated folks that GitLab gives us a chance to do things better than before.

I'll note that GitLab issues is currently on Early Adopters, this is a group that probably should be fragmenting, trying new things and finding their own way without a solid consolidating force, learn from each other sure, however don't guide them to a prebuilt unless they ask for it directly.

I was part of gitlab_templates being created (though by the time it reached D.O. IIRC a lot of work had been done on GitLab.com with a base template we copied from) at times I believe we unified around a single setup too quickly without trying different options and evaluating the framework a bit more, we ended up with a strong template, however we could have flushed out more before it was built for production and potentially created a more robust design.

Re comments 6-8:

My recollection is that the default GitLab job token does not have write ability. This would require a user to save a PAT into the job. Given some recent discussions I'm not sure the Infrastructure team has a stable enough install at this time that we can trust placing secrets into the job config on G.D.O., especially if they have repository write permissions. Addtionaly PATS now expire at the 1 year mark, this would require regular updates work from each maintainer.

Feature requests often have Workarounds?

Likely more often than we think about.

webchick’s picture

I'll note that GitLab issues is currently on Early Adopters, this is a group that probably should be fragmenting, trying new things and finding their own way without a solid consolidating force, learn from each other sure, however don't guide them to a prebuilt unless they ask for it directly.

In general, I totally agree with this sentiment. In this particular case, however, it's a bloody nightmare 🤣 because the ~150 projects in the AI ecosystem have already decided they want to standardize on these templates.

Which means ~150 projects are getting (or soon to be getting) merge requests like this one https://git.drupalcode.org/project/ai_best_practices/-/merge_requests/39... that copy/pasta the main template files into each individual project.

That's in turn going to create ~150 individual copies of those templates that have no connection to their upstream sources, and therefore do not know to change when upstream changes, I guess unless ~150 individual projects implement CI rules like what dww is talking about (assuming they work, given the write permission restriction you've flagged).

OR! ;)

We could get out in front of that by making a decision early "These templates are good enough for now," put an end to people spending time and effort making ~150 copies, and instead point those efforts on aligning with other Drupal technical leaders who are NOT in the AI initiative on what future standards make sense for everyone.


And hey, look. We could also work around (ha! :)) this "fractal fragmentation" problem by assigning all ai* projects to an "AI Projects" Group and set group-level description templates for those projects and those projects only. But, like... why? :) Why create a confusing contribution experience on a new platform out of the gate? (The support requests write themselves: "How come my project doesn't have the Feature Request and Bug Report drop-downs? GITLAB SUX" ;)) Why not instead intervene early, when there are relatively few folks poking around, and raise the bar and provide consistency on GitLab's developer experience for ALL Drupal contributors at once?

cmlara’s picture

I know in GitLab you can override an upstream template, however can you remove one? I know several modules (and Core) for example do not believe in support requests and were looking forward to GitLab removing these options.

We could get out in front of that by making a decision early "These templates are good enough for now,"

In my experience every maintainer is different on what they want. I'm finally looking at the proposed templates and I see several that don't really match my workflows, meaning I'll likely be creating my own variant and never syncing back to the rest of the ecosystem.

The AI ecosystem is more an exception than a rule in that they spawned from an AI targeted initiative they might want to share.

I see several points that will likely cause similar issues for other modules either causing them to fork or for them to be removed from the general template once the community starts taking over editing them.

What happens when the templates are modified by community editing to the point they no longer work for the AI ecosystem? Aren't you in the same position of needing to duplicate to all the projects?

If anything this might be the perfect time to encourage maintainers to deviate from a unified template and embrace the format they want, ask the exact details that are relevant to them, the questions that will allow them to zone in without any other back and forth. This is not something standardized templates can likely give maintainers.

webchick’s picture

Title: Set up issue + merge request templates at a GitLab instance level » Set up AI issue + merge request templates at an "AI" group level and add all ai_ projects to it

I know in GitLab you can override an upstream template, however can you remove one? I know several modules (and Core) for example do not believe in support requests and were looking forward to GitLab removing these options.

Great question. Looks like no. :(

https://gitlab.com/gitlab-org/gitlab/-/work_items/452296

What happens when the templates are modified by community editing to the point they no longer work for the AI ecosystem? Aren't you in the same position of needing to duplicate to all the projects?

FAIR POINT, friend. :)

Ok then, rescoping this to hopefully be something less controversial.