1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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
67
68
69
70
71
72
73
74
75
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
119
120
121
122
|
gnome-disk-utility development happens at in the GNOME git repository
http://git.gnome.org/cgit/gnome-disk-utility/
Send feedback to devkit-devel@lists.freedesktop.org and/or file bugs
in the GNOME Bugzilla at
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 ===
Short explanation of the commit
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
must start with a capital letter. Don't use a trailing period
either. Don't exceed 72 characters.
- 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.
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
- 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)
- 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
CODING STYLE
============
TODO: write me
|