Project

General

Profile

Task #12373

User Guide and debian/control: revise bung description

Added by Charles Atkinson 6 months ago. Updated 3 months ago.

Status:
Closed
Priority:
Normal
Start date:
21/06/2021
Due date:
% Done:

0%

Close

Description

From #11784#note-36

- d/control, package description.
    - The short package description should explain a bit more a bout bung than
    "backup system".
    - The extended description maybe should be not only a bullet point list,
      more free text elaborating a bit more about bung, why one wants it and
      its key features. (I know this is usually quite hard, maybe take a look at
      other packages how this is usually done)

History

#1 Updated by Charles Atkinson 6 months ago

  • Status changed from New to In Progress
  • Assignee changed from Charles Atkinson to Mahesh Arumugam

Mahesh, can you help? I'm too close to bung and have revised the overview/description several times, most recently last week. It is for readers who are considering using bung and want to know if it is a good solution for them.

The criticism of it was

    - The short package description should explain a bit more a bout bung than
    "backup system".
    - The extended description maybe should be not only a bullet point list,
      more free text elaborating a bit more about bung, why one wants it and
      its key features. (I know this is usually quite hard, maybe take a look at
      other packages how this is usually done)
The current package description (sorry about the formatting) is
Description: backup system
 backup scripts next generation (bung): o Uses standard backup utilities mysqldump, pg_dump, rsync, slapcat and tar to 
  create backups on local and remote file systems.
 o Is arbitrarily extensible via templates with integrated support for git. 
  Templated examples are provided for backing up some Cisco and MikroTik
  devices.
 o Supports hotplug storage devices such as USB disks. o Features LVM snapshots, file system mounting, on-screen notifications and 
  report emails.
 o Features extensive logging designed to facilitate problem investigation. o For rsync backups, retains changed and deleted files thus providing a 
  "rolling full" backup.
 o Is normally started by scheduler (anacron or cron) or by udev (after a 
  hotplug storage device plug in event).
 o Is GPL-2.0+ licensed. o Is written in bash. o Was created in 2013 and is known to be used for backing up hundreds of 
  laptops, PCs, routers and switches.
That was created from the User Guide's

backup scripts next generation (bung):
• Uses standard backup utilities mysqldump, pg_dump, rsync, slapcat and tar to create backups on local and remote file systems.
• Is arbitrarily extensible via templates with integrated support for git. Templated examples are provided for backing up some Cisco and MikroTik devices.
• Supports hotplug storage devices such as USB disks.
• Features LVM snapshots, file system mounting, on-screen notifications and report emails.
• Features extensive logging designed to facilitate problem investigation.
• For rsync backups, retains changed and deleted files thus providing a "rolling full" backup.
• Is normally started by scheduler (anacron or cron) or by udev (after a hotplug storage device plug in event).
• Is GPL-2.0+ licensed.
• Is written in bash.
• Was created in 2013 and is known to be used for backing up hundreds of laptops, PCs, routers and switches.
1.1.1

#2 Updated by Mahesh Arumugam 6 months ago

  • Assignee changed from Mahesh Arumugam to Charles Atkinson

Hey Charles, I am not so good at the documentation part as you. But I have shuffled the sentences according my understanding. So its easy to understand the bung.

* Was created in 2013 and is known to be used for backing up hundreds of laptops, PCs, routers and switches.
* 1.1.1
* Is GPL-2.0+ licensed and written in bash.
* Uses standard backup utilities mysqldump, pg_dump, rsync, slapcat and tar to create backups on local and remote file systems.
* Supports hotplug storage devices such as USB disks.
* Is normally started by scheduler (anacron or cron) or by udev (after a hotplug storage device plug in event).
* Features LVM snapshots, file system mounting, on-screen notifications and report emails.
* Features extensive logging designed to facilitate problem investigation.
* For rsync backups, retains changed and deleted files thus providing a "rolling full" backup.
* Is arbitrarily extensible via templates with integrated support for git. Templated examples are provided for backing up some Cisco and MikroTik devices.

Is the above points written for the " - The short package description should explain a bit more a bout bung than "backup system".?

#3 Updated by Charles Atkinson 6 months ago

  • Assignee changed from Charles Atkinson to Mahesh Arumugam

Thanks for the re-ordering. I believe more is needed. Your feedback on the suggested text below will help

Synopsis

Regards the "synopsis", imagine you are looking for a backup system to run on Debian for yourself, your business or your college. You have searched the Debian packages list for "backup" https://packages.debian.org/search?keywords=backup&searchon=names&suite=stable&section=all and you are browsing the hits, looking at each package's synopsis. Currently bung has "backup system". It should be more helpful

What is allowed? From https://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions

Every Debian package must have a Description control field which contains a synopsis and extended description of the package. Technical information about the format of the Description field is in Description.
.
The description should describe the package (the program) to a user (system administrator) who has never met it before so that they have enough information to decide whether they want to install it. This description should not just be copied verbatim from the program’s documentation.
.
Put important information first, both in the synopsis and extended description. Sometimes only the first part of the synopsis or of the description will be displayed. You can assume that there will usually be a way to see the whole extended description.
.
The description should also give information about the significant dependencies and conflicts between this package and others, so that the user knows why these dependencies and conflicts have been declared.
.
3.4.1. The single line synopsis
.
The single line synopsis should be kept brief—certainly under 80 characters.
.
Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can.

How about

Database, file, router and switch backup to local or remote file system
Database, file, router and switch backup for one or many devices
12345678901234567890123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7         8

Extended description

Imagine you have read bung's synopsis and you are interested to find out more so you display the extended description

From https://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions, as above plus

