Editable and pinned features
Table of contents
Introduction
Every feature your product declares is either editable or pinned. An editable feature is a working copy you change. A pinned feature is a read-only snapshot of a release, the same on every machine. You develop with editable features and ship pinned ones, and the CLI moves a feature between the two.
[tool.splent]
features = [
"splent_io/splent_feature_shop@v1.17.0", # pinned
"splent_io/splent_feature_reports", # editable
]
An entry with @<tag> is pinned, and one without is editable. Nothing else decides the mode.
How the two differ
| Editable | Pinned | |
|---|---|---|
| Entry | The name alone | The name plus a tag, @v1.17.0 |
| Code lives in | A working copy at the workspace root | A snapshot under .splent_cache/features/ |
| Files | Read-write, one copy shared by every product | Read-only, one copy per version |
| Your edits | Reach the development app without reinstalling | Not allowed. Unlock the feature first |
db:migrate |
Generates migrations | Skips the feature |
| Production | Refused | Required |
| Brought in with | feature:add |
feature:attach |
The production image asks PyPI for the tag without its v, so @v1.17.0 installs splent_feature_shop==1.17.0, or the git tag when PyPI does not serve it.
Where each lives on disk
Your product holds no feature code. features/<namespace>/ holds one relative symlink per entry, named like the entry.
splent_workspace/
├── splent_feature_reports/ ← working copy, read-write
├── .splent_cache/features/splent_io/
│ ├── splent_feature_shop@v1.16.0/ ← snapshot, read-only
│ └── splent_feature_shop@v1.17.0/ ← snapshot, read-only
└── my_first_app/features/splent_io/
├── splent_feature_shop@v1.17.0 → the v1.17.0 snapshot
└── splent_feature_reports → the working copy
Two products that declare splent_io/splent_feature_reports without a version share the working copy, so a change for one reaches the other. Pin the feature in a product that must stay on a known release. SPLENT Cache covers the snapshots.
If you edit the feature lists by hand, run product:resolve so the symlinks follow.
What happens to your edits
An editable feature is installed with pip install -e through its symlink, so a change to its code or templates reaches the development server at once. Commit and push from the working copy like any repository.
A snapshot is read-only, and commands that change code skip it. db:migrate tells you to run feature:unlock, and lint checks only the features at the workspace root. A change forced into a snapshot would not travel anyway, since the production image never reads the cache.
Moving between the two
The usual round trip is to unlock, fix, and release.
# Turn the pinned feature into a working copy at the workspace root
splent feature:unlock splent_feature_shop
# Edit, test, commit and push in <workspace>/splent_feature_shop
# Cut v1.17.1 and pin the product to it
splent feature:release splent_feature_shop --bump patch --attach
Your product now declares @v1.17.1. The working copy stays, so the next feature:unlock reuses it and pulls main.
| Command | From | To | What it does |
|---|---|---|---|
feature:add |
Not declared, or pinned | Editable | Links the working copy at the workspace root, which must exist |
feature:attach |
Not declared, editable, or another version | Pinned | Fetches the tag into the cache if needed and links it. A tag the forge lacks is refused |
feature:unlock |
Pinned | Editable | Copies the snapshot to the workspace root when needed, makes it writable, switches to main and pulls |
feature:release |
Editable | Pinned | Cuts a version and attaches it, after asking or at once with --attach |
feature:pin |
Editable | Pinned | Pins every editable entry to the highest version in the cache, without asking the forge |
feature:upgrade |
Either | Pinned | Moves an entry to the latest tag on the forge |
feature:outdated |
Pinned | Pinned | Lists the pinned features behind the forge. --upgrade upgrades them |
feature:detach |
Pinned | Editable entry, no symlink | Removes the symlink and drops @version |
feature:remove |
Either | Not declared | Removes the entry and its symlink. The working copy and the cache stay |
Each command edits only the entries it changes, as Commands that edit it explains. To take a pinned feature out of a product, use feature:remove, since feature:detach leaves an editable entry behind.
feature:install does the first steps in one. With --editable it clones the working copy and runs feature:add. With --pinned it fetches the release and runs feature:attach.
Which one to use
Use editable while you work on the feature itself, such as writing a new one with feature:create, fixing it, or generating a migration.
Use pinned whenever you only use the feature, and always for production. It keeps every machine on the same code and keeps your product away from someone else’s work in progress.
A product in daily development is often mixed. Before production, release each editable feature you changed and attach the new version, or run feature:pin. The product:build pre-flight names any feature still without a version.
Environment rules
Development takes both kinds. Production takes only pinned features, because the image installs from PyPI or a git tag and cannot reach a working copy.
| Command | Editable entries | Pinned entries |
|---|---|---|
product:resolve |
Links the working copy, or reports it missing. Never clones one | Clones the tag when missing, then links it |
product:build |
Fails the pre-flight for an entry in features or features_prod |
Each version must be published and resolved |
product:derive --prod |
product:build warns and asks, defaulting to no |
Accepted |
product:release |
Refused in any of the three lists | Required |
product:build never reads features_dev, so an editable development-only feature does not block a build. product:release reads all three lists, because a release must be reproducible.
Advanced
pip’s
-eand SPLENT’s editable are different ideas. In development both kinds are installed withpip install -e, and only the directory behind the symlink differs. Production installs nothing from the workspace, so an editable entry would get whatever PyPI has under the name.
The namespace can be written splent_io or splent-io, and commands keep the spelling your product uses. A feature is declared once, and feature:add and feature:attach replace any earlier declaration of it. feature:pull pulls every working copy, and feature:discard deletes one.
See also
- SPLENT Cache, how snapshots are stored and pruned
- pyproject.toml, the three feature lists
- Feature state, where the manifest records each feature’s mode
feature:pip-install, how the production image installs features