Skip to content

Common workflows

Each recipe lists the steps, the right tools, and the verification. Follow them in order — the order matters.

"I want to add a field to an event group"

  1. Identify the change: a new field on group (bundle event). Owner module: fedms_federation.
  2. cd web/modules/contrib/fedms_federation
  3. Create / edit field storage:
  4. config/install/field.storage.group.field_<name>.yml
  5. Create field instance:
  6. config/optional/field.field.group.event.field_<name>.yml
  7. Add the file names to config_devel: in fedms_federation.info.yml.
  8. Add to form display:
  9. config/optional/core.entity_form_display.group.event.default.yml
  10. Add to view display:
  11. config/optional/core.entity_view_display.group.event.default.yml
  12. Verify locally:
  13. l3d drush cr
  14. Visit a clean install / event-edit form.
  15. Test:
  16. l3d ahoy test phpcsmodule fedms_federation
  17. l3d ahoy test phpstanmodule fedms_federation
  18. Commit on a branch, push, open an MR on fedms/components/federation.

"I want to add a field to a fedms_event (the content entity)"

Same as above but the owner is fedms_content and the config filenames are:

  • field.storage.fedms_event.field_<name>.yml
  • field.field.fedms_event.<bundle>.field_<name>.yml
  • core.entity_form_display.fedms_event.<bundle>.default.yml
  • core.entity_view_display.fedms_event.<bundle>.default.yml

"I want to add a new task-pattern condition"

  1. Owner module: fedms_task.
  2. Create a new ECA event plugin under src/Plugin/ECA/Event/<MyCondition>Event.php. Follow the pattern of TaskPatternConditionEvent.php.
  3. Register the corresponding _arguments event plugin under TaskPatternConditionArgumentsEvent.php (if your condition needs arguments).
  4. Update the task_api ECA model to add the new event:
  5. Open the modeler at /admin/config/workflow/eca.
  6. Add events for both the condition and (if needed) its arguments.
  7. Wire them into the appropriate flow.
  8. Save the model.
  9. Export config:
  10. l3d ahoy fedms export-config
  11. Inspect the diff in fedms_eca:
  12. cd web/modules/contrib/fedms_eca && l3d git diff
  13. Test:
  14. l3d ahoy test phpcsmodule fedms_task
  15. l3d ahoy test phpstanmodule fedms_task
  16. l3d ahoy test phpunitmodule fedms_task
  17. Open coordinated MRs on fedms/components/tasks (the plugin) and fedms/components/eca (the model). Reference each other.

"I want to change an ECA model"

  1. Identify the model. See Developer guide → ECA models.
  2. Read the per-model page.
  3. Open the modeler at /admin/config/workflow/eca.
  4. Make the change visually.
  5. Save in the modeler.
  6. l3d ahoy fedms export-config
  7. cd web/modules/contrib/fedms_eca && l3d git diff
  8. Verify the diff only contains the model you intended.
  9. Commit, push, open MR.

Never edit eca.eca.*.yml files by hand.

"I want to add a new module-owned permission"

  1. Identify the module that owns the permission.
  2. Edit <module>/<module>.permissions.yml:
1
2
3
'my new permission':
  title: 'My new permission'
  description: '...'
  1. Update fedms_federation/config/roles_permissions.yml to assign the permission to the appropriate roles.
  2. Rebuild:
  3. l3d drush roles-permission-builder:rebuild
  4. Export config:
  5. l3d ahoy fedms export-config
  6. Test, commit, push.

"I want to add a new view"

  1. Identify the right module:
  2. Lists of groups → fedms_federation.
  3. Lists of events/sessions content → fedms_content.
  4. Lists of tasks → fedms_task.
  5. Create the view in the admin UI.
  6. Export config:
  7. l3d ahoy fedms export-config
  8. Move the resulting views.view.<name>.yml to the owning module's config/install/ (or config/optional/ if it depends on optional config).
  9. Add the file name to the module's config_devel: list.
  10. Test, commit, push.

"I want to add a new recipe"

  1. Fork the parent recipe scaffold at fedms/components/recipe.
  2. Create a new project under fedms/components/recipes/<name>.
  3. Edit recipe.yml — set name, description, install list, inputs, config actions.
  4. Add starter config under config/.
  5. Test locally: 
    1
2
    l3d composer require fedms-recipe/<name>:dev-develop
l3d drush recipe ../recipes/fedms-recipe-<name>
  6. Open MR, get review, tag a release.
  7. Add to fedms profile's composer.json if the recipe should be available to every tenant.

"I want to fix a documentation bug"

  1. Identify the right page on this site. See Where things live → Documentation.
  2. cd mkdocs
  3. Edit the relevant .md file.
  4. Preview locally (see mkdocs/.ahoy.yml).
  5. Commit on a branch in fedms/documentation, open an MR.

"I want to update the AGENTS.md or this AI agents section"

When you discover a convention that an AI agent should know, add it here in the same MR as the change that motivated it. Don't file it as a separate "doc TODO" — by the next session, that TODO will have lost context.

Specifically:

  • Site-specific conventions → site's AGENTS.md.
  • Cross-project FedMS conventions → ~/.opencode/skills/fedms/SKILL.md.
  • User-facing or developer-facing documentation → this site.

"I want to verify my change against the documentation"

Whenever you make a change that affects user-facing behavior:

  1. Find the documentation pages that describe the behavior.
  2. Update them to match your change.
  3. If your change introduces a brand-new behavior, add a page (or section) that describes it.
  4. Commit the documentation update in the same MR series as the code change.

"I want to investigate an issue"

  1. Find the issue at gitlab.lakedrops.com/fedms — it lives on one of the per-component projects.
  2. Read the issue and all its comments.
  3. cd into the right repo (per Where things live).
  4. l3d glab issue view <id> for the in-CLI view.
  5. Check linked MRs:
  6. l3d glab mr list
  7. Read the relevant code and the relevant docs.
  8. Form a plan.
  9. Open a branch, write code, write tests, write docs, open MR.

Next steps