Do not try to continue the single line synopsis into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary (the single line synopsis) is available.
.
The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).
.
The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with

How about

bung (Backup Next Generation) was created in 2013 and is now known to be in regular use for backing up hundreds of laptops, PCs, servers, routers and switches. It backs up files, MariaDB, OpenLDAP, postgres and -- via an extensible templates system -- some Cisco switches and MikroTik routers. Backups are written to local or remote file systems. The templates system has integrated git support.

The rsync-based files backup creates a "rolling full" backup which is easy to browse and restore from using everyday tools. Changed and deleted files are kept for a configurable number of days. When the source is on an LVM volume, snapshots can be used.

Backup jobs are scheduled or initiated by plugging in hotplug storage such as USB disks. When hotplug storage starts a backup, on-screen notifications (terminal or GUI) tell of the start and end of the backup.

When backing up to a remote file system, commands are run via ssh. For security, bung on the remote server validates commands before they are run.

Developed in a production environment, bung's log messages have key information needed to fix problems.

bung is written in bash and GPL-2.0+ licensed.

#4 Updated by Charles Atkinson 6 months ago

  • Assignee changed from Mahesh Arumugam to Charles Atkinson
Mahesh and I (Charles) discussed
  • Synopsis
    Database, file, router and switch backup to file system for one or many devices 
    12345678901234567890123456789012345678901234567890123456789012345678901234567890
             1         2         3         4         5         6         7         8
    
  • Extended: Nice to mention mounting local backup file systems

#5 Updated by Charles Atkinson 6 months ago

The files to be changed
  • "nextcloud/bung/3.0/Backup scripts next generation 3.0.x User Guide.odt" > Overview and thence, following the release procedure in the Programmer's Guide, the HTML and .pdf versions
  • git:source/usr/share/doc/bung/README
  • git:"source build/bung-<bung_ver>-<pack_ver>/debian/control"

Copied "nextcloud/bung/3.0/Backup scripts next generation 3.0.x User Guide.odt" to "nextcloud/bung/3.0/Archive" as "Backup scripts next generation 3.0.7 User Guide.odt"

Edited "nextcloud/bung/3.0/Backup scripts next generation 3.0.x User Guide.odt" > Overview to

bung (Backup Next Generation) was created in 2013 and is now known to be in regular use for backing up hundreds of laptops, PCs, servers, routers and switches. It backs up files, MariaDB, OpenLDAP, postgres and -- via an extensible templates system with git support -- some Cisco switches and MikroTik routers.

Backups are written to local or remote file systems. Local file systems can be mounted when the backup starts and unmounted when it ends. This minimises the danger of accidentally removing backup files.

The rsync-based files backup creates a "rolling full" backup which is easy to browse and restore from using everyday tools. Changed and deleted files are kept for a configurable number of days. When the source is on an LVM volume, snapshots can be used.

Backup jobs are scheduled or initiated by plugging in hotplug storage such as USB disks. When hotplug storage starts a backup, on-screen notifications (terminal or GUI) tell of the start and end of the backup.

When backing up to a remote file system, commands are run via ssh. For security, bung on the remote server validates the commands before they are run.

Developed in a production environment, bung's log messages are designed to give the information needed to investigate problems.

Backup reports are sent by email.

bung is written in bash and uses the GPL-2.0+ license.

Following the Programmer's Guide
  • Updated the ToC and saved
  • Exported as .pdf
  • Saved as .html
  • Ran the release procedure up to and including "Create the tarball"
  • Updated "git:source build/bung-3.0.8-1/debian/control". Doc https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-description. New content
    Source: bung
    Section: admin
    Priority: optional
    Maintainer: Charles Atkinson <bung@charlesmatkinson.org>
    Build-Depends: debhelper (>=11~)
    Standards-Version: 4.1.4
    Homepage: https://redmine.auroville.org.in/projects/bung
    
    Package: bung
    Architecture: all
    Multi-Arch: foreign
    Depends: at,
             anacron | cron | cron-daemon,
             default-mta | mail-transport-agent,
             lsscsi,
             rsyslog | system-log-daemon,
             ${misc:Depends}
    Recommends: rsync, ssh-client
    Suggests: lsof, yad | xenity
    Description: Database, file, router and switch backup to file system for one or many devices
     bung (Backup Next Generation) was created in 2013 and is now known to be in regular use for backing up hundreds of laptops, PCs, servers, routers and switches. It backs up files, MariaDB, OpenLDAP, postgres and -- via an extensible templates system with git support -- some Cisco switches and MikroTik routers.
     .
     Backups are written to local or remote file systems. Local file systems can be mounted when the backup starts and unmounted when it ends. This minimises the danger of accidentally removing backup files.
     .
     The rsync-based files backup creates a "rolling full" backup which is easy to browse and restore from using everyday tools. Changed and deleted files are kept for a configurable number of days. When the source is on an LVM volume, snapshots can be used.
     .
     Backup jobs are scheduled or initiated by plugging in hotplug storage such as USB disks. When hotplug storage starts a backup, on-screen notifications (terminal or GUI) tell of the start and end of the backup.
     .
     When backing up to a remote file system, commands are run via ssh. For security, bung on the remote server validates the commands before they are run.
     .
     Developed in a production environment, bung's log messages are designed to give the information needed to investigate problems.
     .
     Backup reports are sent by email.
     .
     bung is written in bash and uses the GPL-2.0+ license.
    
    Next: after running lintian, git commit

#6 Updated by Charles Atkinson 3 months ago

  • Status changed from In Progress to Closed

The debian/control change was committed as part of bung-3.0.8-1, commit bung3|ac923547

Also available in: Atom PDF