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 commands that move a feature between pinned and editable PINNED splent_feature_shop@v1.17.0 A snapshot in .splent_cache/ Read-only, one per version What production accepts EDITABLE splent_feature_shop A working copy at the root Read-write, shared Development only feature:unlock feature:add feature:release --attach feature:attach <version> feature:pin, feature:upgrade
Unlocking turns a snapshot into a working copy. Releasing, attaching, pinning or upgrading points the product at a snapshot again.

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 -e and SPLENT’s editable are different ideas. In development both kinds are installed with pip 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


Back to top

splent. Distributed by an LGPL license v3. Contact us: drorganvidez@us.es