Re: [RFR] templates://git-stuff/{control,git-stuff.templates}
David Prévot wrote:
> Please find, for review, the debconf templates and packages descriptions
> for the citadel source package.
s/citadel/git-stuff/
[...]
>> Template: git-repack-repositories/enable
>> Type: boolean
>> Default: false
>> -Description: Git repack:
>> - Git repositories tend to grow quite large quickly. From time to time, you
>> - have to repack the repositories to save space and keep optimal
>> +_Description: Do you want to enable the cron job?
No need to make it a question about my preferences:
+_Description: Enable cron job?
>> + Git repositories tend to grow quite large quickly. From time to time,
>> + the repositories should be repacked to save space and keep optimal
>> performances (by not having too many of files in the objects
>> subdirectory).
Better but still fractured English.
Git repositories tend to grow quite large quickly. To save space and
maintain optimal performance they should be repacked from time to
time (reducing the number of files in the objects subdirectory).
>> Template: git-repack-repositories/directories
>> Type: string
>> Default: /srv/git
>> -Description: Git directories:
>> - Please specify the directory or directories (space separated) that is used
>> - as root for the Git repositories on your server. Note that
>> +_Description: Git directories:
>> + Please specify the directory or directories (space separated) used
>> + as root for the Git repositories on the server. Note that
>> git-repack-repositories will work recursively.
>
> I may be mistaken here, but “the directory or directories” doesn't sound
> like a singular subject,
It's arguable, but either answer will trip up some readers, so
avoiding the issue like that is a good solution.
>> Template: git-repack-repositories/cron
>> Type: string
>> Default: @monthly
[...]
>> +_Description: When should the cron job be started?
Sorry, string templates shouldn't end in a question mark. You need
something like:
+_Description: Git cron job scheduling:
And put the question at the start of the long description:
When should the cron job be started?
.
>> + Please refer to crontab(5) for the format definition. By default,
>> + '@monthly' (without quotes), means the cron job gets executed every
>> beginning of the month at midnight.
It not only means that by default, it always means that! Er, except
that no, it doesn't; it only happens at midnight exactly if cron runs
it directly. If it's going through anacron it might happen in the
early morning (and on the second of the month).
Please refer to crontab(5) for the format definition. If it is left
empty the default value "@monthly" (without the quotes) will be used,
executing the cron job every month.
>> Template: git-stuff/bash-profile
>> Type: boolean
>> Default: false
>> +_Description: Should shortcut definitions be activated?
>> + Special shortcut definitions for Bash can be activated in /etc/profile.d.
Magic global shell fragments? Aren't these still deprecated in
policy? Oh well, at least it asks permission.
Meanwhile in the control file:
> Package: git-stuff
> Architecture: all
> Depends: ${misc:Depends}, git
> Recommends: cron, git-buildpackage, mr, pristine-tar
> Description: additional Git utilities
> This is a growing collection of tools for the Git Version Control System.
> .
> Currently the following tools have been documented:
So is this a full list of what's included? No, apparently there are
some undocumented ones too - that's unhelpful.
> .
> * git-amend-all: adds all untracked files and amend all changes to the last
> commit.
Should that be "and amends"?
> * git-checkout-branches: checks out all remote branches.
> * git-cherry-pick-recursive: does a cherry-pick for a commit and each all its
> children.
What does "and each all its children" mean? Missing verb?
> * git-commit-lazy: creates a new commit with all untracked files and changes.
> * git-debian-add: creates a new commit and tag with all untracked files and
> changes as new debian version.
Is that "and tags it", or what?
> * git-debian-changelog: creates a new section in debian/changelog with all
> entries since the last release.
> * git-whoami: tells about author and committer information.
"Tell" requires an object.
As descriptions go, these are barely any more useful than the bare
names would have been, and if it only gave the names it could at least
be a comprehensive list:
Description: additional Git utilities
This is a growing collection of tools for the Git Version Control System,
including:
* git-amend-all
* git-checkout-branches
* git-cherry-pick-recursive
* git-commit-lazy
* git-{debian,progress}-{add,changelog,release,retag,tag}
* git-dpkg-source
* git-hook-notification-{bts,cia,cia.pl,email}
* git-repack-repositories{,-cron}
* git-upstream-{add,retag,tag,tar}
* git-whoami
(It seems to me that there isn't room for full documentation of what
each of these does anyway.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru old/control new/control
--- old/control 2012-06-30 18:03:51.000000000 +0100
+++ new/control 2012-08-28 12:17:53.360411584 +0100
@@ -11,18 +11,15 @@
Depends: ${misc:Depends}, git
Recommends: cron, git-buildpackage, mr, pristine-tar
Description: additional Git utilities
- This is a growing collection of tools for the Git Version Control System.
- .
- Currently the following tools have been documented:
- .
- * git-amend-all: adds all untracked files and amend all changes to the last
- commit.
- * git-checkout-branches: checks out all remote branches.
- * git-cherry-pick-recursive: does a cherry-pick for a commit and each all its
- children.
- * git-commit-lazy: creates a new commit with all untracked files and changes.
- * git-debian-add: creates a new commit and tag with all untracked files and
- changes as new debian version.
- * git-debian-changelog: creates a new section in debian/changelog with all
- entries since the last release.
- * git-whoami: tells about author and committer information.
+ This is a growing collection of tools for the Git Version Control System,
+ including:
+ * git-amend-all
+ * git-checkout-branches
+ * git-cherry-pick-recursive
+ * git-commit-lazy
+ * git-{debian,progress}-{add,changelog,release,retag,tag}
+ * git-dpkg-source
+ * git-hook-notification-{bts,cia,cia.pl,email}
+ * git-repack-repositories{,-cron}
+ * git-upstream-{add,retag,tag,tar}
+ * git-whoami
diff -ru old/git-stuff.templates new/git-stuff.templates
--- old/git-stuff.templates 2012-06-30 18:04:05.000000000 +0100
+++ new/git-stuff.templates 2012-08-28 12:23:57.612733882 +0100
@@ -1,43 +1,39 @@
Template: git-repack-repositories/title
Type: title
-Description: Git Repack Repositories
+_Description: Git repack repositories
Template: git-repack-repositories/enable
Type: boolean
Default: false
-Description: Git repack:
- Git repositories tend to grow quite large quickly. From time to time, you
- have to repack the repositories to save space and keep optimal
- performances (by not having too many of files in the objects
- subdirectory).
- .
- Do you want to enable the cron job?
+_Description: Enable cron job?
+ Git repositories tend to grow quite large quickly. To save space and
+ maintain optimal performance they should be repacked from time to
+ time (reducing the number of files in the objects subdirectory).
Template: git-repack-repositories/directories
Type: string
Default: /srv/git
-Description: Git directories:
- Please specify the directory or directories (space separated) that is used
- as root for the Git repositories on your server. Note that
+_Description: Git directories:
+ Please specify the directory or directories (space separated) used
+ as root for the Git repositories on the server. Note that
git-repack-repositories will work recursively.
Template: git-repack-repositories/cron
Type: string
Default: @monthly
-Description: Git cron:
- What times should the cron job be started? Please refer to crontab(5) for
- the format definition. The default or if left empty will set the interval
- to '@monthly' (without the quotes) which means it gets executed every
- beginning of the month at midnight.
+_Description: Git cron job scheduling:
+ When should the cron job be started?
+ .
+ Please refer to crontab(5) for the format definition. If it is left
+ empty the default value "@monthly" (without the quotes) will be used,
+ executing the cron job every month.
Template: git-stuff/title
Type: title
-Description: additional Git utilities
+_Description: Additional Git utilities
Template: git-stuff/bash-profile
Type: boolean
Default: false
-Description: Shortcuts for Bash (/etc/profile.d)
- Should special shortcut definitions for Bash be activated in /etc/profile.d?
- .
- If unsure, say no.
+_Description: Should shortcut definitions be activated?
+ Special shortcut definitions for Bash can be activated in /etc/profile.d.
Source: git-stuff
Section: misc
Priority: optional
Maintainer: Daniel Baumann <daniel.baumann@progress-technologies.net>
Uploaders: Andrew Lee (李健秋) <ajqlee@debian.org>
Build-Depends: debhelper (>= 9)
Standards-Version: 3.9.3
Package: git-stuff
Architecture: all
Depends: ${misc:Depends}, git
Recommends: cron, git-buildpackage, mr, pristine-tar
Description: additional Git utilities
This is a growing collection of tools for the Git Version Control System,
including:
* git-amend-all
* git-checkout-branches
* git-cherry-pick-recursive
* git-commit-lazy
* git-{debian,progress}-{add,changelog,release,retag,tag}
* git-dpkg-source
* git-hook-notification-{bts,cia,cia.pl,email}
* git-repack-repositories{,-cron}
* git-upstream-{add,retag,tag,tar}
* git-whoami
Template: git-repack-repositories/title
Type: title
_Description: Git repack repositories
Template: git-repack-repositories/enable
Type: boolean
Default: false
_Description: Enable cron job?
Git repositories tend to grow quite large quickly. To save space and
maintain optimal performance they should be repacked from time to
time (reducing the number of files in the objects subdirectory).
Template: git-repack-repositories/directories
Type: string
Default: /srv/git
_Description: Git directories:
Please specify the directory or directories (space separated) used
as root for the Git repositories on the server. Note that
git-repack-repositories will work recursively.
Template: git-repack-repositories/cron
Type: string
Default: @monthly
_Description: Git cron job scheduling:
When should the cron job be started?
.
Please refer to crontab(5) for the format definition. If it is left
empty the default value "@monthly" (without the quotes) will be used,
executing the cron job every month.
Template: git-stuff/title
Type: title
_Description: Additional Git utilities
Template: git-stuff/bash-profile
Type: boolean
Default: false
_Description: Should shortcut definitions be activated?
Special shortcut definitions for Bash can be activated in /etc/profile.d.
Reply to: