Beta test feedback - JA (1)

[Dave Offiler]

Email from Josep Aparicio (Beta tester under VS contract) on Tue, 23 Sep 2008 14:56:22

Huw, Dave,

Although I am working on the internals of the code (mostly the
forward operator), I have several things that I can suggest you
now, and which would be easy for you to implement along the
next few days. Essentially, the idea is that the presentation is
confusing for an external user, and risks making it too puzzling
to put it to use. I suggest you below how I would restructure
it to make it look simpler.

-1) Restructure and simplify the deliverable:
     For an external user, the structure of ROPP can be difficult to
     understand while browsing at the page, shortly after having
     gained access. It is thus preferable not to expose the users to
     the internals until later.
     Unless there is some reason that I am missing (copyright or
     similar), I would reduce the deliverable to one single file.
     The confused user will anyway download all files, then look
     inside, and still have some feeling that something may be
     missing. It is simpler to just have 1 file.
-2) Deliverable file:
     Ideally the file's name should be ropp-n.m.tar.gz
     and develop to a subdirectory
     ropp-n.m
     The current "metafile" unpacks within the current directory
     (this is considered inappropriate).
     The modules can then be subdirectories, unpacked and
     uncompressed.
     It is ok to directly unpack all modules, even if the user ends
     up using only a fraction. Something like:
     ropp-n.m/README
     ropp-n.m/COPYRIGHT
     ropp-n.m/INSTALL
     ropp-n.m/grass_ropp_licence.pdf
     ropp-n.m/ropp_tools/
     ...   
     ropp-n.m/ropp_1dvar/
     Again, the user is initially confused, so it is preferable at this
     stage to help the user to feel that everything is simple.
     It is ok to have a README file outside, but it is better to
     just say something like "download the tarball, unpack it, go to
     the main directory and read the INSTALL file".
-3) By the way, the current README is for version 1.2.
     If the above steps are taken, the external README is much
     simpler. An internal README or INSTALL file, prominent
     upon unpacking will suffice.
-4) If you restructure things as above, upgrading may also be
     easier for you, as only the upper tarball and directory have
     the version number.
   
     Josep
    

-- 
Dr. Josep Maria APARICIO
Data Assimilation and Satellite Meteorology Division
Meteorological Service of Canada
2121 Transcanada Hwy
H9P 1J3 Dorval, QC, Canada

Tel: 1-(514)-421-4687
Fax: 1-(514)-421-2106
Josep.Aparicio@ec.gc.ca

[(none)]

Milestone 2.0 deleted

[Dave Offiler]

...and my reply Wed, 24 Sep 2008 09:25:28 :

Josep,

> Huw, Dave,
> 
> Although I am working on the internals of the code (mostly the
> forward operator), I have several things that I can suggest you
> now, and which would be easy for you to implement along the
> next few days. Essentially, the idea is that the presentation is
> confusing for an external user, and risks making it too puzzling
> to put it to use. I suggest you below how I would restructure
> it to make it look simpler.
> 
> -1) Restructure and simplify the deliverable:
>      For an external user, the structure of ROPP can be difficult to
>      understand while browsing at the page, shortly after having
>      gained access. 

We used to have a nice diagram (from the User Guide) showing the
component parts of ROPP, together with a brief description of the
modules on the Overview webpage, but this seems to have got lost when we
ported the download pages to DMI. We recommend users read the open
documentation first (in particular the ROPP Overview guide), but we
could certainly give more information on the high-level ROPP structure
here, before one links to the Downloads page.

Did you read the Release Notes (html) at the top level on the Downloads
page before downloading the ROPP files? If not, did you miss it - so we
need to bring attention to it - or if you read it, it was clearly
inadequate as a structure overview, and we need to better explain it
here. (EUMETSAT consider a RN to be the prime user guide to downloading
and installing any deliverable software - for all SAFs - as it is the
initial user experience, so your feedback on this guide would be most
helpful.)

