Skip to content

Contributing

This page describes the workflow for changing any FedMS repository — the install profile, a component module, a recipe, a tenant site, the test suites, or the documentation.

Prerequisites

  • L3D installed and working. See Tooling → L3D.
  • glab authenticated against gitlab.lakedrops.com. See the gitlab opencode skill if you're an AI agent.
  • The site running locally — l3d ahoy d4d update.

The change workflow

1. Find or create an issue

Issues live on the relevant component project, not on the group. For example, a federation bug goes to fedms/components/federation, a task-engine bug goes to fedms/components/tasks.

If you can't find a matching issue, create one:

1
2
cd web/modules/contrib/fedms_X    # or wherever the change belongs
l3d glab issue create --title "..." --description "..."

2. Identify the right repo

Use this table:

Change Repo
Group fields / federation hooks / permissions YAML fedms_federation
fedms_event / fedms_session entity or paragraph types fedms_content
Attachment entity fedms_attachment
Task entity / pattern / condition plugins / spawning logic fedms_task
ECA model fedms_eca
Translations fedms_locale
Install pipeline / Ahoy commands fedms/components/scripts
Optional recipe A fedms/components/recipes/* repo
Test infrastructure fedms/components/tests/playwright
Tenant site issues The tenant's site repo (fedms/sites/<name>)
Documentation fedms/documentation

cd into the right directory before running l3d glab / l3d git.

3. Branch

1
2
3
4
cd <repo-dir>
git checkout develop
git pull
git checkout -b feature/<short-slug>   # or fix/<short-slug>

Branch naming conventions:

  • feature/<slug> for new functionality.
  • fix/<slug> for bug fixes.
  • docs/<slug> for doc-only changes.
  • chore/<slug> for non-functional housekeeping.

4. Make the change

Follow the conventions:

  • US English (en-US) — cspell will reject British English.
  • OOP hooks with the #[Hook] attribute.
  • declare(strict_types=1); in new PHP files.
  • Use constructor DI for services.
  • Add PHPDoc to public methods.
  • Add tests where reasonable.
  • Don't hand-edit eca.eca.*.yml — go through the modeler.
  • Don't add Cypress tests — Playwright only.

5. Test locally

1
2
3
l3d ahoy test phpcsmodule <module>
l3d ahoy test phpstanmodule <module>
l3d ahoy test phpunitmodule <module>

For ECA model changes:

1
2
3
l3d ahoy fedms export-config
cd web/modules/contrib/fedms_eca
l3d git diff

For Playwright changes:

1
2
cd tests/playwright
l3d npx playwright test

6. Commit

Commit in imperative mood, with a short subject:

1
2
3
4
Add task pattern successor logic

Implements the successor chain when a task is marked complete.
Closes fedms/components/tasks#15

Reference the issue with Closes fedms/components/<project>#<id> when the change fully resolves it. Use Relates to ... when it only partially addresses it.

1
2
3
git add <files>
git commit -m "..."
git push -u origin feature/<short-slug>

7. Open an MR

1
l3d glab mr create --fill --target-branch develop

Fill in the MR description with:

  • A summary of the change.
  • The reason (link to the issue).
  • A test plan — what you ran locally.
  • Any screenshots for UI changes.

8. Verify CI

1
l3d glab ci status

If the pipeline fails, pull the logs:

1
2
l3d glab ci view
l3d glab ci trace <job-name>

Fix locally, push, and re-check.

9. Address reviews

1
l3d glab mr view --comments

Make the requested changes, commit, push. The MR's pipeline re-runs automatically.

10. Merge

Once approved and green:

1
l3d glab mr merge --squash --remove-source-branch

(Or let the reviewer merge.)

11. Tag a release if needed

For module changes that other repos depend on, tag a release after merge. See Release process.

Cross-cutting changes

Some changes touch multiple repos — e.g. a new ECA condition that requires:

  • a new plugin in fedms_task,
  • a model update in fedms_eca,
  • an MR in each.

For these:

  1. Open a tracking issue in the most central repo (often fedms/components/profile).
  2. Open MRs in each affected repo, linking to the tracking issue.
  3. Coordinate merge order — usually plugin first, model second.
  4. Tag a synchronised release of the affected modules.

US English enforcement

The cspell pipeline uses a US-English dictionary. Common substitutions:

❌ Avoid ✅ Use
behaviour behavior
colour color
organisation, organise organization, organize
optimise, optimisation optimize, optimization
analyse analyze
customise customize
modeller modeler
artefact artifact
labelled labeled
cancelled canceled
programme (in software) program
centre center

This applies to code, comments, commit messages, MR titles and descriptions, issue summaries, and in-repo documentation.

What never to commit

  • Secrets (API keys, passwords, tokens).
  • .env files (.env is .gitignore'd but verify before commit).
  • Tenant-specific content in framework modules.
  • Hand-edited eca.eca.*.yml files.

Next steps