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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="hosted-projects/">
<chapter>
<title>Hosted Projects</title>
<body>
<p>
The following guidelines have been proposed for hosted projects in an attempt to
prevent a repeat of the <c>genkernel</c> disaster.
</p>
</body>
<section>
<title>Documentation Requirement</title>
<body>
<p>
All hosted projects should have decent, up to date user and developer
documentation. This documentation must be available <e>before the first release</e>,
and not left as "something we'll do later (honest)".
</p>
<p>
Our documentation team are happy to help out with GuideXMLification, translation
etc. for the user documentation, but they <e>need</e> various things to do this:
</p>
<ul>
<li>
Basic documentation to start with.
</li>
<li>
Basic information on the project or tool, such as:
<ul>
<li>
The goals
</li>
<li>
The design specification
</li>
<li>
An FAQ
</li>
</ul>
</li>
<li>
To be informed of any updates, in advance if at all possible <d/> this is to
avoid having out of date recommendations in the documentation.
</li>
</ul>
<p>
Developer documentation is generally best left in the hands of the project
maintainers.
</p>
</body>
</section>
<section>
<title>Portability</title>
<body>
<p>
Gentoo runs on a large number of architectures. This is one of our big
advantages over some other distributions. It is therefore important that any
tools are made with portability in mind, <e>even if you originally think that your
tool is only relevant for one arch</e>. It was this kind of assumption that meant
that <c>genkernel</c> had to be completely rewritten when it suddenly became
mandatory.
</p>
<p>
In practice, this means the following:
</p>
<ul>
<li>
Using a portable programming language <d/> no Java or C# for any Gentoo tools.
Bash, C and Python are good, especially since everyone already has those
installed.
</li>
<li>
Not making assumptions about the hardware or architecture. This covers various
things, depending upon the tool <d/> simple examples include:
<ul>
<li>
Not assuming that you are running on a 32bit little endian system.
</li>
<li>
Not assuming that all computers have a VGA text console, or indeed any
kind of graphics capability.
</li>
<li>
Not assuming that all computers use DOS disclabels.
</li>
</ul>
</li>
<li>
Not relying too strongly upon particular implementations of various tools,
except where it has been agreed that we will always use a particular
implementation of said tool (it is safe to use <c>GNU sed</c> extensions, for
example, but <e>not</e> <c>GNU find</c> extensions).
</li>
</ul>
</body>
</section>
<section>
<title>Open / Free</title>
<body>
<p>
All hosted projects should use an appropriate open / free / libre license.
Typically this will be the GPL v2 for software, and some version of the
Creative Commons Attribution-ShareAlike License (CC-BY-SA-*) for documentation.
However, reasonable exceptions can be made <d/> sometimes it
makes more sense to use the LGPL or a *BSD license, and for application-specific
projects going with the application's license may make more sense (the
<c>gentoo-syntax</c> package for <c>vim</c> uses the <c>vim</c> license, for example).
</p>
</body>
</section>
<section>
<title>Accessible</title>
<body>
<p>
Projects should be accessible to users with disabilities. Simple examples of how
to go about this include:
</p>
<ul>
<li>
Not relying solely upon colour to convey information.
</li>
<li>
Providing textual descriptions for any images.
</li>
<li>
Providing clear captions for dialogs, buttons, form fields and so on.
</li>
</ul>
<p>
Good places to look for further hints include:
</p>
<ul>
<li>
<uri link="https://developer.gnome.org/accessibility-devel-guide/stable/gad.html.en">GNOME Accessibility
Project</uri>
</li>
<li>
<uri link="https://www.w3.org/WAI/Resources/#guides">W3C Web Accessibility
Initiative Guidelines</uri>
</li>
</ul>
</body>
</section>
</chapter>
</guide>
|
GitWeb