> It is thus preferable not to expose the users to
>      the internals until later.
>      Unless there is some reason that I am missing (copyright or
>      similar), I would reduce the deliverable to one single file.
>      The confused user will anyway download all files, then look
>      inside, and still have some feeling that something may be
>      missing. It is simpler to just have 1 file.

We do have a single file now - ropp_all.tar - which contains all of the
release files (but modules are still as individual tarballs). This is
documented in the Release Notes (html). But we could present this meta-
file more prominently (first), with the individual tarfiles as
(following) options.

> -2) Deliverable file:
>      Ideally the file's name should be ropp-n.m.tar.gz
>      and develop to a subdirectory
>      ropp-n.m
>      The current "metafile" unpacks within the current directory
>      (this is considered inappropriate).
>      The modules can then be subdirectories, unpacked and
>      uncompressed.
>      It is ok to directly unpack all modules, even if the user ends
>      up using only a fraction. Something like:
>      ropp-n.m/README
>      ropp-n.m/COPYRIGHT
>      ropp-n.m/INSTALL
>      ropp-n.m/grass_ropp_licence.pdf
>      ropp-n.m/ropp_tools/
>      ...   
>      ropp-n.m/ropp_1dvar/
>      Again, the user is initially confused, so it is preferable at this
>      stage to help the user to feel that everything is simple.
>      It is ok to have a README file outside, but it is better to
>      just say something like "download the tarball, unpack it, go to
>      the main directory and read the INSTALL file".

Actually, it would be far from trivial to re-organise the meta-file this
way, as the whole ROPP build system (including the Makefiles which
generate the tarballs) are geared around the separate modules. This is
because not all users want all the modules (e.g. GFZ only want ropp_io -
and ropp_tools - to support BUFR encoding). Others might only want the
ropp_fm to but into a 4-DVar scheme etc... So they have the choice - we
considered they might be more confused having modules they don't want. 

But what we can do relatively easily is to build the meta-tarfile (a)
with the version ID [ropp_all-n.m.tar or just ropp-n.m.tar], and (b)
extract to directly to ropp-n.m. At the moment, the Release Notes advise
manually creating the directory, downloading the meta-tarfile here and
extracting to that directory; this can be automated somewhat.
 
> -3) By the way, the current README is for version 1.2.
>      If the above steps are taken, the external README is much
>      simpler. An internal README or INSTALL file, prominent
>      upon unpacking will suffice.

All of the READMEs are updated for V2.0 now, but this wasn't done in
time for your beta version. But the information in the README is backup;
the main user help on installation is in the Release Notes.

> -4) If you restructure things as above, upgrading may also be
>      easier for you, as only the upper tarball and directory have
>      the version number.

We'll consider this, but we also have to take into account that not all
users want the whole package. Also, individual modules can be changed
more easily, and users only have to download that one if they previously
downloaded it, and not the whole package. Packaging the whole of ROPP
openly in one file (i.e. not as individual tarballs on one archive)
would, I think, take quite some changes to the packaging system (which
Chris Marquardt set up when he was working here), so this could probably
not be done for v2.0; perhaps a future release when we've reviewed how
it might be achieved. We have a policy of continuously simplifying the
internals of the package (reducing 3rd party dependencies, removal of
bundled libraries which are little called etc), so simplifying the
package presentation is an ongoing objective too.

As a compromise for packaging V2.0, we could:
a) rename the meta ropp_all.tar file as ropp-2.0.tar;
b) have this as the first in the list of linked files with the
individual tarballs following as options;
c) arrange for the meta tarfile to automatically extract to a directory
ropp-2.0 (but would still contain the individual module tarballs);
d) document the above in the Release Notes (and overall package README)
with the default being that the meta tarfile is presented as the primary
download file, with individual files as options.

Would this be acceptable for v2.0?


Thanks for the suggestion; we'll put your original email and this reply
in the ROPP Trac system. If you have any others as you go along, please
feed them to us rather than wait until you send in your test report. The
plan was to send us an interim report at week 5 after starting - that
would be the week after next?)

Dave

