Re: lacie-uboot : Please review the description
On Mon, Nov 19, 2012 at 6:55 PM, Justin B Rye <jbr@edlug.org.uk> wrote:
> Maxime Hadjinlian wrote:
>> I'm in the process of packaging my first debian package, it will be
>> named lacie-uboot (if it's accepted of course) and the description I
>> wanted to add to the package was :
>>
>> Description : lacie u-boot netconsole shell
>
> Well, for a start it needs to be "LaCie U-Boot".
Alright, my bad, I though capital letter were not authorized.
>
>> While filing the ITP (#692894), I was advised by Christian Perrier to
>> make my package description reviewed by you and so the reason for this
>> mail.
>>
>> The purpose of the package is to help the user create an interactive
>> shell with the U-Boot netconsole of any LaCie product and so being
>> able to toy with its boot process.
>
> Doesn't it have a *long* description? It's rather pointless trying to
> review just the synopsis line.
Sorry about that...
> https://github.com/maximeh/plum has
> some material you could use as a basis for a long description:
>
> # plum - Python LaCie das U-Boot Milchkuh
> # ---------------------------------------
> # plum let you connect to the U-Boot netconsole of any newgen LaCie
> # product. It include a mini TFTP server. It is written in Python and
> # designed to be easy to use.
> #
> # Available tools include:
> #
> # * plum : A simple U-Boot netconsole client.
> # * capsup : A simple script using plum to update your system and/or
> # bootloader.
> #
> # plum support the --help option to present the usage summary to the
> # user.
> #
> # The best way to use plum is to previously install it using :
> (and from here on it's useless as a Debian package description).
>
> This has a few minor language issues, but more importantly it takes
> too much for granted. Remember, the people reading this may never
> have heard of the problem that this software was invented to solve!
Yep, I have lost that, I'll need to rethink a few things with that in mind.
>
> What sort of hardware is it talking about? Looking up lacie.com I see
> they sell everything from LCD monitors to USB cables; but I'm going to
> guess you are particularly talking about NAS devices.
Your guess is right but it should be explicit.
>
> What does the description of capsup mean by "update your system"? Why
> would you need to "update your bootloader"? Again, I have no idea
> what problem this software is designed to solve. And why is it called
> capsup?
It is called capsup because LaCie gives its update as "capsule" so
it's a contraction of capsule and update.
I realize while typing it that as you said, it needs a lot of
knowledge from the user to understand what it could do.
>
> The last line of the github description says:
> # Note
> # ----
> # plum comes with opentfptd, it's a TFTP server written in C++ by
> # Achal Dhir
>
> So lacie-uboot incorporates a fork of opentfptd? That sounds like a
> bad idea - wouldn't it make more sense for the package to express a
> Recommends on one of the several TFTP servers already available in
> Debian?
When I created this, it was only for personal usage and a few other
people, and I did not want them to care about their TFTP servers, but
in a Debian system, it doesn't make any sense that a package give two
completely different piece of software.
I'll have to really rethink that part, thanks for pointing it out.
>
> Downloading it I see some more useful information in capsup's usage
> output: "Update a LaCie NAS system with the given file", "MAC address
> of the product to flash". But I also notice it hardcodes paths like
> "/usr/local/etc/opentftp.ini". That looks like a bug!
True, it should not do that.
>
> Here's a rough first draft:
>
> Description: LaCie U-Boot netconsole shell
> LaCie newgen network storage products offer a U-Boot netconsole which
> can be used to configure the device remotely. This package provides an
> easy-to-use interactive netconsole client and associated tools:
> * plum - a simple U-Boot netconsole client written in Python;
> * capsup - a script using plum to flash the bootloader.
> * opentftpd - a TFTP server.
>
Thanks for you draft, I imagine a lot more what is wanted here.
> (I've avoided mentioning the difference in naming between "PLUM" and
> "lacie-uboot", partly because expanding the acronym just raises more
> questions. I can work out why it's a Milchkuh, but why is it "das"?)
The das is here only because the full name of U-Boot is "das U-Boot"
(at least on the front page of the project).
> --
> JBR with qualifications in linguistics, experience as a Debian
> sysadmin, and probably no clue about this particular package
Thank you very much for all your advices and input.
I will rename the tools and write a proper help/manual/description
from your advices, then I'll send another email for reviewing.
I was thinking about lacie-uboot-shell for the package name and :
- plum could be lacie-uboot-shell
- capsup could be lacie-nas-updater
I don't know if it's preferred to use short name and contraction or
longer but clearer names ? I would love some pointers so I could try
and think about new names.
Reply to: