224 <type>requirement</type> |
224 <type>requirement</type> |
225 <text>Upgrade scripts and upgrade documentation must be provided.</text> |
225 <text>Upgrade scripts and upgrade documentation must be provided.</text> |
226 </item> |
226 </item> |
227 </chapter> |
227 </chapter> |
228 |
228 |
|
229 <chapter> |
|
230 <name>Names and identifiers</name> |
|
231 <id>a416d88d-6a8f-4219-85f4-367a89396da9</id> |
|
232 <item> |
|
233 <id>b231cf73-6509-45d4-96c4-79060bf4f7bd</id> |
|
234 <type>recommendation</type> |
|
235 <text>The name of the product and its significant parts should be reasonably unique, so it can be found using full-text search or other standard methods.</text> |
|
236 <note>Significant part is e.g. a protocol, a file format or a CLI command.</note> |
|
237 <note>Global uniqueness is not necessary – such name is not a unique identifier. Collisions cannot be completely avoided, but we should make reasonable efforts to prevent them.</note> |
|
238 <item> |
|
239 <id>ebb8c013-a309-486d-b17b-04a73dd57969</id> |
|
240 <type>recommendation</type> |
|
241 <text>Avoid generic words like common verbs, nouns or adjectives.</text> |
|
242 </item> |
|
243 <item> |
|
244 <id>d923f626-5fd9-4e6d-8f16-af9711ac6e2e</id> |
|
245 <type>recommendation</type> |
|
246 <text>Avoid name collisions with well known and used software.</text> |
|
247 </item> |
|
248 <item> |
|
249 <id>fc3fab39-dfaa-4b90-b51d-11e6b9bf3f2f</id> |
|
250 <type>recommendation</type> |
|
251 <text>Use company or organization name as part of the name if the name itself would be too generic (e.g. „Speed“ is wrong while „SaneCorp Speed“ is right).</text> |
|
252 </item> |
|
253 </item> |
|
254 <item> |
|
255 <id>d71ec208-7657-4914-a00e-d9008c8d7138</id> |
|
256 <type>recommendation</type> |
|
257 <text>For globally unique identifiers, the URI format is recommended.</text> |
|
258 <item> |
|
259 <id>a60448ba-451d-4176-a3ef-fa537698dbc2</id> |
|
260 <type>information</type> |
|
261 <text>Besides the uniqueness, the most important feature of it is immutability and stability.</text> |
|
262 </item> |
|
263 <item> |
|
264 <id>fea4993c-7405-4755-b66a-68cd1f57637b</id> |
|
265 <type>information</type> |
|
266 <text>Identifiers can be derived from an internet domain, an OID or PEN number etc.</text> |
|
267 </item> |
|
268 <item> |
|
269 <id>eb3bb5fa-a99e-4ffa-b27f-2f024e43f3eb</id> |
|
270 <type>recommendation</type> |
|
271 <text>When deriving from internet domains use the tag URI scheme to create timeless identifiers that are not affected by the changes in domain ownership.</text> |
|
272 </item> |
|
273 <item> |
|
274 <id>aa0554cf-0cac-47c2-8075-54a84cb20e74</id> |
|
275 <type>recommendation</type> |
|
276 <text>Use randomly generated identifiers when full decentralization is desired. These identifiers might be just random (e.g. UUID version 4) or derived from a public key (e.g. an SSH key or a Tor address) or a hash of a (secret) data.</text> |
|
277 <note>When public key or a hash of secret data is used, then ownership of the name or namespace can be reliably proved.</note> |
|
278 <note>Random identifiers must be picked from a sufficiently large space where we can assume that collisions are effectively eliminated.</note> |
|
279 </item> |
|
280 </item> |
|
281 </chapter> |
|
282 |
229 <chapter> |
283 <chapter> |
230 <name>Interfaces, formats and protocols</name> |
284 <name>Interfaces, formats and protocols</name> |
231 <id>d34ce339-197c-44ee-9e5c-6d7e212f8c10</id> |
285 <id>d34ce339-197c-44ee-9e5c-6d7e212f8c10</id> |
232 <item> |
286 <item> |
233 <id>be4c72d1-c494-4c44-aeb4-c5847f5a3524</id> |
287 <id>be4c72d1-c494-4c44-aeb4-c5847f5a3524</id> |