Note: Action required as above (items a-d on packaging and enhancement of user-interface webpage on GARF) for release version of v2.0, then consideration of suggested package architecture for v3.0.

[Dave Offiler]

On reflection, the structure requested can be achieved by the modifying the distro builder script and some jigging of ropp_bld content. The following modifications have been made:

1) ropp_bld module:

a) the mini-config scripts in ropp_bld have been moved to a configure/ directory, leaving only the build* scripts & READMEs in the root.

b) Makefile changed to generate a ropp_build-n.m.tar.gz archive instead of a .zip archive for consistency with the ropp_src modules. As before, this tarfile will unpack in PWD, but the mini-scripts will be separated into a configure/ sub-dir.

2) makedistro script

a) ropp_* source tarballs (incl. ropp_build) are built normally, and copied to the distro version root (note: now lowercase) $ROPP_DIS/ropp-n.m as for previous versions

b) most user pdf documents are gathered into $ROPP_DIS/ropp-n.m/Documents with html documents going into the distro root. (html also copied to ROPP_DIS)

c) a new 'meta' key added to independently build a meta-tarfile. This option:

• extracts all files from all the ropp_* tarfiles
  
• creates an uncompressed tarfile ROPP_DIS/ropp-n.m.tar from the whole ropp_n.m tree, but excluding the component tarfiles, zipfile collections, reference manuals in Documents (since they're also in the source modules) and certain other files not appropriate for the meta-tarfile
  
• lists the tarfile to MANIFEST and adds this to the tarfile before compressing it to ropp-n.m.tar.gz
  
• delete all the extracted trees, leaving just the tarfiles & Documents again.

The result is that we retain all of the current individual module tarfiles and a meta-tarfile containing the whole distro (full tree, not in sub-tarfiles as for v1.x) which, for the user, will extract to ropp-n.m from PWD to give the following structure:

PWD : ropp-n.m.tar.gz
 |- ropp-n.m  : READMEs, Release Note, Change Log, Licence, 
                MANIFEST, build scripts
    |- configure : package configure mini-config scripts
    |- Documents : ROPP user documentation (not RMs)
    |- ropp_tools-n.m
    |- ropp_io-n.m
    |- ropp_pp-n.m
    |- ropp_fm-n.m
    |- ropp_1dvar-n.m

This should meet all of Josep's suggestions, except that the modules, when extracted, will still have a version number. This is desirable, as (at least in principle) individual modules might not be changed between minor releases - for instance we may still have a ropp_tools-2.0 in a generic ropp-2.1 release, where perhaps only one other module has been updated. Also, changing the extract to a version-less tree would need the module make distro system modifying, (or have makedistro rename the directories and re-make the tarfiles) which would need more tinker-time.

These changes have been committed as changeset [1784] (ropp_bld) and [1785] (makedistro).

TODO:

1) bring documentation (Release Notes, Change Log, READMEs) into line with the modified structure with the meta-tarfile being the assumed default download, and individual tarfiles as an option.

2) when uploading distro files to GARFdev, the structure should have the that release version's Release Notes, Change Log and meta-tarfile at root, with a ropp[-n.m] subdirectory containing the individual module tarfiles and Documents sub-directory, thus mirroring the structure in ROPP_DIS.

3) enhance the ROPP overview page to better describe the structure of ROPP and its components (as the MetO (beta) version used to before it was ported to GARF.

4) review (with Josep) whether to have version-less extracted module trees and the changes required to achieve this, or leave as-is.

Leaving this Ticket open until 1-3 completed and Josep has confirmed that this meets his feedback.

[Huw Lewis]

TODO stages 1) and 2) now completed as part of enhancements for v2.0. e.g. User Guide enhancements [1897].

Overview and download pages drafted in line with suggestions above. Requires cooperation with GRAS SAF web team for implementation before v2.0 release.

Leaving Ticket open until 3 completed

[Huw Lewis]

Updated ROPP download and ROPP overview pages have now been implemented on GARFdev. These will be updated on GARF when the ROPP-2 release takes place.

Ticket closed.