masque follows a published, two-phase policy. The phase boundary is the 1.0.0 release.
Pre-1.0 (current)
Versions 0.x.y follow an additive-by-intent policy: every minor release (0.x to 0.(x+1)) is meant to add new exports without breaking existing signatures. The track record so far:
0.2.0: first public surface (11 exports).0.3.0: addeddetect_design(),plot_design_summary(), and thedesign_summaryS7 class.propose_roles()gaineddetect = TRUEas a new default withdetect = FALSErecovering v0.2.x behaviour byte-for-byte. No breaking changes.0.4.0: addedsynthesise_geospatial(). No breaking changes.0.5.0: joint-treatment masking; thekeeprole; first-class date/time covariates. No breaking changes.0.6.0: the two-axis roles model: the roles table gains anactioncolumn and the role vocabulary changes (keep/ignorebecome thekeep/dropactions; new rolesdate/id/text/other). New exports:masque()(guided verb),set_role(),clean_table(),mask_set(),read_set(),write_set().mask()no longer requires anoutcome. This is a breaking change, listed inNEWS.md. Roles tables built by masque <= 0.5.0 are upgraded automatically with a one-time deprecation warning, so existing scripts keep working; the warning signposts re-runningpropose_roles().0.7.0: added opt-in conditional numeric synthesis. No signature breaks.0.8.0: strengthened warning propagation and the package-managed write gate. Addedallow_highat the end of affected signatures. Behavioural safety change, listed inNEWS.md.0.9.1: supersedes the untagged 0.9.0 release candidate. Added the append-onlyenvargument todetect_design()and additive environment-scope properties todesign_summary. Conservative automatic scope detection changespropose_roles()defaults for high-confidence MET environment columns.env = FALSEanddetect = FALSEretain the former detector and name-only role paths.mask()andmask_set()now inherit the mode provenance recorded on role plans whenmodeis omitted, with an explicit warning for a downgrade. Behaviour changes are listed first inNEWS.md.0.9.2: addedjitter_coordinates()and themask()coordsargument. No breaking changes.0.10.0: the geomask now draws one displacement per site rather than per row, and a site that cannot be placed on land fails closed toNAinstead of retaining its true coordinate.jitter_coordinates()gainsby(appended afterlon_col), and a coordinate spec passed tomask(coords = )acceptsby.by = FALSErecovers the pre-0.10.0 per-row behaviour, and genuinely point-level input reproduces its 0.9.2 output exactly under the same seed. This is a behaviour change and a confidentiality fix, listed first inNEWS.md.0.11.0: a coordinate column kept unmasked now stopsmask()unless the caller states otherwise, viacoords, a masking action, or the newallow_unmasked_coordsargument (appended, defaultFALSE). Value-shaped coordinate detection warns rather than stops.audit_mask()no longer classes a geomask-coarsened coordinate as HIGH. Behaviour change, listed first inNEWS.md.0.12.0: addedconform_table(). The collaborate-mode alias map is drawn from a seeded random permutation instead of the sort order, which changes the integer codes of an aliased factor.conditional = TRUEcoarsens its strata until they are large enough, instead of pooling the whole clone silently. Behaviour change and a confidentiality fix, listed inNEWS.md.0.13.0:mask(),mask_set()andmasque()gainladder(appended). The new default,"hierarchy", coarsens a conditional clone along the design hierarchy;ladder = "levels"reproduces 0.11.1 to 0.12.0. Breaking change, listed first inNEWS.md.0.14.0: a scrambled factor keeps the original level order, and an aliased join key lists its aliases in sorted order, solevels()of a clone no longer reveals its label map. Values under the same seed are unchanged.apply_recipe()returns the clone’s level order. Confidentiality fix, listed first inNEWS.md; re-make any clone shared from 0.13.0 or earlier.0.15.0: every returned table is adata.tableinstead of a tibble, and tibble leaves the dependencies. Signatures and values are unchanged. Breaking change for code that relies on tibble behaviour, listed first inNEWS.md.-
0.16.0: new exportsdata_card()androles(). New arguments, each with a default:-
mask():events,grain,allow_kept_outcome -
mask_set():grain,allow_kept_outcome,sheets,info,... -
masque():detect,sheets,info,... -
reveal_maps():table
In
mask()the new arguments sit beforeallow_unmasked_coordsandquiet, and inmask_set()beforequiet, so a call that passes those by position must name them.Default clones change for tables with a column constant within a design unit (
grain = FALSErestores 0.15.0), for collaborate jitter (no longer clipped to the observed range), for numeric treatments (aliased in collaborate mode) and formask_set()link aliases made with a seed. A kept outcome audits HIGH in collaborate mode. Recipes saved by 0.15.0 still load and apply. Behaviour changes, listed first inNEWS.md. -
Additive by intent is not frozen: before 1.0 a release may break an existing signature when a design flaw surfaces, but every such change must be:
- Listed under a
## Breaking changesheading inNEWS.md, first. - Justified in the release notes.
- Where feasible, accompanied by a temporary back-compat shim.
If you depend on masque before 1.0, set a version floor in DESCRIPTION (Imports: masque (>= 0.14.0)) and record the exact version with renv (renv::snapshot()).
1.0 and after
From 1.0.0, masque adopts a frozen API:
- Signatures of exported functions never change in a backwards-incompatible way within a major version.
- New capability arrives via new entry points (new exports), never via changes to existing ones.
- If an existing function genuinely needs to be retired, it is marked with
lifecycle::deprecate_warn(), kept for at least 2 minor versions, then promoted tolifecycle::deprecate_stop()for at least 1 more minor version, then removed in the next major release. Successors are signposted in the deprecation message.
Pipeline code written against a clone is later run unchanged on the real data, so it has to keep working when masque is upgraded.
Versioning and tags
masque uses Semantic Versioning 2.0.0. Every release is git-tagged vX.Y.Z on main; the tag is annotated and carries the NEWS.md entry as its message.
Reporting an unintended break
If you discover that a masque release has silently broken your pipeline, open an issue at https://github.com/max578/masque/issues with the version you upgraded from and to plus a small reproducible example. Unintended breaks at any stage are treated as bugs.
