[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

[RFR] templates://tipcutils/{templates}



Please find, for review, the debconf templates and packages descriptions for the tipcutils source package.

This review will last from Saturday, January 05, 2008 to Tuesday, January 15, 2008.

Please send reviews as unified diffs (diff -u) against the original
files. Comments about your proposed changes will be appreciated.

Your review should be sent as an answer to this mail.

When appropriate, I will send intermediate requests for review, with
"[RFRn]" (n>=2) as a subject tag.

When we will reach a consensus, I send a "Last Chance For
Comments" mail with "[LCFC]" as a subject tag.

Finally, the reviewed templates will be sent to the package maintainer
as a bug report, and a mail will be sent to this list with "[BTS]" as
a subject tag.

Rationale:
--- ../tipcutils.old/debian/templates	2008-01-01 12:48:57.719332464 +0100
+++ debian/templates	2008-01-05 14:39:13.387252526 +0100
@@ -1,6 +1,7 @@
 Template: tipcutils/configure
 Type: boolean
 Default: true
+# Not rewritten as debconf abuse
 _Description: Configure this TIPC node now?
  In case you don't know what TIPC is you most probably installed
  the package "tipcutils" by accident. As it is a very special network protocol

This template is IMHO debconf abuse. Asking whether one wants to
configure a package while the package was installed is kinda
redundant.

Whether or not the package was installed "by accident" should not be
an argument, otherwise each package would ask such a question.

I therefore did not review the template.


@@ -12,41 +13,45 @@
 Template: tipcutils/address
 Type: string
 Default: 1.1.1
-_Description: The TIPC address of this node:
- The TIPC address is written in Z.C.N (Zone.Cluster.Node) notation.
+_Description: TIPC address of this node:

Writing style consistency. It is not recommended to start a prompt
with an article.


+ Please enter the TIPC address of this node, in Z.C.N (Zone.Cluster.Node)
+ notation.

Common way to write such long descriptions. In the original template,
the first sentence was not a sentence which is discouraged.

  .
- Make sure all nodes in your network have different addresses!
+ You should use different addresses for all nodes in the same network.

More neutral wording (the use of exclam. marks is generally
discouraged as well).

 
 Template: tipcutils/netid
 Type: string
 Default: 4711
-_Description: The Network ID of the TIPC Network this node shall join:
- In case there is just one TIPC Network, keep the default!
+_Description: Network ID of the TIPC network to join:
+ The default setting should be appropriate when there is only
+ one local TIPC network.

Similar changes.

 
 Template: tipcutils/remote_management
 Type: string
 Default: disable
-_Description: Enable/disable TIPC remote management for this node:
- In case you don't know what this is keep it disabled!
+_Description: TIPC remote management:
+ If you want to disable network management for this node, please enter
+ 'disable' here.

That one is tricky. I think you should use a boolean template here but
that goes quite outside the scope of the review as dealing with this
would need maintainer scripts changes. You should consider turning
this into a boolean template.

The use of sentences like "if you don't know what to do...." is
discouraged as well. The user is supposed to have some knowledge.

 
 Template: tipcutils/default_ndd
 Type: string
 Default: 0.0.0
-_Description: The default Neighbour Detection Domain for this TIPC node:
- If there is no setting for a specific bearer this will be used as the Neighbour
- Detection Domain. Setting a NDD for a specific bearer is not yet possible in
- this package version.
+_Description: Default neighbour detection domain for this TIPC node:
+ This setting will define the neighbour detection domain if there is
+ no setting for a specific bearer.
  .
- In case you don't know what this is keep the default!
+ Setting a NDD for a specific bearer is not yet possible in
+ this package version.

Avoid extra capitalization.

Again avoid the "if you don't know what to do" assumption.
 
 Template: tipcutils/interfaces
 Type: string
 Default: eth0
-_Description: The interfaces to use for TIPC:
- A space separated list of the interfaces to be used for TIPC.
+_Description: Interfaces to use for TIPC:
+ Please enter a space-separated list of interfaces to be used for TIPC.

join words by hyphens, in addition to changes similar to above ones.
 
 Template: tipcutils/script_verbosity
 Type: string
 Default: 0
-_Description: The verbosity to use for TIPC scripts:
- Defines the verbosity of the init, if-up and if-down scripts.
+_Description: Verbosity to use for TIPC scripts:
+ This setting defines the verbosity of the TIPC init, if-up and if-down
+ scripts.

Turn the long description into a real sentence.


--- ../tipcutils.old/debian/control	2008-01-01 12:48:57.719332464 +0100
+++ debian/control	2008-01-05 14:39:47.385376987 +0100
@@ -10,5 +10,5 @@
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}, lsb-base, ifupdown, net-tools
 Description: TIPC utilities package
- Configures and manages the TIPC 1.6 (Transparent Inter Process Communication) 
- kernel module.
+ This package provides tools and scripts to configure and manage the TIPC
+ 1.6 (Transparent Inter Process Communication) kernel module.

I would recommend describing what TIPC is. Assuming that "if ppl do
not know what this is, they don't need it" is IMHO not enough. After
all, FLOSS is a matter of learning, also.

-- 


Template: tipcutils/configure
Type: boolean
Default: true
# Not rewritten as debconf abuse
_Description: Configure this TIPC node now?
 In case you don't know what TIPC is you most probably installed
 the package "tipcutils" by accident. As it is a very special network protocol
 you most probably don't need you might want to consider uninstalling it.
 .
 If you don't want to configure TIPC now, you can edit the configuration file 
 /etc/default/tipc later.

