Add, Change, or Exclude a Feature

Curation decides which Artemis candidates become features of the model, and how. This page walks through one curation change from the decision to the pull request. You need it when a run reports an undeclared candidate, or when a module that the model leaves out should finally become a feature.

Before you begin

Run the pipeline locally once, as described in Run the Pipeline Locally, and open the report. Look at the candidate in scan/feature-candidates.json and its evidence in scan/evidence.json, so that you know what Artemis says about it.

Decide

Ask whether someone setting up Artemis would choose this feature for a deployment. If yes, model it. If not, list it in notModeled with one of the reasons the manifest already uses:

Reason	Use it when the candidate is…
sub-option	a detail of a feature the model already has
internal-mechanism	infrastructure or a Spring profile that only serves other parts
operational	a safeguard of operations, such as rate limiting
experimental	a research or trial setting
deferred	a real feature that the model does not cover yet

Only a module that Artemis presents as a feature must be decided. A runtime toggle or a Spring profile without an entry stays out of the model on its own; add a notModeled entry only when you want to record why.

When you model a module, also decide:

• where it sits in the tree (group or parent) and in which order;
• whether it is mandatory or optional (the default);
• whether it depends on or excludes another feature.

A deployment choice for maintainers, such as a database, is a technical entry instead; see The Feature Manifest.

Edit the manifest

Add the entry to the features list of src/main/resources/feature-model/extraction/artemis-feature-manifest.yml. Its id is the Artemis module id. A simple optional module needs only two lines:

- id: ldap
  group: platform-integrations

To model a module from notModeled, delete its notModeled entry and add the features entry. The pipeline takes the name, the description, the default state, and the configuration keys from Artemis, and derives the capabilities the feature needs from those keys. The Feature Manifest lists every field.

Run the pipeline

./gradlew buildFeatureModelSnapshot -PartemisPath=../artemis-extraction

Check the report: the candidate appears under included features or excluded candidates. For a modeled feature, look at its keys in the Configuration derivation section of the report. Every key that a deployment must provide, such as a service URL or a secret, should be there as a deployment input.

When a key is missing, the pipeline cannot see it in the source, for example because a library reads it. Add it as a configuration entry. When a derived key does not belong to the feature, reject it with action: exclude.

A CONFIG_KEY_CATALOG_DRIFT error means that a mapped key has no default in the Artemis application*.yml files. Check the spelling of the keys you added. When the error names the module's own on/off key, the module is switched on by a key without a default, for example a service URL. Such a module needs a developer to decide how its configuration is mapped before it can be modeled.

Update the guided workflow

An included functional feature needs an option in the guided workflow, or teachers cannot choose it. Run the scaffold, which adds a draft option for every uncovered feature, and write its text:

./gradlew syncGuidedWorkflowScaffold

Update the Guided Workflow explains the details. Technical features need no guided option.

Update the Ansible bindings

The remote deployment package must know every selectable feature. Classify the new feature in src/main/resources/deployment-bindings/artemis-ansible-binding-catalog.yml as bound, no-op, or unsupported, as described in Update Ansible Bindings. The server tests fail until you do.

Refresh the fixture and test

Copy the new model into the classpath fixture and run the tests:

./gradlew -q refreshFeatureModelFixture -PsnapshotPath=build/feature-extraction/<source-revision>/snapshot
./gradlew test

Start the application and look at the feature in the Explorer and the Configurator, as described in the Developer Guide setup.

Checklist

1. The manifest has a features or notModeled entry for the module.
2. The pipeline passes locally.
3. An included functional feature has a published guided option.
4. The binding catalog classifies an included selectable feature.
5. The classpath fixture is refreshed, and ./gradlew test passes.
6. When the change answers a failed run, the validation pin names the failing commit, see Fix a Failed Run.