Follow Artemis Source Changes
Sometimes Artemis changes not its features but the place or shape of its source: a folder moves, a file is renamed, a configuration key gets a new name. The pipeline then stops finding what it used to find. This page shows how to recognize such a change and where to adapt this repository.
Symptoms
| What you see | What changed in Artemis |
|---|---|
MANIFEST_ORPHAN_ANCHOR for candidates that still exist in Artemis | A scanned file or folder moved, so the scan no longer finds the candidates |
EXTRACTOR_ERROR | A scanned file changed its structure, and the scanner cannot read it |
MANIFEST_ORPHAN_ANCHOR together with UNDECLARED_CANDIDATE | A module was renamed |
MANIFEST_ORPHAN_ANCHOR for a technical feature | A Spring profile or a Compose file of a technical feature was renamed |
CONFIG_KEY_CATALOG_DRIFT | A configuration key that the model maps was renamed or removed |
An example: when Artemis moved its Docker Compose files from docker/ to deployment/docker/, the scan stopped
finding the database stacks. The run failed with MANIFEST_ORPHAN_ANCHOR for infra:mysql and infra:postgres,
although both databases were still there.
A moved or restructured file
The pipeline finds Artemis files through
src/main/java/de/tum/cit/aet/artemis/featuremodel/extraction/source/ArtemisSourceConventions.java.
Source Scanners explains what each scanner reads.
- Find the new location or shape of the file in the Artemis commit that failed.
- Update the path, root, or symbol in
ArtemisSourceConventions. A changed file structure may also need a change in the scanner itself; ask a developer when you are not sure. - Mirror the new layout in the small test checkout
src/test/resources/extraction/mini-artemis/, so that the tests cover it. - Run the tests and the pipeline against the failing commit.
A renamed feature
A rename is a curation change. For a technical feature, point the entry to the new anchor and keep its id, so that
the model and the packages stay unchanged:
- anchor: profile:new-name # the current anchor in Artemis
id: old-name # the feature id stays
The anchor of a functional feature follows from its id, the Artemis module id. When Artemis renames a module,
rename the features entry, and then every reference to the old id: the options and review groups in
src/main/resources/feature-model/guided-workflow.json and the entry in the Ansible binding catalog. Run
./gradlew syncGuidedWorkflowScaffold afterwards; it reports every reference to an id the model does not have.
A renamed configuration key
A key that the pipeline derives follows on its own, because the pipeline reads the new name from the source. A key that
a configuration entry of the manifest declares needs an update of its key. The pipeline rebuilds the config-key
catalog from the mappings and the Artemis defaults, so the catalog follows on its own. The application's copy of the
catalog changes with the next fixture refresh; a test fails as long as a mapping in the classpath model is missing from
that copy.
Changes that reach the generated packages
The deployment packages refer to Artemis files as well: the Compose files of the Docker package, the Spring profiles of the IDE package, the variables of the Ansible collection. The pipeline derives the Compose files of the database features from the scan, so they follow a move as soon as the scan finds the files again. The package writers hold the other paths. When Artemis moves such a file, ask a developer to adapt the writers, as described on Deployment Packages.
Verify
Run the pipeline against the exact commit that failed, then run the tests:
./gradlew buildFeatureModelSnapshot -PartemisPath=../artemis-extraction -PexpectedArtemisSha=<artemis-commit>
./gradlew test
To also run the smoke test that reads a real Artemis checkout, pass the path to the tests:
./gradlew test -PartemisPath=../artemis-extraction --tests '*RealArtemisCheckoutSmokeTest'
Then open a pull request as described in Fix a Failed Run.