Template: tipcutils/address
Type: string
Default: 1.1.1
_Description: TIPC address of this node:
 Please enter the TIPC address of this node, in Z.C.N (Zone.Cluster.Node)
 notation.
 .
 You should use different addresses for all nodes in the same network.

Template: tipcutils/netid
Type: string
Default: 4711
_Description: Network ID of the TIPC network to join:
 The default setting should be appropriate when there is only
 one local TIPC network.

Template: tipcutils/remote_management
Type: string
Default: disable
_Description: TIPC remote management:
 If you want to disable network management for this node, please enter
 'disable' here.

Template: tipcutils/default_ndd
Type: string
Default: 0.0.0
_Description: Default neighbour detection domain for this TIPC node:
 This setting will define the neighbour detection domain if there is
 no setting for a specific bearer.
 .
 Setting a NDD for a specific bearer is not yet possible in
 this package version.

Template: tipcutils/interfaces
Type: string
Default: eth0
_Description: Interfaces to use for TIPC:
 Please enter a space-separated list of interfaces to be used for TIPC.

Template: tipcutils/script_verbosity
Type: string
Default: 0
_Description: Verbosity to use for TIPC scripts:
 This setting defines the verbosity of the TIPC init, if-up and if-down
 scripts.
--- tipcutils.old/debian/templates	2008-01-01 12:48:57.719332464 +0100
+++ tipcutils/debian/templates	2008-01-05 19:12:38.507014972 +0100
@@ -1,6 +1,7 @@
 Template: tipcutils/configure
 Type: boolean
 Default: true
+# Not rewritten as debconf abuse
 _Description: Configure this TIPC node now?
  In case you don't know what TIPC is you most probably installed
  the package "tipcutils" by accident. As it is a very special network protocol
@@ -12,41 +13,45 @@
 Template: tipcutils/address
 Type: string
 Default: 1.1.1
-_Description: The TIPC address of this node:
- The TIPC address is written in Z.C.N (Zone.Cluster.Node) notation.
+_Description: TIPC address of this node:
+ Please enter the TIPC address of this node, in Z.C.N (Zone.Cluster.Node)
+ notation.
  .
- Make sure all nodes in your network have different addresses!
+ You should use different addresses for all nodes in the same network.
 
 Template: tipcutils/netid
 Type: string
 Default: 4711
-_Description: The Network ID of the TIPC Network this node shall join:
- In case there is just one TIPC Network, keep the default!
+_Description: Network ID of the TIPC network to join:
+ The default setting should be appropriate when there is only
+ one local TIPC network.
 
 Template: tipcutils/remote_management
 Type: string
 Default: disable
-_Description: Enable/disable TIPC remote management for this node:
- In case you don't know what this is keep it disabled!
+_Description: TIPC remote management:
+ If you want to disable network management for this node, please enter
+ 'disable' here.
 
 Template: tipcutils/default_ndd
 Type: string
 Default: 0.0.0
-_Description: The default Neighbour Detection Domain for this TIPC node:
- If there is no setting for a specific bearer this will be used as the Neighbour
- Detection Domain. Setting a NDD for a specific bearer is not yet possible in
- this package version.
+_Description: Default neighbour detection domain for this TIPC node:
+ This setting will define the neighbour detection domain if there is
+ no setting for a specific bearer.
  .
- In case you don't know what this is keep the default!
+ Setting a NDD for a specific bearer is not yet possible in
+ this package version.
 
 Template: tipcutils/interfaces
 Type: string
 Default: eth0
-_Description: The interfaces to use for TIPC:
- A space separated list of the interfaces to be used for TIPC.
+_Description: Interfaces to use for TIPC:
+ Please enter a space-separated list of interfaces to be used for TIPC.
 
 Template: tipcutils/script_verbosity
 Type: string
 Default: 0
-_Description: The verbosity to use for TIPC scripts:
- Defines the verbosity of the init, if-up and if-down scripts.
+_Description: Verbosity to use for TIPC scripts:
+ This setting defines the verbosity of the TIPC init, if-up and if-down
+ scripts.
--- tipcutils.old/debian/control	2008-01-01 12:48:57.719332464 +0100
+++ tipcutils/debian/control	2008-01-05 14:39:47.385376987 +0100
@@ -10,5 +10,5 @@
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}, lsb-base, ifupdown, net-tools
 Description: TIPC utilities package
- Configures and manages the TIPC 1.6 (Transparent Inter Process Communication) 
- kernel module.
+ This package provides tools and scripts to configure and manage the TIPC
+ 1.6 (Transparent Inter Process Communication) kernel module.
Source: tipcutils
Section: admin
Priority: optional
Maintainer: Martin Peylo <debian@izac.de>
Build-Depends: debhelper (>= 5), linux-libc-dev (>= 2.6.21-2), po-debconf
Standards-Version: 3.7.3
Homepage: http://tipc.sourceforge.net

Package: tipcutils
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}, lsb-base, ifupdown, net-tools
Description: TIPC utilities package
 This package provides tools and scripts to configure and manage the TIPC
 1.6 (Transparent Inter Process Communication) kernel module.

Attachment: signature.asc
Description: Digital signature


Reply to: