Families

A feature is not an option. It is an option, a post type, a field on other posts, a value in another artifact and a step the target needs afterwards. A family names all of them, and the tree holds them together or not at all.

Why a settings group was not enough

A plugin’s feature seldom lives in one place. A theme keeps its redirects as posts of a type of its own, and clears the cache it reads them from only through its own form. It keeps its SEO fields as post meta on ordinary pages and switches two flags in the page builder’s settings when it takes over. The tree knew a settings group and a content group, one declaration per place, and nothing said the two belonged together.

That is how two features fell through the report. The redirects travelled as a post type and answered 404 for twelve hours, because the transient stayed. The SEO fields travelled as options and meta, and the flags in the builder’s tree did not. cwp coverage judged each area on its own and called both tracked.

What a family names

A family is one feature with every place it keeps state. Seven kinds of member, each optional:

Member	What it is
toggle	the option, or the key inside one, that switches the feature on
options	a settings group: keys, and a class per path saying what each value is
content	a post type with its meta, and the term meta beside it
post_meta, term_meta	what the feature writes on other groups’ posts and terms
asserts	a value another artifact’s option has to hold, checked and never written
settle	what the target needs after the data landed: a transient cleared, the rewrite rules flushed
refuse	what never travels: the log post types and tables the scrub removes, the markers the plugin derives

A family is data: one YAML file per plugin or theme. cwp ships one for every owner it has read against a live install, and you add your own under cwp/families/. The file’s shape is on the cwp.yml reference.

Switching one on

You name the family in cwp.yml, and the owner has to be in inventory.yml:

features:
  snn-brx-child-theme/seo: on
  snn-brx-child-theme/redirects: on
  snn-brx-child-theme/logs: settings-only

on carries every member. settings-only carries the options and nothing that is content or log. off and absence are the same thing. What a family refuses, the scrub cuts in either mode but off: a log the tree does not carry is not a log the local database keeps.

When cwp reads the file, the family expands into the groups every command already reads. Those are a settings group named <owner>/<family>, a content group of the same name, meta rules on the other groups and the scrub’s lists. The expansion is visible. cwp coverage shows one row per family, and cwp pull writes the same files it would write for a group you had typed by hand.

A family and a group you wrote yourself cannot both claim a key or a post type. cwp refuses that when it reads the file, with the name of the group to remove.

Whole or not at all

Three things hold a family together on the way up.

A push checks every assert on the target before it writes. A family that says the page builder must hold disableSeo: true stops the push when the target holds false, before any write, and names the line. A pull warns instead: the source is what it is.

A settle step is an effect of the push. It stands in the plan after the artifacts. The dry run lists it, the confirmation names it, and one that fails is a push that did not arrive. Two families naming the same step get one, and the flush of the rewrite rules runs last.

Half of a family does not go up. cwp refuses a settings file beside content directories nobody pulled, or the other way round. It names both paths and the two ways out: pull the missing half, or switch the family off.

What the report says

  family                        mode   options   post types   post meta   term meta   asserts   settle       verdict
✓ snn-brx-child-theme/seo       on     29/29     –            3/3         3/3         2/2       1 recorded   tracked
! snn-brx-child-theme/redirects on     –         1/1          –           –           –         3 recorded   half carried
  snn-brx-child-theme/redirects: options not pulled yet: cwp pull --only settings
  snn-brx-child-theme/security  available

available is a family cwp knows for a plugin the site has and features: does not name. cwp coverage --suggest prints the line that switches it on.

What a family does not do

• It carries no executable code. A theme’s code snippets are PHP the site runs. A family names the switch and never the code; a project that wants the code writes the group by hand, where a reviewer sees the line.
• It writes nothing into another artifact. A family asserts the two flags in the builder’s settings and never sets them. Setting them would be a second writer for a name the builder’s tree carries.
• It replaces no group you wrote. settings: and content: stay for everything no family knows.

Where to go next

• cwp.yml has the file a family reads from and every key it accepts.
• cwp coverage is where a half-carried family shows first.
• The tree is what a family expands into.