Please find, for review, the debconf templates and packages descriptions for the phpwiki source package. This review will last from Friday, August 14, 2009 to Monday, August 24, 2009. 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: --- phpwiki.old/debian/templates 2009-08-14 10:01:34.667595680 +0200 +++ phpwiki/debian/templates 2009-08-14 22:39:11.215141848 +0200 @@ -1,72 +1,61 @@ Template: phpwiki/notes/introduction Type: note -_Description: Welcome to PHPWiki! - This is an automated config generator for PHPWiki. It is not intended to - do everything, in fact, all it will do is generate a basic, standalone - PHPWiki. It is sufficient for simple local installations, but does not - encompass all of PHPWiki's capabilities. If you want to use the more - advanced features of the Wiki, please edit /etc/phpwiki/config.ini - yourself. +_Description: PHPWiki configuration + The most important settings for PHPWiki can be configured automatically. + This configuration process will generate a basic, standalone + PHPWiki. It is sufficient for simple local installations, but does not + encompass all of PHPWiki's capabilities. If you want to use the more + advanced features of the Wiki, you need to modify /etc/phpwiki/config.ini + after the initial configuration is completed. . Please read /usr/share/doc/phpwiki/README.Debian for some important notices - regarding the first time you load pages into your new Wiki. + regarding the first time you load pages into the new wiki. I have a problem with that note: it should not exist and is, IMHO, Debconf abuse. If the package uses debconf, then users should be aware that (as for most software in Debian) not everything is configured by the debconf process. So, in short, that note should imho be dropped. I even wonder whether I haven't already filed a bug report about this..:) Anyway, in case we disagree on this, I reworded the note. First of all, it is highly discouraged to talk about the deboncf/postinst scripts as a process per se. So, I made the wording slightly more neutral. I also drop any reference to "your" wiki asa this is not necessarily "mine". This is something we also try to standardize over debconf templates: not assumign that the person installing packages is "owning" the server. Template: phpwiki/system/documentroot Type: string Default: /phpwiki -_Description: Specify the web-accessible location of PHPWiki: - This is the path under your website that people should use to access - the PHPWiki. By default, this is http://yourserver/phpwiki, but you can - change it to be anything within your server. Enter just the path portion - below. +_Description: Web-accessible location of PHPWiki: + Please specify the location of PHPWiki home page in the web site tree. + . + The recommended (and default) value is http://<server>/phpwiki. Please + only specify the path (example: "/phpwiki"). Synopsis for string templates ar emostly some kind of prompts. So, it is disoucraged to use the verb sentence, for instance by including "specify".... The long description should be made of full sentences, hence the rewording. This is indeed tricky to really explain, though the input expected from the user is fairly obvious. I tried to make things as simple and clear as possible.... Template: phpwiki/system/accessible Type: select -_Choices: localhost only, local network, global +__Choices: localhost only, local network, global Split each choice in a string. That helps translators a lot and avoid mistakes (such as translators not using commas to separate choices). Default: localhost only -_Description: Who should be able to access your PHPWiki?: - A Wiki is normally used to provide unfettered access to information, which - can be freely modified by anyone. Since that is sometimes not what one - wants, it is possible to restrict access to the site on the basis of the - originating IP address. - . - If you select 'localhost only', only people on the localhost (the machine - the Wiki is running on) will be able to connect. 'local network' will - allow people on machines in a local network (which you will need to - specify) to talk to the Wiki. 'global' will allow anyone, anywhere, to - connect to the Wiki. - . - For security, this is set to 'localhost only' by default. Unless you have - a particular need for privacy on your Wiki, you should be able to allow - access globally without compromising site security. +_Description: Hosts authorized to access the wiki pages: + It is possible to restrict access to the wiki to specific hosts + or IP addresses. + . + If you select "localhost only", access will be restricted to users + of the machine + the Wiki is running on. The "local network" choice will + allow people on machines in the same network than the wiki host to + access wiki pages. Finally, when choosing "global", any host can + connect to the wiki. It is first needed to shorten that template. Otherwise it doesn't fit on one screen which always makes things more difficult for users. The synopsis should be a "prompt" and not using interrogative form. This is a strong style recommendation that's mostly respected by all packages.... In my general rewrite, I tried to first make things clear about what is the consequence of this choice: access restriction. Then, I tried to summarize each choice in one sentence. Template: phpwiki/system/localnet Type: string Default: 10.0.0.0/24 -_Description: Specify your local network: - The specification should either be an IP network in CIDR format (x.x.x.x/y) or +_Description: Local network: + Please specify the network that will be considered as "local" and + allowed to access the wiki pages. You must use either an IP network in CIDR format (x.x.x.x/y) or a domain specification (like *.mydomain.com). - . - Anyone who matches the specification given below will be given full and - complete access to the PHPWiki. Again, drop the "specifiy" part in the synopsis. I guess that this question is only asked when "Local network" is chosen previously, for access restriction. So, first remind this briefly. As a consequence, the second paragraph is probably useless, which avoids the tricky part of chaging "anyone" into something else (as what needs to match is an host address, not a personà. Template: phpwiki/notes/configupgrade Type: note _Description: New Configuration Method PHPWiki 1.3.10 has implemented a new configuration system that no longer stores configuration details in the index.php file. The configuration syntax - has also been standardised and all directives are now placed in config.ini. + has also been standardized and all directives are now placed in config.ini. . You still need to run the PHPWiki Upgrade Wizard manually to complete the - final portions of the upgrade. See Step 3 of 'Wiki Upgrades' section in + final portions of the upgrade. See Step 3 of "Wiki Upgrades" section in README.Debian for details. . - An automatic migration of your configuration has been performed which should - correctly migrate your configuration in 95+ percent of cases. However please - check the new configuration at /etc/phpwiki/config.ini carefully as it is - always possible that the automatic process was not perfect. - . - In particular there are known problems migrating configurations that use - external authentication methods (LDAP, IMAP, SQL, etc) for user accounts. - These methods are not used by the standard Debian package and their - configuration is left to the administrator. + An automatic migration of the configuration has been performed, which should + be enough in most cases. The resulting /etc/phpwiki/config.ini file + should however be checked carefully, particularly when + external authentication methods (LDAP, IMAP, SQL, etc) are + used. Use US spelling (something we try to standardize over packages, even though most reviewers are UK users and developers..:-)) Be more vague about the percentage of cases chere things work: I think there is probably no eal data about this..:-) Shorten the template to make it fit in one screen...This is done mostly by dropping sentences that don't add much information. --- phpwiki.old/debian/control 2009-08-14 10:01:34.667595680 +0200 +++ phpwiki/debian/control 2009-08-14 22:41:42.059140471 +0200 @@ -13,11 +13,12 @@ Recommends: mysql-client | postgresql-client | sqlite Suggests: php5-imap, php5-ldap Description: informal collaborative website manager + PHPWiki provides a Wiki server written in PHP. A Wiki is a dynamic website which can be edited by anyone at any time. Over time bad information is naturally filtered out, since the barrier to - modification is very low. Malicious or accidental destruction is obviated + modification is very low. Malicious or accidental destruction is obviated by the keeping of backup versions of all pages. . - Installed as part of this package is introductory material to the Wiki + This package provides an introductory material to the Wiki concept, which can be viewed via the Wiki interface when the package has been installed. This is tricky. 100% of the long description does not really explain what the package is...but more what a wiki is..:-) As of today, I'm not sure it's worth explaining what is a wiki (that might have been different in the past). So, it would be much more preferable to have details about the specific features of PHPWiki. However, I don't really have many clues about what should be enhanced.
Template: phpwiki/notes/introduction Type: note _Description: PHPWiki configuration The most important settings for PHPWiki can be configured automatically. This configuration process will generate a basic, standalone PHPWiki. It is sufficient for simple local installations, but does not encompass all of PHPWiki's capabilities. If you want to use the more advanced features of the Wiki, you need to modify /etc/phpwiki/config.ini after the initial configuration is completed. . Please read /usr/share/doc/phpwiki/README.Debian for some important notices regarding the first time you load pages into the new wiki. Template: phpwiki/system/documentroot Type: string Default: /phpwiki _Description: Web-accessible location of PHPWiki: Please specify the location of PHPWiki home page in the web site tree. . The recommended (and default) value is http://<server>/phpwiki. Please only specify the path (example: "/phpwiki"). Template: phpwiki/system/accessible Type: select __Choices: localhost only, local network, global Default: localhost only _Description: Hosts authorized to access the wiki pages: It is possible to restrict access to the wiki to specific hosts or IP addresses. . If you select "localhost only", access will be restricted to users of the machine the Wiki is running on. The "local network" choice will allow people on machines in the same network than the wiki host to access wiki pages. Finally, when choosing "global", any host can connect to the wiki. Template: phpwiki/system/localnet Type: string Default: 10.0.0.0/24 _Description: Local network: Please specify the network that will be considered as "local" and allowed to access the wiki pages. You must use either an IP network in CIDR format (x.x.x.x/y) or a domain specification (like *.mydomain.com). Template: phpwiki/notes/configupgrade Type: note _Description: New Configuration Method PHPWiki 1.3.10 has implemented a new configuration system that no longer stores configuration details in the index.php file. The configuration syntax has also been standardized and all directives are now placed in config.ini. . You still need to run the PHPWiki Upgrade Wizard manually to complete the final portions of the upgrade. See Step 3 of "Wiki Upgrades" section in README.Debian for details. . An automatic migration of the configuration has been performed, which should be enough in most cases. The resulting /etc/phpwiki/config.ini file should however be checked carefully, particularly when external authentication methods (LDAP, IMAP, SQL, etc) are used.
--- phpwiki.old/debian/templates 2009-08-14 10:01:34.667595680 +0200 +++ phpwiki/debian/templates 2009-08-14 22:39:11.215141848 +0200 @@ -1,72 +1,61 @@ Template: phpwiki/notes/introduction Type: note -_Description: Welcome to PHPWiki! - This is an automated config generator for PHPWiki. It is not intended to - do everything, in fact, all it will do is generate a basic, standalone - PHPWiki. It is sufficient for simple local installations, but does not - encompass all of PHPWiki's capabilities. If you want to use the more - advanced features of the Wiki, please edit /etc/phpwiki/config.ini - yourself. +_Description: PHPWiki configuration + The most important settings for PHPWiki can be configured automatically. + This configuration process will generate a basic, standalone + PHPWiki. It is sufficient for simple local installations, but does not + encompass all of PHPWiki's capabilities. If you want to use the more + advanced features of the Wiki, you need to modify /etc/phpwiki/config.ini + after the initial configuration is completed. . Please read /usr/share/doc/phpwiki/README.Debian for some important notices - regarding the first time you load pages into your new Wiki. + regarding the first time you load pages into the new wiki. Template: phpwiki/system/documentroot Type: string Default: /phpwiki -_Description: Specify the web-accessible location of PHPWiki: - This is the path under your website that people should use to access - the PHPWiki. By default, this is http://yourserver/phpwiki, but you can - change it to be anything within your server. Enter just the path portion - below. +_Description: Web-accessible location of PHPWiki: + Please specify the location of PHPWiki home page in the web site tree. + . + The recommended (and default) value is http://<server>/phpwiki. Please + only specify the path (example: "/phpwiki"). Template: phpwiki/system/accessible Type: select -_Choices: localhost only, local network, global +__Choices: localhost only, local network, global Default: localhost only -_Description: Who should be able to access your PHPWiki?: - A Wiki is normally used to provide unfettered access to information, which - can be freely modified by anyone. Since that is sometimes not what one - wants, it is possible to restrict access to the site on the basis of the - originating IP address. - . - If you select 'localhost only', only people on the localhost (the machine - the Wiki is running on) will be able to connect. 'local network' will - allow people on machines in a local network (which you will need to - specify) to talk to the Wiki. 'global' will allow anyone, anywhere, to - connect to the Wiki. - . - For security, this is set to 'localhost only' by default. Unless you have - a particular need for privacy on your Wiki, you should be able to allow - access globally without compromising site security. +_Description: Hosts authorized to access the wiki pages: + It is possible to restrict access to the wiki to specific hosts + or IP addresses. + . + If you select "localhost only", access will be restricted to users + of the machine + the Wiki is running on. The "local network" choice will + allow people on machines in the same network than the wiki host to + access wiki pages. Finally, when choosing "global", any host can + connect to the wiki. Template: phpwiki/system/localnet Type: string Default: 10.0.0.0/24 -_Description: Specify your local network: - The specification should either be an IP network in CIDR format (x.x.x.x/y) or +_Description: Local network: + Please specify the network that will be considered as "local" and + allowed to access the wiki pages. You must use either an IP network in CIDR format (x.x.x.x/y) or a domain specification (like *.mydomain.com). - . - Anyone who matches the specification given below will be given full and - complete access to the PHPWiki. Template: phpwiki/notes/configupgrade Type: note _Description: New Configuration Method PHPWiki 1.3.10 has implemented a new configuration system that no longer stores configuration details in the index.php file. The configuration syntax - has also been standardised and all directives are now placed in config.ini. + has also been standardized and all directives are now placed in config.ini. . You still need to run the PHPWiki Upgrade Wizard manually to complete the - final portions of the upgrade. See Step 3 of 'Wiki Upgrades' section in + final portions of the upgrade. See Step 3 of "Wiki Upgrades" section in README.Debian for details. . - An automatic migration of your configuration has been performed which should - correctly migrate your configuration in 95+ percent of cases. However please - check the new configuration at /etc/phpwiki/config.ini carefully as it is - always possible that the automatic process was not perfect. - . - In particular there are known problems migrating configurations that use - external authentication methods (LDAP, IMAP, SQL, etc) for user accounts. - These methods are not used by the standard Debian package and their - configuration is left to the administrator. + An automatic migration of the configuration has been performed, which should + be enough in most cases. The resulting /etc/phpwiki/config.ini file + should however be checked carefully, particularly when + external authentication methods (LDAP, IMAP, SQL, etc) are + used. --- phpwiki.old/debian/control 2009-08-14 10:01:34.667595680 +0200 +++ phpwiki/debian/control 2009-08-14 22:41:42.059140471 +0200 @@ -13,11 +13,12 @@ Recommends: mysql-client | postgresql-client | sqlite Suggests: php5-imap, php5-ldap Description: informal collaborative website manager + PHPWiki provides a Wiki server written in PHP. A Wiki is a dynamic website which can be edited by anyone at any time. Over time bad information is naturally filtered out, since the barrier to - modification is very low. Malicious or accidental destruction is obviated + modification is very low. Malicious or accidental destruction is obviated by the keeping of backup versions of all pages. . - Installed as part of this package is introductory material to the Wiki + This package provides an introductory material to the Wiki concept, which can be viewed via the Wiki interface when the package has been installed.
Source: phpwiki
Section: web
Priority: optional
Maintainer: Matt Brown <mattb@debian.org>
Uploaders: David Moreno Garza <damog@debian.org>
Build-Depends: debhelper (>= 7), dpatch, po-debconf
Standards-Version: 3.8.2
Homepage: http://phpwiki.sourceforge.net/
Package: phpwiki
Architecture: all
Depends: ${misc:Depends}, apache2 | httpd, php5 | libapache2-mod-php5, php-db, php5-mysql | php5-pgsql | php5-sqlite, ucf (>= 1.05), dbconfig-common (>= 1.8.21)
Recommends: mysql-client | postgresql-client | sqlite
Suggests: php5-imap, php5-ldap
Description: informal collaborative website manager
PHPWiki provides a Wiki server written in PHP.
A Wiki is a dynamic website which can be edited by anyone at any time.
Over time bad information is naturally filtered out, since the barrier to
modification is very low. Malicious or accidental destruction is obviated
by the keeping of backup versions of all pages.
.
This package provides an introductory material to the Wiki
concept, which can be viewed via the Wiki interface when the package has
been installed.
Attachment:
signature.asc
Description: Digital signature