HACKING 4.52 KB
Newer Older
David Zeuthen's avatar
David Zeuthen committed
1

David Zeuthen's avatar
David Zeuthen committed
2
gnome-disk-utility development happens at in the GNOME git repository
David Zeuthen's avatar
David Zeuthen committed
3

4
 http://git.gnome.org/cgit/gnome-disk-utility/
David Zeuthen's avatar
David Zeuthen committed
5

David Zeuthen's avatar
David Zeuthen committed
6 7
Send feedback to devkit-devel@lists.freedesktop.org and/or file bugs
in the GNOME Bugzilla at
David Zeuthen's avatar
David Zeuthen committed
8

David Zeuthen's avatar
David Zeuthen committed
9 10 11 12 13 14 15 16 17
 http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-disk-utility

COMMIT MESSAGES
===============

 - Commit messages should be of the form (the five lines between the
   lines starting with ===)

=== begin example commit ===
18
Short explanation of the commit
David Zeuthen's avatar
David Zeuthen committed
19 20 21 22 23 24 25 26 27 28 29

Longer explanation explaining exactly what's changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too brief.
=== end example commit ===

 - Always add a brief description of the commit to the _first_ line of
   the commit and terminate by two newlines (it will work without the
   second newline, but that is not nice for the interfaces).

 - First line (the brief description) must only be one sentence and
30 31
   must start with a capital letter. Don't use a trailing period
   either. Don't exceed 72 characters.
David Zeuthen's avatar
David Zeuthen committed
32 33 34 35 36 37 38 39

 - The main description (the body) is normal prose and should use normal
   punctuation and capital letters where appropriate. Normally, for patches
   sent to a mailing list it's copied from there.

 - When committing code on behalf of others use the --author option, e.g.
   git commit -a --author "Joe Coder <joe@coder.org>" and --signoff.

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
TERMINOLOGY
===========

Dealing with and managing storage devices often involves a lot of
techno-babble that only advanced computer-litterate users are familiar
with. The goal of the gnome-disk-utility project is two-fold

 1. To provide plug-ins and programs that enhance the core GNOME desktop
    experience for dealing with and managing storage devices
    - Simple formatting tool
    - GIO/GVfs volume monitor
    - Notification icon displayed when a device is failing

 2. To provide a simple yet powerful disk utility app (Palimpsest)
    suitable for both every-day use (formatting/configuring a USB stick),
    intermediate use (setting up RAID, checking disk health) and also
    capable enough to be useful for things like configuring storage when
    installing the OS.

In a nutshell, the audience is different for 1. and 2. The audience
for the former includes all GNOME users while the audience for the
latter mostly includes system administrators and enthusiasts. As such
different terminology is used.

In Palimpsest the following terminology is used

 - Partition/Partition Table
67 68 69 70 71 72 73 74 75
   - Avoid using terms that are used for other concepts; e.g.
     use "Partition Label" instead of "Label"

 - Filesystem
   - Use the spelling "Filesystem"
     - http://en.wiktionary.org/wiki/filesystem
   - Use the word "Label" when referring to a filesystem label
   - Generally refer to a filesystem by it's label
   - Don't show/reference the UUID (might be shown in a "Details" dialog)
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

 - Disk: Only to be used when referring to the entirety of a
         device; e.g. avoid using it for individual things
         like a partition.

 - Media: Only to be used on disks with removable media and
          preferably only when media is missing. Media in
          optical drives should be referred to as "Disc".

 - Array/Component: Use these terms when dealing with RAID.

 - Device: A generic catch all word that simply is short for "Block
           Device". It should only be used when any of the above
           terms are not suitable.

 - In particular avoid words like "Drive" and "Volume".

 - Power-of-ten ("1 MB" = 1,000,000 bytes), power-of-two ("1 MiB" = 1,048,576
   bytes) and the raw size, e.g. "1,048,576 bytes" should be used to classify
   sizes. If space it tight, use MB, not MiB or the full size.

In the plug-ins/programs a simpler terminology is to be used

 - Volume: Something that contains data

 - Drive: A drive is a container of volumes

 - Media: Only to be used on disks with removable media and
          preferably only when media is missing. Media in
          optical drives should be referred to as "Disc".

 - In general terms like "mounting" and "unmounting" should be
   avoided. The word (and icon) "Eject" should be used in scenarios
   where the user wants to remove the device. Mounting a device
   should happen on insertion and/or when the user tries to access
   the device.

 - Only power-of-ten ("1 MB" = 1,000,000 bytes) should be used to classify
   sizes of devices.

 - Avoid words like: Device, File system, Partition, Partition Table, Array,
                     Component, Label, UUID

David Zeuthen's avatar
David Zeuthen committed
119 120 121 122
CODING STYLE
============

TODO: write me