Re: fusiondirectory: review of new debian/templates file
Mike Gabriel wrote:
> I am seeking for an Englisch native speaker who can review the newly created
> debian/templates file in package fusiondirectory. I paste the file'S content
> below and also attach it.
Comments below, diff and amended version (not including my more
radical suggested changes) attached.
> Template: fusiondirectory/upgrade-warning
> Type: note
DevRef 6.5.3.1.6 discourages the use of debconf notes to present
material like this if it can go in a README or a normal dialogue.
Couldn't this one just go in the following template?
But assuming it can't:
> _Description: FusionDirectory Upgrade Warning
u w
Short descriptions don't usually get titlecase.
> FusionDirectory is _not_ a generic LDAP web frontend. FusionDirectory
> expects a highly specific LDAP data information tree. Over the past,
> different versions of FusionDirectory have expected slightly different
> LDAP tree structures.
* Some style tweaks: the "not" is already emphatic enough without the
ASCII markup, the first stop can become a colon (as the second
clause justifies the first), and then there's no need to repeat
"FusionDirectory".
* Isn't a DIT a _directory_ information tree?
* "Over the past" is awkward, but more importantly, irrelevant - the
whole point of warning about this is that it will keep happening.
* This is an odd place to put a paragraph break - it might make sense
to move it one sentence earlier or just not to have one.
So:
FusionDirectory is not a generic LDAP web frontend: it expects a
highly specific LDAP directory information tree.
.
Different versions of FusionDirectory have been known to expect
slightly different LDAP tree structures; [...]
> .
> In fact, some previous version upgrades of FusionDirectory have broken
> FD sites sometimes partially and sometimes even fully. There is no
> all-in-one automatic upgrade tool for your LDAP data. In worst case
> scenarios, adaptations of the LDAP data information tree have to be made
> manually outside of FusionDirectory (e.g. with tools like ldapmodify or
> ldapvi).
Merging in the leftover sentence above, ironing out unidiomatic
phrasings, and trying to shorten it slightly on the way through:
Different versions of FusionDirectory have been known to expect
slightly different LDAP tree structures, causing partial or complete
breakage on upgrade. There is no all-in-one automatic upgrade tool for
your LDAP data; the directory information tree may even need to be
manually adapted outside of FusionDirectory with tools such as
ldapmodify or ldapvi.
> .
> You are about to uprade FusionDirectory to a new major version. Please
> consult the UPGRADE documentation first:
> /usr/share/doc/fusiondirectory/UPGRADE.md.gz
(Typo: s/uprade/upgrade/)
I would suggest moving this paragraph to the top, and then merging the
paragraphs about LDAP DIT problems into one (since after all if they
immediately follow the pointer and read UPGRADE.md.gz, they can skip
that paragraph).
> .
> In the next screen you will be asked to confirm your intention to upgrade
> FusionDirectory. If you decline, the upgrade process will be cancelled.
A reference to debconf implementation details, but I suppose this
one's robust enough that we don't need to worry about it.
Oh, wait - debconf dialogues are standardised to en_US, so: canceled.
> Template: fusiondirectory/upgrade-accepted
This seems a misleading template title.
> Type: boolean
> Default: false
> _Description: Do really want to upgrade FusionDirectory to a new major version?
Malformed question syntax - it doesn't need to be a full sentence
anyway, so make it:
_Description: Really perform FusionDirectory major version upgrade?
> If you agree here, all FusionDirectory related packages will be
> upgraded.
This works, but it's not as if you couldn't fit all the relevant
information into this one template, given that it's mostly just a
pointer! Here's a tentative all-in-one version of the template:
Template: fusiondirectory/upgrade-confirm
Type: boolean
Default: false
_Description: Really perform FusionDirectory major version upgrade?
You are about to upgrade FusionDirectory to a new major version.
Please consult the UPGRADE documentation first:
/usr/share/doc/fusiondirectory/UPGRADE.md.gz
.
FusionDirectory is not a generic LDAP web frontend: it expects a
highly specific LDAP directory information tree. Different versions
of FusionDirectory have been known to expect slightly different
LDAP tree structures, causing partial or complete breakage on
upgrade. There is no all-in-one automatic upgrade tool for your
LDAP data; the directory information tree may even need to be
manually adapted outside of FusionDirectory with tools such as
ldapmodify or ldapvi.
.
If you do not choose to proceed, the upgrade process for
FusionDirectory related packages will be canceled.
(Not in my diff.)
>
> Template: fusiondirectory/upgrade-declined
> Type: error
> _Description: Error: FusionDirectory upgrade has been declined!
Make that just:
_Description: FusionDirectory upgrade canceled
> The upgrade of FusionDirectory has been cancelled on user request. The
> installation process will be aborted.
(Again s/cancelled/canceled/)
This is effectively an extra dialogue just to confirm that debconf has
got the message and things are going as they should - a reassuring
thing to have after the warnings above, but not exactly an *error*...
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Template: fusiondirectory/upgrade-warning
Type: note
_Description: FusionDirectory upgrade warning
You are about to upgrade FusionDirectory to a new major version.
Please consult the UPGRADE documentation first:
/usr/share/doc/fusiondirectory/UPGRADE.md.gz
.
FusionDirectory is not a generic LDAP web frontend: it expects a
highly specific LDAP directory information tree. Different versions
of FusionDirectory have been known to expect slightly different
LDAP tree structures, causing partial or complete breakage on
upgrade. There is no all-in-one automatic upgrade tool for your
LDAP data; the directory information tree may even need to be
manually adapted outside of FusionDirectory with tools such as
ldapmodify or ldapvi.
.
In the next screen you will be asked to confirm your intention to upgrade
FusionDirectory. If you decline, the upgrade process will be canceled.
Template: fusiondirectory/upgrade-accepted
Type: boolean
Default: false
_Description: Really perform FusionDirectory major version upgrade?
If you agree here, all FusionDirectory related packages will be
upgraded.
Template: fusiondirectory/upgrade-declined
Type: error
_Description: FusionDirectory upgrade canceled
The upgrade of FusionDirectory has been canceled on user request. The
installation process will be aborted.
--- template 2018-08-25 23:16:11.667214614 +0100
+++ template.new 2018-08-25 23:45:00.065633126 +0100
@@ -1,35 +1,31 @@
Template: fusiondirectory/upgrade-warning
Type: note
-_Description: FusionDirectory Upgrade Warning
- FusionDirectory is _not_ a generic LDAP web frontend. FusionDirectory
- expects a highly specific LDAP data information tree. Over the past,
- different versions of FusionDirectory have expected slightly different
- LDAP tree structures.
- .
- In fact, some previous version upgrades of FusionDirectory have broken
- FD sites sometimes partially and sometimes even fully. There is no
- all-in-one automatic upgrade tool for your LDAP data. In worst case
- scenarios, adaptations of the LDAP data information tree have to be made
- manually outside of FusionDirectory (e.g. with tools like ldapmodify or
- ldapvi).
- .
- You are about to uprade FusionDirectory to a new major version. Please
- consult the UPGRADE documentation first:
+_Description: FusionDirectory upgrade warning
+ You are about to upgrade FusionDirectory to a new major version.
+ Please consult the UPGRADE documentation first:
/usr/share/doc/fusiondirectory/UPGRADE.md.gz
.
+ FusionDirectory is not a generic LDAP web frontend: it expects a
+ highly specific LDAP directory information tree. Different versions
+ of FusionDirectory have been known to expect slightly different
+ LDAP tree structures, causing partial or complete breakage on
+ upgrade. There is no all-in-one automatic upgrade tool for your
+ LDAP data; the directory information tree may even need to be
+ manually adapted outside of FusionDirectory with tools such as
+ ldapmodify or ldapvi.
+ .
In the next screen you will be asked to confirm your intention to upgrade
- FusionDirectory. If you decline, the upgrade process will be cancelled.
+ FusionDirectory. If you decline, the upgrade process will be canceled.
Template: fusiondirectory/upgrade-accepted
Type: boolean
Default: false
-_Description: Do really want to upgrade FusionDirectory to a new major
-version?
+_Description: Really perform FusionDirectory major version upgrade?
If you agree here, all FusionDirectory related packages will be
upgraded.
Template: fusiondirectory/upgrade-declined
Type: error
-_Description: Error: FusionDirectory upgrade has been declined!
- The upgrade of FusionDirectory has been cancelled on user request. The
+_Description: FusionDirectory upgrade canceled
+ The upgrade of FusionDirectory has been canceled on user request. The
installation process will be aborted.
Reply to: