Working with features

A feature is a Python package with its own version that adds one piece of functionality to a product. It owns its routes, models, migrations, templates, assets, seeders and tests, and a product is a set of features.

Below each state, what moves a feature into it. feature:status shows where every feature of the product is.

Editable and pinned

Kind	Where it lives	Use it for
Editable	A git working copy at the workspace root, `<workspace>/<feature>/`. Your edits take effect at once	Development
Pinned	A read-only clone of a tag, `.splent_cache/features/<namespace>/<feature>@<version>/`	Stable and production products

Editable and pinned features explains how to declare each and how to move a feature from one to the other.

Naming a feature

Most commands take a feature as [namespace/]feature[@version].

You write	It means
`splent_feature_notes`	Editable, in the default namespace (`splent_io`)
`splent-io/splent_feature_notes`	Editable, in an explicit namespace
`splent_feature_notes@v1.2.7`	Pinned, in the default namespace
`splent-io/splent_feature_notes v1.2.7`	Pinned, as two arguments, the way `feature:attach` takes it

The namespace is splent_io on disk and splent-io on the forge, and the CLI accepts both. A bare name works for commands that act on a feature you already have, such as feature:test. feature:create, feature:add and feature:clone need the namespace, and stop with Invalid format without it.

Where features live

<workspace>/
├── splent_feature_notes/                  ← editable copy
└── .splent_cache/features/splent_io/
    ├── splent_feature_notes@v1.2.7/       ← pinned snapshot
    └── splent_feature_auth@v1.5.8/        ← pinned snapshot

A product reaches each feature through a relative link in its features/ folder.

my_first_app/features/splent_io/splent_feature_notes@v1.2.7
  → ../../../.splent_cache/features/splent_io/splent_feature_notes@v1.2.7
my_first_app/features/splent_io/splent_feature_notes
  → ../../../splent_feature_notes

Command sections

Section	Commands to
Feature Discovery	Find, list and inspect features
Feature Lifecycle	Create, fetch, add and remove features
Feature Development	Work on a feature day to day
Feature Contracts & Hooks	Contracts, extension points and template hooks
Feature Release	Release and upgrade features

The full state machine is in Feature lifecycle.