Skip to content

Upgrading

Two separate things upgrade here.

  • The installation: a new release installs alongside the ones you already have and disturbs none of them.
  • A project: your results, and a project belongs to one release for as long as it exists.

Coming from 2.2.0 or older, read Coming from 2.2.0 alongside this: 3.0 moved where things live, not just the settings.

1. Install the new release

Get it and install it exactly as you did the first time (Install).

  • Nothing is replaced. ~/.local/opt gains a directory, ~/.local/bin gains a PoolSeqFlow-<version> command, and plain PoolSeqFlow starts meaning the new one. Every earlier release still runs under its own name.
  • Your projects are untouched: parameters.config lives in your project directory, not in the installation.
  • The new release's module store starts empty. No module ships inside a release, and the store belongs to the installation that runs it, so the old release keeps what you installed into it and the new one has nothing.

Ask the old release what to reinstall, then install each into the new one:

PoolSeqFlow-3.0.0 analysis modules list      # what the old release has
PoolSeqFlow analysis modules install mds     # and again, into the new one
PoolSeqFlow analysis modules install all     # or every module published for the new one

Nothing is lost by this. A module installs the libraries it needs along with it, and the analyses it has already produced are results; no install or uninstall reaches them.

2. Bring each project's configuration forward

Run this in each project directory, before the first run under the new release:

PoolSeqFlow migrate_config
  • An update never touches parameters.config, because it must not silently change your analysis settings. So after a new release your file can be missing parameters the newer code expects.
  • migrate_config saves your file as parameters.config.bak, rebuilds it from the current template, carries across every setting whose parameter still exists, and reports what happened to each one.
Report Meaning
Kept your value The parameter still exists and your setting was carried over
Renamed this release The parameter was renamed and your value followed it to the new name
Now computed by the pipeline This release derives the value; yours was ignored
Format changed this release The value's meaning or format changed, so the template's wins
New in this release The template has a parameter your file did not; review the default
Still yours to set The pipeline works the value out itself now, and your new config carries the parameter commented out; uncomment it to take it back
No longer used Your file had a parameter this release does not use

Still yours to set is not a loss, and is distinct from Now computed by the pipeline, where the value is derived from other parameters and there is no line to uncomment. Coming from 2.2.0 it covers thirteen parameters: the eight cores values and the five options strings your file already had.

Move the files it names. It ends with a list and moves none of them, printing the exact mv commands for the files it found. From 2.2.0 or older there will be several, because your reads, reference and sample table used to live under the storage directory and now belong on mainDir.

.poolseqflow_params and its neighbors matter most in that list. They are the records the change guard compares against. Leave them behind and the next run finds no record, decides the project is new, and writes your current configuration down as though it had produced the results already on disk. The guard then reports that nothing has changed, having quietly stopped guarding.

Treat the migrated config as a starting point, not an answer. Migration can only recognize a parameter that still exists and still means the same thing. One whose behavior changed while its value still looks like an ordinary number or string is carried across and is silently wrong.

Rebuilding by hand

Often the safer choice, and the only way to be certain you have looked at the new parameters:

mv parameters.config parameters.config.bak            # keep your settings
PoolSeqFlow init                                      # writes a fresh parameters.config
diff parameters.config.bak parameters.config          # see what changed, then re-apply yours

init never overwrites, so move your own file aside first; otherwise it reports the config as already present and leaves it alone.

A project belongs to one release

Completed steps are skipped by looking for output files, not by checking what produced them, so continuing a project under a new release would leave one set of results built by two versions, with nothing on disk to say which is which. The pipeline refuses, before any work happens:

PIPELINE VERSION:      These results were produced by 2.2.0,
PIPELINE VERSION:      and this is 3.0.0.

migrate_config does not clear this. There are two ways forward and deliberately no third, because a project that changed version midway has no answer to the question of which version to cite.

  • Finish the project on the release that started it: PoolSeqFlow-2.2.0 run. That version is still installed and still works, which is the reason releases sit side by side.
  • Start it again under the new one: PoolSeqFlow reset, then run. This deletes the existing results.

A project started fresh under the new release is governed by the ordinary change guard from then on, and the Changelog has what each release changed.