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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
|
<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Gentoo Policy Guide documentation</title>
<link rel="stylesheet" href="_static/tyrian-sphinx-theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<link rel="icon" href="https://www.gentoo.org/favicon.ico" type="image/x-icon">
<link href="https://assets.gentoo.org/tyrian/bootstrap.min.css" rel="stylesheet" media="screen">
<link href="https://assets.gentoo.org/tyrian/tyrian.min.css" rel="stylesheet" media="screen">
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/tyrian-sphinx-theme.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
</head><body>
<header>
<div class="site-title">
<div class="container">
<div class="row">
<div class="site-title-buttons">
<div class="btn-group btn-group-sm">
<a href="https://get.gentoo.org/" role="button" class="btn get-gentoo"><span class="fa fa-fw fa-download"></span> <strong>Get Gentoo!</strong></a>
<div class="btn-group btn-group-sm">
<a class="btn gentoo-org-sites dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
<span class="fa fa-fw fa-map-o"></span> <span class="hidden-xs">gentoo.org sites</span> <span class="caret"></span>
</a>
<ul class="dropdown-menu dropdown-menu-right">
<li><a href="https://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li>
<li><a href="https://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text-o fa-fw"></span> Wiki</a></li>
<li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li>
<li><a href="https://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li>
<li><a href="https://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li>
<li class="divider"></li>
<li><a href="https://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li>
<li><a href="https://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li>
<li><a href="https://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li>
<li class="divider"></li>
<li><a href="https://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-server fa-fw"></span> Infra Status</a></li>
</ul>
</div>
</div>
</div>
<div class="logo">
<a href="index.html" title="Back to the homepage" class="site-logo"></a>
<span class="site-label"> Policy Guide </span>
</div>
</div>
</div>
</div>
<nav class="tyrian-navbar" role="navigation">
<div class="container">
<div class="row">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="collapse navbar-collapse navbar-main-collapse">
<ul class="nav navbar-nav">
<li class="active">
<a href="index.html">Home</a></li>
<li class=""><a href="https://gitweb.gentoo.org/proj/policy-guide.git/">Source</a></li>
</ul>
<form action="index.html" class="navbar-form navbar-right" method="get" onsubmit="if (this.quicksearch.value == '')
{ alert('Please enter one or more search terms first.');
return false; } return true;">
<div class="input-group" style="margin-top:2px;">
<span class="input-group-addon" style="background:#61597b;color:#FFF;border:0px;" id="basic-addon1"><i class="fa fa-search" aria-hidden="true"></i></span>
<input class="form-control" style="height:30px;border:0px;background:#61597b;color:#FFF;padding-left:0px;box-shadow: none;" type="text" id="highlight" name="highlight" title="Quick Search" placeholder="Quick Search" value="">
</div>
<button class="btn btn-default hidden" type="submit" value="Search" id="find_top">Search</button>
</form>
</div>
</div>
</div>
</nav>
</header>
<div class="container">
<div class="row">
<div class="col-md-9 col-sm-12 col-xs-12" role="main">
<section id="gentoo-policy-guide">
<h1>Gentoo Policy Guide<a class="headerlink" href="#gentoo-policy-guide" title="Permalink to this headline">¶</a></h1>
<p>Gentoo Policy Guide aims to become a definitive clear source of all
Tree Policies that are currently binding to Gentoo developers.
It combines both policies that are global by design (i.e. set by the QA
team or the Council), as well as specific to other Gentoo projects.
The policies are meant to be supplied with rationale and clear
indication of the body setting the policy, and therefore the process
in which the policy can be updated.</p>
<div class="toctree-wrapper compound">
<span id="document-preface"></span><section id="preface">
<h2>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h2>
<section id="introduction">
<h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h3>
<p>Gentoo Policy Guide aims to become a definitive clear source of all
Tree Policies that are currently binding to Gentoo developers.
It combines both policies that are global by design (i.e. set by the QA
team or the Council), as well as specific to other Gentoo projects.
The policies are meant to be supplied with rationale and clear
indication of the body setting the policy, and therefore the process
in which the policy can be updated.</p>
</section>
<section id="authors">
<h3>Authors<a class="headerlink" href="#authors" title="Permalink to this headline">¶</a></h3>
<p>This document is maintained by the Gentoo <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA project</a>.</p>
<p>The current text authors are:</p>
<ul class="simple">
<li><p>Michał Górny (mgorny)</p></li>
</ul>
</section>
<section id="license">
<h3>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3>
<p>This work is licensed under the <a class="reference external" href="https://creativecommons.org/licenses/by-sa/4.0/.">Creative Commons Attribution-ShareAlike
4.0 International License</a>.</p>
</section>
</section>
<span id="document-motivation"></span><section id="motivation-and-history">
<h2>Motivation and history<a class="headerlink" href="#motivation-and-history" title="Permalink to this headline">¶</a></h2>
<section id="historical-state-of-policy-documentation">
<h3>Historical state of policy documentation<a class="headerlink" href="#historical-state-of-policy-documentation" title="Permalink to this headline">¶</a></h3>
<p>At the time, Gentoo was lacking a clear and focused document listing all
development-related policies in a concise and clear way.</p>
<p><a class="reference external" href="https://projects.gentoo.org/pms/latest/pms.html">PMS</a> provided a technical specification for the ebuild files but did
not provide a sufficient explanation on how to use it. Furthermore, PMS
was focused on wider usage of the ebuild files than intended for
the Gentoo repository, and therefore was partially restricted via tree
policies.</p>
<p>Past Council decisions can be found in the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Council/Meeting_logs">Council meeting logs</a>.
However, their form makes it hard to find any particular decision,
not to mention establishing a complete list of policies.</p>
<p>At some point, the QA team started listing <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies">QA policies</a> on its wiki
page. Only eight policies were listed so far. The policies were written
out as a flat list with no particular order which is not going to scale
well.</p>
<p>Finally, there was an attempt to turn <a class="reference external" href="https://devmanual.gentoo.org/">devmanual</a> into a source of
reference policies. It was rejected by its maintainers as explicitly
against the original purpose of this document. Furthermore, a large
amount of stale information combined with ability to edit by every
developer would make it unclear which parts are applicable policies,
and which are obsolete or non-binding tips.</p>
<p>There are also project policies, scattered across wiki pages and other
project documentation, and a lot of de facto policies that were
established less or more formally in the past but were never really
written down.</p>
</section>
<section id="purpose-of-the-policy-guide">
<h3>Purpose of the Policy Guide<a class="headerlink" href="#purpose-of-the-policy-guide" title="Permalink to this headline">¶</a></h3>
<p>The Policy Guide was created in order to address aforementioned
documentation deficiencies. Its primary purpose is to collect all
applicable policies from various sources and combine them into a single
logically organized document.</p>
<p>Along with a wording of each policy, its rationale should be provided
(if available) and an indication of which body set the policy.
The former should make it possible to better understand the policy,
and apply it in spirit rather than requiring very precise wording.
The latter should make it clear who can be queried for additional
information, and how the policy can be updated if need arises.</p>
<p>This Guide is going to replace the QA team policies page. All new QA
policies will be documented directly in it. Other documentation (e.g.
devmanual) should conform to policies stated here.</p>
</section>
</section>
<span id="document-basics"></span><section id="basic-information">
<h2>Basic information<a class="headerlink" href="#basic-information" title="Permalink to this headline">¶</a></h2>
<section id="goals-of-policy-making">
<h3>Goals of policy making<a class="headerlink" href="#goals-of-policy-making" title="Permalink to this headline">¶</a></h3>
<p>The Gentoo policies focus on three aims:</p>
<ol class="arabic simple">
<li><p><em>Portability</em>. By following the policies, it should be possible
to package software so that it works on different system setups.
This includes various supported architectures, basic system
components, service managers, package managers, combinations
of compiler and linker flags, etc.</p></li>
<li><p><em>Maintainability</em>. The policies aim to provide consistent coding
practices that make it easy for a different person to co-maintain
the package or take over after previous maintainer. This also
reduces the risk of mistakes experienced by the end users.</p></li>
<li><p><em>End-user experience</em>. The policies try to help developers
in providing a consistent end-user experience. The same concepts
applied across different packages make it easier for user to achieve
his goals and reduce the likeliness of surprising behavior.</p></li>
</ol>
</section>
<section id="policy-compliance-checking">
<h3>Policy compliance checking<a class="headerlink" href="#policy-compliance-checking" title="Permalink to this headline">¶</a></h3>
<p>Currently, there are two kinds of tools involved in detecting policy
violations:</p>
<ol class="arabic simple">
<li><p>Linting-class tools, including <a class="reference external" href="https://wiki.gentoo.org/wiki/Repoman">repoman</a> and <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a>. Those tools
analyze ebuilds and other files in the package repository for known
policy violations. They are limited to checking for problems that
can be detected without running the phase functions.</p></li>
<li><p>Build- and install-time QA checks, implemented in package managers.
Those trigger while the ebuilds are executing. They are limited
to testing the currently running code path.</p></li>
</ol>
<p>Developers are expected to use both kinds of tools before pushing their
commits. They should both lint the changed ebuilds using <a class="reference external" href="https://wiki.gentoo.org/wiki/Repoman">repoman</a>
or <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a>, and test whether their packages build and install
correctly.</p>
<p>Additionally, Gentoo is running <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a> periodically as <a class="reference external" href="https://qa-reports.gentoo.org/output/gentoo-ci/output.html">Gentoo CI</a>.
All non-trivial violations are reported to the <a class="reference external" href="https://archives.gentoo.org/gentoo-automated-testing/">gentoo-automated-testing</a>
mailing list and to the developers making the relevant commits. This
supplements the direct use of linting tools by developers with reliable
tree-wide scans.</p>
</section>
<section id="policy-enforcement">
<h3>Policy enforcement<a class="headerlink" href="#policy-enforcement" title="Permalink to this headline">¶</a></h3>
<p>The Gentoo <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA team</a> is tasked with enforcement of the tree policies.
Its role is governed by <a class="reference external" href="https://www.gentoo.org/glep/glep-0048.html">GLEP 48</a>. It focuses on documenting
the policies, resolving doubts regarding them and educating
the developers.</p>
<p>The QA team members can also take direct action in resolving minor
quality problems (i.e. when fixing directly involves far less effort
than if the developer was requested to fix it), or when developer
refuses to resolve policy violations.</p>
<p>Finally, in case of repeated unwillingness to follow policies, the QA
team can issue disciplinary measures against the developer in question.</p>
</section>
<section id="policy-making-changes-and-appeals">
<h3>Policy making, changes and appeals<a class="headerlink" href="#policy-making-changes-and-appeals" title="Permalink to this headline">¶</a></h3>
<p>The majority of policies are written down and maintained by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA
team</a>. Other Gentoo projects also create policies that affect their
specific areas of contributions (e.g. <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Systemd">systemd project</a> created
policies related to installing systemd unit files).</p>
<p>Each policy listed in this document indicates the body maintaining it.
In order to change or abolish the policy, that team should be contacted.
If the project in question disagrees with the change, <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA team</a> can be
asked to override the policy. All QA decisions and policies can further
be appealed to the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Council">Council</a>.</p>
</section>
</section>
<span id="document-other-docs"></span><section id="other-policy-documents">
<h2>Other policy documents<a class="headerlink" href="#other-policy-documents" title="Permalink to this headline">¶</a></h2>
<section id="gentoo-specific-documentation">
<h3>Gentoo-specific documentation<a class="headerlink" href="#gentoo-specific-documentation" title="Permalink to this headline">¶</a></h3>
<section id="package-manager-specification">
<h4>Package Manager Specification<a class="headerlink" href="#package-manager-specification" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="https://projects.gentoo.org/pms/latest/pms.html">PMS</a> provides the specification of ebuild format, as well as general
guidelines for implementing package managers. All ebuilds in the Gentoo
repository are required to conform to the PMS. Tree policies may
enforce additional restrictions upon the format discussed in PMS.</p>
<p>PMS is maintained by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:PMS">PMS project</a>. All major changes are done
in subsequent EAPIs that are approved by the Council. The project’s
wiki page discusses how PMS can be changed via <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification/Future_EAPI_process">future EAPI process</a>.</p>
</section>
<section id="gleps">
<h4>GLEPs<a class="headerlink" href="#gleps" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="https://www.gentoo.org/glep/">GLEPs</a> provide the highest level policies applicable to Gentoo. Final
or active GLEPs apply to all developers. Tree policies may impose
additional restrictions on GLEPs but may not override them.</p>
<p>The process for creating and updating GLEPs is documented in <a class="reference external" href="https://www.gentoo.org/glep/glep-0001.html">GLEP 1</a>.
In general, all GLEP updates go through mailing list review and need
to be approved by the Council.</p>
</section>
<section id="developer-manual">
<h4>Developer Manual<a class="headerlink" href="#developer-manual" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="https://devmanual.gentoo.org/">Devmanual</a> is the basic guide for ebuild developers. Besides policies,
it contains many general recommendations and detailed instructions.
Developer Manual does not specify policies itself, and needs to comply
with policies defined in this document.</p>
<p>Technically, devmanual can be changed by any developer. However, it is
recommended that all changes are reviewed by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Devmanual">devmanual project</a>.</p>
</section>
</section>
<section id="external-standards">
<h3>External standards<a class="headerlink" href="#external-standards" title="Permalink to this headline">¶</a></h3>
<section id="posix">
<h4>POSIX<a class="headerlink" href="#posix" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="http://get.posixcertified.ieee.org/">POSIX</a> is the basic standard for operating systems. However, its rules
apply to the software packaged in Gentoo rather than the distribution
itself. Nevertheless, when no more specific policy applies, following
POSIX is recommended.</p>
</section>
<section id="fhs">
<h4>FHS<a class="headerlink" href="#fhs" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="https://refspecs.linuxfoundation.org/fhs.shtml">FHS</a> specifies the suggested filesystem layout for Linux systems.
Gentoo follows FHS only partially. Whenever Gentoo policies and FHS
disagree, Gentoo policies should be followed.</p>
</section>
</section>
</section>
<span id="document-dependencies"></span><section id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
<span class="target" id="index-0"></span><section id="pg0001">
<span id="optional-runtime-dependencies"></span><span id="index-1"></span><h3>Optional runtime dependencies<a class="headerlink" href="#pg0001" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0001</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>Using USE flags to control optional runtime dependencies is not
acceptable except under very specific circumstances, such as a package
being nonfunctional unless at least one of a set of optional runtime
dependencies is installed.</p>
<p>There is no specific preference as to how user should be informed
of optional runtime dependencies. Three possible ways are
<code class="docutils literal notranslate"><span class="pre">optfeature</span></code> eclass, <code class="docutils literal notranslate"><span class="pre">readme.gentoo-r1</span></code> eclass and plain <code class="docutils literal notranslate"><span class="pre">elog</span></code>
messages.</p>
<p><em>Rationale</em>: toggling USE flags in order to enable or disable optional
runtime dependencies causes needless rebuilds of packages in question.
This is especially important for packages that take long time to build.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><a class="reference external" href="https://www.gentoo.org/glep/glep-0062.html">GLEP 62</a> proposes a solution permitting flipping USE flags without
rebuilding package in question. It has been tentatively approved
by the Council but no reference implementation has been written.</p>
</div>
</section>
<section id="pg0002">
<span id="dependencies-with-no-revision"></span><span id="index-2"></span><h3>=-dependencies with no revision<a class="headerlink" href="#pg0002" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0002</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by repoman and pkgcheck</p>
</dd>
</dl>
<p>Whenever a non-wildcard <code class="docutils literal notranslate"><span class="pre">=</span></code> (equals) dependency is used on a package,
the requested revision must be specified explicitly. When the zeroth
revision is requested, <code class="docutils literal notranslate"><span class="pre">-r0</span></code> must be used. When no specific revision
is necessary, the <code class="docutils literal notranslate"><span class="pre">~</span></code> (tilde) operator must be used instead.</p>
<p><em>Example</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD:</span>
<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2.3</span>
<span class="c1"># GOOD:</span>
<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2.3</span><span class="o">-</span><span class="n">r0</span>
<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2.3</span><span class="o">-</span><span class="n">r3</span>
<span class="o">~</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2.3</span>
</pre></div>
</div>
<p><em>Rationale</em>: using <code class="docutils literal notranslate"><span class="pre">=</span></code> operator in place of <code class="docutils literal notranslate"><span class="pre">~</span></code> to mean a specific
version has been a common mistake. This policy uses the fact that
no revision and explicit <code class="docutils literal notranslate"><span class="pre">-r0</span></code> are equivalent. By explicitly
requesting the latter, it warns developers to reconsider whether they
used the correct operator.</p>
</section>
<section id="slot-and-subslot-dependencies">
<span id="index-3"></span><h3>Slot and subslot dependencies<a class="headerlink" href="#slot-and-subslot-dependencies" title="Permalink to this headline">¶</a></h3>
<section id="pg0011">
<span id="on-sub-slotted-packages"></span><h4>on (sub-)slotted packages<a class="headerlink" href="#pg0011" title="Permalink to this headline">¶</a></h4>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0011</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f">https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>by repoman and pkgcheck</p>
</dd>
</dl>
<p>Whenever a package dependency specification matches a range of versions
that span different slots or subslots, the package must explicitly
include slot specification. If the <code class="docutils literal notranslate"><span class="pre">:=</span></code> operator is not applicable
and any slot is acceptable, explicit <code class="docutils literal notranslate"><span class="pre">:*</span></code> operator must be used.
If the <code class="docutils literal notranslate"><span class="pre">:<slot>=</span></code> operator is not applicable and only a specific slot
can be used, <code class="docutils literal notranslate"><span class="pre">:<slot></span></code> value must be explicitly specified.</p>
<p>Package dependency specification without explicit slot specifier can
be used on packages that are not slotted nor subslotted at the moment.</p>
<p><em>Rationale</em>: this policy aims to help detecting missing slot operators
when dependencies start using slots or subslots. It uses the fact that
the explicit <code class="docutils literal notranslate"><span class="pre">:*</span></code> operator is equivalent to no slot specification,
and therefore can be used interchangeably. In this case, we assume
that the latter means ‘dependency not verified yet’, while the former
means ‘verified that any slot is acceptable’.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <a class="reference external" href="https://paludis.exherbo.org/">Paludis</a> package manager applies different logic when no slot
is specified on the dependency. It pulls in the slot corresponding
to the newest package version available.</p>
</div>
</section>
<section id="pg0012">
<span id="special-case-qt-packages"></span><span id="index-4"></span><h4>special case: Qt packages<a class="headerlink" href="#pg0012" title="Permalink to this headline">¶</a></h4>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0012</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Qt project</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies">https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>The Qt packages use subslots in an uncommon way. The public ABI of Qt
libraries is stable within each slot, and the subslot is used to refer
to private ABI. Therefore, the <code class="docutils literal notranslate"><span class="pre">:=</span></code> operator must only be used
if your package uses one of the private API parts, and plain <code class="docutils literal notranslate"><span class="pre">:5</span></code>
or likewise dependency must be used otherwise.</p>
</section>
<section id="proactive-use-of-slot-operators">
<h4>proactive use of slot operators<a class="headerlink" href="#proactive-use-of-slot-operators" title="Permalink to this headline">¶</a></h4>
<p>There is an open debate on whether developers should be proactively
adding <code class="docutils literal notranslate"><span class="pre">:=</span></code> slot operators on packages that do not define subslots
yet.</p>
<p>Proponents of the idea point out that adding slot operators to reverse
dependencies after the package becomes slotted is cumbersome and usually
results in losing the subslot rebuild opportunity at least once. They
argue that in many cases the future use of subslots is reasonably
predictable.</p>
<p>Opponents claim that the future use of subslots is not 100% predictable.
They point out the case of Qt packages as an example.</p>
</section>
</section>
<section id="pg0003">
<span id="revision-bumps-on-runtime-dependency-changes"></span><span id="index-5"></span><h3>Revision bumps on runtime dependency changes<a class="headerlink" href="#pg0003" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0003</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Council</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>It must not be assumed that changes to package’s dependencies will
be implicitly propagated to users who have installed the package
already. Whenever the change needs to be propagated (e.g. to prevent
a missing runtime dependency from being cleaned), the package revision
must be increased.</p>
<p>This does not apply to build-time dependencies.</p>
<p><em>Rationale</em>: developers were historically relying on Portage’s behavior
called <em>dynamic dependencies</em> which caused Portage to implicitly use
dependencies specified in matching ebuilds for installed packages. This
is non-portable and unreliable. Users using different package managers,
disabling the feature or simply missing the timeframe during which
the old ebuild version existed had experienced dependency graph breakage
and other problems due to it.</p>
<p>The policy requires developers to explicitly account for that
possibility. Revision bumps ensure that users who installed the package
from the previous ebuild version rebuild it and get the updated
dependencies as a result.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The dynamic dependency usage problem has a flip side. You can’t rely
on in-place dependency changes <em>not</em> being propagated either. For
example, if you notice that a package linked to libfoo unnecessarily,
and decide to remove the dependency and code responsible for linking
to it in place, Portage may apply the former immediately even
if the package installed by the user still links to libfoo.</p>
</div>
</section>
<section id="use-dependencies">
<span id="index-6"></span><h3>USE dependencies<a class="headerlink" href="#use-dependencies" title="Permalink to this headline">¶</a></h3>
<section id="pg0021">
<span id="on-packages-without-the-flag"></span><h4>on packages without the flag<a class="headerlink" href="#pg0021" title="Permalink to this headline">¶</a></h4>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0021</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA (inferred from PMS)</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck</p>
</dd>
</dl>
<p>Whenever a package uses a 2-style USE-dependency on another package,
all package versions matching the dependency must have the flag
in question. If the dependency matches at least one version missing
the flag, either 4-style USE-dependency (i.e. having <code class="docutils literal notranslate"><span class="pre">(-)</span></code> or <code class="docutils literal notranslate"><span class="pre">(+)</span></code>
indicator) must be used, or the restriction must be refined to match
only versions having the flag.</p>
<p><em>Example</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD: USE=gtk2 is not supported by v2</span>
<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="p">[</span><span class="n">gtk2</span><span class="p">]</span>
<span class="c1"># GOOD: all matching versions have USE=tools</span>
<span class="o"><</span><span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mi">2</span><span class="p">[</span><span class="n">gtk2</span><span class="p">]</span>
<span class="c1"># GOOD: indicate the default</span>
<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="p">[</span><span class="n">gtk2</span><span class="p">(</span><span class="o">-</span><span class="p">)]</span>
<span class="c1"># BAD: USE=tools is no longer needed with v2</span>
<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libbar</span><span class="p">[</span><span class="n">tools</span><span class="p">]</span>
<span class="c1"># GOOD: indicate the default</span>
<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libbar</span><span class="p">[</span><span class="n">tools</span><span class="p">(</span><span class="o">+</span><span class="p">)]</span>
</pre></div>
</div>
<p><em>Rationale</em>: according to the PMS section on <a class="reference external" href="https://projects.gentoo.org/pms/7/pms.html#x1-790008.2.6.4">2-style and 4-style USE
dependencies</a>, it is an error to apply 2-style USE dependency to
a package missing the flag. Furthermore, checking for this makes it
possible to report whenever USE flags on a package are changed without
updating its reverse dependencies.</p>
</section>
</section>
</section>
<span id="document-deprecation"></span><section id="deprecations">
<h2>Deprecations<a class="headerlink" href="#deprecations" title="Permalink to this headline">¶</a></h2>
<section id="pg1001">
<span id="deprecated-eapis"></span><span id="index-0"></span><h3>Deprecated EAPIs<a class="headerlink" href="#pg1001" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>1001</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Council</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/layout.conf">https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/layout.conf</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>by pkgcheck and repoman</p>
</dd>
</dl>
<p>Deprecated EAPIs should not be used in new ebuilds. Existing packages
should be migrated to newer EAPIs on version bumps, or proactively when
no version bumps are expected.</p>
<p>The current list of deprecated EAPIs is stored as <code class="docutils literal notranslate"><span class="pre">eapis-deprecated</span></code>
in <code class="docutils literal notranslate"><span class="pre">metadata/layout.conf</span></code>.</p>
</section>
<section id="pg1003">
<span id="deprecated-eclasses"></span><span id="index-1"></span><h3>Deprecated eclasses<a class="headerlink" href="#pg1003" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>1003</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>individual eclass maintainers</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck and repoman</p>
</dd>
</dl>
<p>Deprecated eclasses should not be used in new ebuilds. Existing
packages should be updated not to use these eclasses on version bumps,
or proactively when no version bumps are expected.</p>
<p>Deprecations are indicated using the <code class="docutils literal notranslate"><span class="pre">@DEPRECATED</span></code> eclassdoc tag
inside the eclass files.</p>
</section>
</section>
<span id="document-ebuild-format"></span><section id="ebuild-file-format">
<h2>Ebuild file format<a class="headerlink" href="#ebuild-file-format" title="Permalink to this headline">¶</a></h2>
<section id="pg0101">
<span id="coding-style"></span><span id="index-0"></span><h3>Coding style<a class="headerlink" href="#pg0101" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0101</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>partially via repoman and pkgcheck</p>
</dd>
</dl>
<p>While Gentoo leaves most of the coding style choices to developers,
there are a few rules which we try to enforce. Those are:</p>
<ul class="simple">
<li><p>Always indent using a single tab for indentation level. Do not
attempt to align, as it will not work with different tab widths.</p></li>
<li><p>Whenever using named variables, use bracketed variable form, i.e.
<code class="docutils literal notranslate"><span class="pre">${foo}</span></code> rather than <code class="docutils literal notranslate"><span class="pre">$foo</span></code>.</p></li>
<li><p>Use bash conditions <code class="docutils literal notranslate"><span class="pre">[[</span> <span class="pre">...</span> <span class="pre">]]</span></code> rather than POSIX-ish <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">...</span> <span class="pre">]</span></code>
or <code class="docutils literal notranslate"><span class="pre">test</span></code> builtin.</p></li>
</ul>
<p><em>Rationale</em>: the recommended constructs are less error-prone.
Consistency avoids unnecessary changes when other developers edit
the ebuild.</p>
</section>
<section id="pg0102">
<span id="code-must-be-contained-within-ebuild-and-eclasses"></span><span id="index-1"></span><h3>Code must be contained within ebuild and eclasses<a class="headerlink" href="#pg0102" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0102</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://bugs.gentoo.org/612630">https://bugs.gentoo.org/612630</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>The ebuild code must be fully contained within .ebuild and .eclass
files. It is forbidden to load additional ebuild code from other files
via <code class="docutils literal notranslate"><span class="pre">source</span></code>, <code class="docutils literal notranslate"><span class="pre">eval</span></code> or any other possible method.</p>
<p>This affects historical use of ‘eblits’ to include phase functions from
external files. The eblits used by the few affected packages were
converted into eclasses.</p>
<p><em>Rationale</em>: moving ebuild code to non-standard locations is against
the principle of least surprise. It makes the maintenance harder,
confuses other developers and tools that do not explicitly account for
that possibility, including linting tools.</p>
</section>
<section id="pg0103">
<span id="homepage-must-not-contain-variables"></span><span id="index-2"></span><h3>HOMEPAGE must not contain variables<a class="headerlink" href="#pg0103" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0103</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck, highlighted as error by gentoo-syntax</p>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">HOMEPAGE</span></code> variable in ebuild must specify all the URIs verbatim,
without referring to any variables. Variable references are allowed
when setting generic values in eclasses.</p>
<p><em>Rationale</em>: since homepage URIs do not contain dynamic parts (such
as package versions), there is little advantage to using variables
there. On the other hand, variables render the URIs unusable without
preprocessing, breaking URI support in terminals and editors, as well
as reducing the usefulness of plain tools such as grep.</p>
</section>
<section id="pg0104">
<span id="src-uri-must-not-refer-to-homepage"></span><span id="index-3"></span><h3>SRC_URI must not refer to HOMEPAGE<a class="headerlink" href="#pg0104" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0104</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck</p>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code> variable in ebuild must not refer to <code class="docutils literal notranslate"><span class="pre">${HOMEPAGE}</span></code>.
If both overlap, the common part must be repeated verbatim.</p>
<p><em>Rationale</em>: <code class="docutils literal notranslate"><span class="pre">HOMEPAGE</span></code> permits multiple entries by design,
and developers are generally encouraged to add more helpful entries
(e.g. project pages on PyPI, GitHub…). Making individual URIs
incidentally depend on multi-valued variable having a single value
goes against the principle of least surprise. Furthermore, it makes
it hard to copy-paste part of the URI e.g. to investigate the directory
index.</p>
</section>
<section id="pg0105">
<span id="keywords-must-be-defined-on-a-single-line"></span><span id="index-4"></span><h3>KEYWORDS must be defined on a single line<a class="headerlink" href="#pg0105" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0105</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">KEYWORDS</span></code> variable must be defined at most once in an ebuild,
on a single line, with literal content (no variable references, line
wrapping, appending, etc.).</p>
<p><em>Rationale</em>: it is common for arch teams to use the <code class="docutils literal notranslate"><span class="pre">ekeyword</span></code> tool
when working with large number of ebuilds. The tool has only limited
ability to process and modify ebuilds, and therefore developers must
make sure that it works correctly on their ebuilds.</p>
</section>
<section id="pg0106">
<span id="license-must-not-contain-variables"></span><span id="index-5"></span><h3>LICENSE must not contain variables<a class="headerlink" href="#pg0106" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0106</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> variable in an ebuild must specify all the license names
verbatim, without referring to any variables. The only exception is
(implicit or explicit) use of <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> itself, i.e. appending is
allowed.</p>
<p><em>Rationale</em>: since license names do not contain dynamic parts (such as
package versions), using variables there has little advantage. On the
other hand, variables reduce the usefulness of plain tools such as grep.</p>
</section>
</section>
<span id="document-filesystem"></span><section id="file-system-layout">
<h2>File system layout<a class="headerlink" href="#file-system-layout" title="Permalink to this headline">¶</a></h2>
<section id="pg0201">
<span id="installation-paths"></span><span id="index-0"></span><h3>Installation paths<a class="headerlink" href="#pg0201" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0201</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths">https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>via install-qa-check.d</p>
</dd>
</dl>
<p>Gentoo packages may only install into one of the following top-level
directories:</p>
<table class="hlist"><tr><td><ul class="simple">
<li><p>/bin</p></li>
<li><p>/boot</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/dev</p></li>
<li><p>/etc</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/lib*</p></li>
<li><p>/opt</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/sbin</p></li>
<li><p>/srv</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/usr</p></li>
<li><p>/var</p></li>
</ul>
</td></tr></table>
<p>Furthermore, only the following subdirectories of /usr are permitted:</p>
<table class="hlist"><tr><td><ul class="simple">
<li><p>/usr/bin</p></li>
<li><p>/usr/include</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/usr/lib*</p></li>
<li><p>/usr/libexec</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/usr/sbin</p></li>
<li><p>/usr/share</p></li>
</ul>
</td><td><ul class="simple">
<li><p>/usr/src</p></li>
<li><p>/usr/<triplet></p></li>
</ul>
</td></tr></table>
<p>Furthermore, within /usr/share/doc hierarchy only a subdirectory named
after full package name and version with revision (PF) is permitted.</p>
<p>In the aforementioned lists, ‘lib*’ indicates lib and its appropriate
suffixed variants for the architecture in question. ‘<triplet>’
indicates either CHOST or CTARGET value, as used by toolchain packages.</p>
<p>Additional exceptions can be granted by the QA team. Currently those
exceptions are:</p>
<ul class="simple">
<li><p>/gnu for the guix package manager</p></li>
<li><p>/nix for the nix package manager</p></li>
</ul>
</section>
<section id="pg0202">
<span id="support-for-separate-usr"></span><span id="index-1"></span><h3>Support for separate /usr<a class="headerlink" href="#pg0202" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0202</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt</a>
<a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>Developers are not required to support using separate /usr filesystem
without an initramfs.</p>
<p><em>Rationale</em>: upstream software (as of 2013) is already making support
for early boot without /usr mounted difficult, and whenever it is still
works, it is either subtly broken or relying on hacks (udev). In setups
using initramfs, some of the boot and repair functionality can be moved
from rootfs to initramfs.</p>
</section>
<section id="pg0203">
<span id="strict-multilib-layout"></span><span id="index-2"></span><h3>Strict multilib layout<a class="headerlink" href="#pg0203" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0203</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>via install-qa-check.d, fatal</p>
</dd>
</dl>
<p>Libraries must be installed into an appropriate /lib* or /usr/lib*
directory corresponding to their ABI. For example, 64-bit libraries
on amd64 must be installed into lib64 and not lib.</p>
<p>Libraries installed as a part of larger software package can be
installed along with it into a subdirectory of lib.</p>
<p><em>Rationale</em>: historically, Gentoo has been symlinking /lib to /lib64
in order to maintain compatibility with old packages hardcoding /lib
path. With modern Gentoo profiles, this is no longer the case
and packages must install libraries into appropriate directory for them
to be correctly found by the dynamic loader.</p>
</section>
<section id="pg0204">
<span id="static-libraries-and-libtool-files"></span><span id="index-3"></span><h3>Static libraries and libtool files<a class="headerlink" href="#pg0204" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0204</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>via install-qa-check.d, fatal</p>
</dd>
</dl>
<p>Static libraries and libtool files (.la) must be installed into /usr
hierarchy and never to root filesystem (/lib*). If an additional shared
version of the library is installed to /lib*, a .so linker script must
be installed into /usr/lib* in order to ensure correct linking.</p>
<p><em>Rationale</em>: historically, the purpose of root filesystem was to hold
files strictly needed at boot. For this reason, many old Gentoo
installations may still use small / partition. Static libraries are
used only during package builds, and installing them to rootfs would
be a waste of space.</p>
</section>
<section id="pg0205">
<span id="game-install-locations-and-ownership"></span><span id="index-4"></span><h3>Game install locations and ownership<a class="headerlink" href="#pg0205" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0205</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Council, clarified by QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt</a>
<a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>via install-qa-check.d</p>
</dd>
</dl>
<p>The historical game install locations (/usr/games and /etc/games) must
not be used anymore. Instead, games should follow normal guidelines
for install locations. As an exception, /usr/share/games can be used
if this location is used upstream, and /var/games can be used for shared
game files (e.g. high scores, game state files).</p>
<p>The historical games group must no longer be used. Games must work
for users that are not in this group. The aforementioned install
locations must therefore be owned by root and be world-readable.</p>
<p>If games need privileged access to shared files, the group gamestat
can be used for this purpose. The game executables should be owned
by that group and made setgid. The shared files must be installed
into /var/games hierarchy, and writable to gamestat group.</p>
<p><em>Rationale</em>: there is no technical reason to isolate games from other
applications on the system, or to restrict access to them. The boundary
between game and non-game packages is very blurry on modern systems,
especially due to web browsers.</p>
<p>The historical use of games group on Gentoo to control access is
inconsistent with the use in other distributions where it was used to
share data files. Since the latter implied users must not be added
to the games group, a new group (gamestat) needed to be created to
fulfill that purpose.</p>
</section>
<section id="pg0206">
<span id="absolute-symbolic-link-targets"></span><span id="index-5"></span><h3>Absolute symbolic link targets<a class="headerlink" href="#pg0206" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0206</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by repoman and pkgcheck (when ebuild-generated)</p>
</dd>
</dl>
<p>Packages must not install symbolic links with absolute targets.
Instead, relative paths must be used. An exception is granted
for symlinks to specially mounted filesystems (such as /proc, /run)
when symlinks are supposed to always reference the running host system.</p>
<p><em>Example</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD:</span>
<span class="n">dosym</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">frobnicate</span><span class="o">/</span><span class="n">frobnicate</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">frobnicate</span>
<span class="c1"># GOOD:</span>
<span class="n">dosym</span> <span class="o">../</span><span class="n">lib</span><span class="o">/</span><span class="n">frobnicate</span><span class="o">/</span><span class="n">frobnicate</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">frobnicate</span>
<span class="c1"># ACCEPTABLE EXCEPTION:</span>
<span class="n">dosym</span> <span class="o">/</span><span class="n">proc</span><span class="o">/</span><span class="bp">self</span><span class="o">/</span><span class="n">mounts</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">mtab</span>
</pre></div>
</div>
<p><em>Rationale</em>: absolute symlinks work correctly only when the root
filesystem is mounted at /. They point at the wrong location whenever
it is mounted in another location, e.g. for the purposes of recovery.</p>
</section>
</section>
<span id="document-installed-files"></span><section id="installed-files">
<h2>Installed files<a class="headerlink" href="#installed-files" title="Permalink to this headline">¶</a></h2>
<section id="pg0301">
<span id="installation-of-small-files"></span><span id="index-0"></span><h3>Installation of small files<a class="headerlink" href="#pg0301" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0301</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>Ebuilds must not introduce USE flags to control installing files that
are small in size, require no additional dependencies and not cause any
negative consequences to the program behavior by being installed. Such
files must be installed unconditionally. Examples include shell
completion files, systemd service units, localization files.</p>
<p>Users wishing to strip unnecessary files of this category should use
INSTALL_MASK to do so.</p>
<p><em>Rationale</em>: the goal of this policy is to avoid unnecessary rebuilds
of packages when the cost of installing additional files is much smaller
than the cost of rebuild. It has been specifically brought in context
of bash completions in LibreOffice – a user who did not notice that he
did not enable the flag should not be required to spend hours rebuilding
such a huge package in order to install one tiny file.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>While technically e.g. <code class="docutils literal notranslate"><span class="pre">app-shells/bash-completion</span></code> could be
considered a dependency of installed bash completions, it is not
applicable here since this package needs to be installed by the user
if he wishes to use completions in the first place, and if it is not
installed, completion files are not used at all.</p>
</div>
</section>
<section id="pg0302">
<span id="installation-of-static-libraries"></span><span id="index-1"></span><h3>Installation of static libraries<a class="headerlink" href="#pg0302" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0302</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>Packages must not install static libraries unless they are explicitly
required, either by themselves or their reverse dependencies. If both
shared and static libraries are supported, shared libraries must be
installed by default and <code class="docutils literal notranslate"><span class="pre">USE=static-libs</span></code> may be added for static
libraries if they are necessary.</p>
<p><em>Rationale</em>: static linking is strongly discouraged as it makes security
support for packages practically impossible. It may be used whenever
really necessary (e.g. for recovery tools) but otherwise proliferating
it is considered harmful. There is no point in installing static
libraries if they are never going to be used.</p>
</section>
<section id="pg0303">
<span id="installation-of-libtool-la-files"></span><span id="index-2"></span><h3>Installation of libtool (.la) files<a class="headerlink" href="#pg0303" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0303</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>Packages must not install libtool .la files unless they are explicitly
required. Generally, they might be required if:</p>
<ol class="loweralpha simple">
<li><p>the package is using a plugin loader that requires .la files in order
to locate plugins and does not have .so fallback (very uncommon),</p></li>
<li><p>the package is installing static libraries that have additional
dependencies and no pkg-config files or other tools that provide
the list of dependencies to build systems.</p></li>
</ol>
<p>It is recommended to use the following one-liner to remove .la files:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">find</span> <span class="s2">"$</span><span class="si">{ED}</span><span class="s2">"</span> <span class="o">-</span><span class="n">name</span> <span class="s1">'*.la'</span> <span class="o">-</span><span class="n">delete</span> <span class="o">||</span> <span class="n">die</span>
</pre></div>
</div>
<p><em>Rationale</em>: libtool files were historically introduced as an attempt
to supplement static library archives with dependent library list.
However, they were only supported by libtool-based (autotools) projects
and caused many issues, in particular due to hardcoding full paths.
Today they are practically replaced by more portable pkg-config files,
and while libtool keeps generating them, they are considered
unnecessary and potentially harmful.</p>
</section>
<section id="pg0304">
<span id="virtuals"></span><span id="index-3"></span><h3>Virtuals<a class="headerlink" href="#pg0304" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0304</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>Packages in the <code class="docutils literal notranslate"><span class="pre">virtual</span></code> category must not install any files.</p>
<p><em>Rationale</em>: The <code class="docutils literal notranslate"><span class="pre">virtual</span></code> category is reserved for packages with
an empty installation image. Package managers rely on this for some
optimizations. Also QA tools make certain assumptions about virtuals,
e.g., that they must not assign the <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> variable (which would
be impossible if they installed any files).</p>
</section>
</section>
<span id="document-keywords"></span><section id="keywording-and-stabilization">
<h2>Keywording and stabilization<a class="headerlink" href="#keywording-and-stabilization" title="Permalink to this headline">¶</a></h2>
<section id="pg0401">
<span id="rekeywording-on-dropped-keywords"></span><span id="index-0"></span><h3>Rekeywording on dropped keywords<a class="headerlink" href="#pg0401" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0401</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck and repoman</p>
</dd>
</dl>
<p>The developer removing keywords from a package (e.g. due to new
dependencies) must file a rekeywording bug asking for the package being
retested. This rule can be exempted if the package is known not to work
(anymore) on the arch in question.</p>
<p><em>Rationale</em>: rekeywording on minor architectures often takes a long
time. If a developer neglects to request it immediately, it negatively
affects other developers who in the future either want to stabilize
a new version or to remove an old version.</p>
</section>
<section id="pg0402">
<span id="stabilizing-new-versions"></span><span id="index-1"></span><h3>Stabilizing new versions<a class="headerlink" href="#pg0402" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0402</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck</p>
</dd>
</dl>
<p>Whenever requesting a stabilization of a new version of the package,
the developer must CC <em>all</em> arches that had at least one previous stable
version of the package in question, and that still have ~arch keywords
in the stabilized version. This applies to experimental architectures
as well.</p>
<p>The stabilization request can be closed and old stable version removed
once all non-experimental architectures have processed the stabilization
request. However, the remaining arch teams should be kept CC-ed in case
they wanted to process the bug.</p>
<p><em>Rationale</em>: there were some cases of developers requesting
stabilization only of a subset of architectures they were personally
interested in. This meant some other developer had to independently
request stabilization on remaining architectures which only meant
a duplication of effort and unnecessary confusion over which version
is stable and whether arch teams are slacking or stabilization was not
requested on remaining architectures in the first place.</p>
</section>
<section id="pg0403">
<span id="removing-stable-keywords"></span><span id="index-2"></span><h3>Removing stable keywords<a class="headerlink" href="#pg0403" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0403</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>n/a</p>
</dd>
</dl>
<p>Stable keywords (or the last stable version) can be removed from
a package if the relevant arch team does not respond within 90 days.
If the removal causes a breakage of dependency graph, the developer
must work with maintainers of the depending packages before proceeding
with it.</p>
<p>The policy for removing a package must be followed here, with exception
of last rite mails.</p>
</section>
</section>
<span id="document-languages"></span><section id="language-specific-policies">
<h2>Language-specific policies<a class="headerlink" href="#language-specific-policies" title="Permalink to this headline">¶</a></h2>
<section id="python">
<span id="index-0"></span><h3>Python<a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h3>
<span class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><section id="pg0501">
<span id="eclass-usage"></span><span id="index-4"></span><h4>Eclass usage<a class="headerlink" href="#pg0501" title="Permalink to this headline">¶</a></h4>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0501</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Python project</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Python/Eclasses">https://wiki.gentoo.org/wiki/Project:Python/Eclasses</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>by pkgcheck</p>
</dd>
</dl>
<p>All packages using Python (either through installing Python modules
or scripts, linking to libpython, calling Python at runtime or build
time) must do it through one of the python-r1 eclasses. Packages must
not directly depend on Python, directly use PYTHON_SINGLE_TARGET
or PYTHON_TARGETS. The variables and functions provided by the eclasses
must be used instead.</p>
<p>All ebuilds must explicitly define supported Python implementations
in PYTHON_COMPAT. Dependencies between Python packages must use
PYTHON_USEDEP, PYTHON_SINGLE_USEDEP or python_gen_cond_dep in order
to ensure implementation match.</p>
<p><em>Rationale</em>: the eclass code guarantees consistent and reliable handling
of slotted Python. It ensures that the whole dependency graph uses
matching implementation and that programs will not accidentally break
if user changes his Python preferences. The helper functions
and variables also make it possible to gracefully retire old
implementations with minimal changes to existing ebuilds.</p>
</section>
<section id="pg0502">
<span id="python-2-deprecation"></span><span id="index-5"></span><h4>Python 2 deprecation<a class="headerlink" href="#pg0502" title="Permalink to this headline">¶</a></h4>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0502</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Python project</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life">https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>Python 2 is being phased out of Gentoo packages. Python 2 support
must not be introduced in new packages, unless explicitly required
to maintain compatibility with existing packages. Packages that do not
support Python 3 should be removed sooner or later, depending
on Python 3 porting chances.</p>
<p>In packages that support both Python 2 and Python 3, the Python 2
support should be gracefully retired, as soon as their reverse
dependencies are ready or removed.</p>
<p><em>Rationale</em>: Python 2 has reached its (deferred) end-of-life by the end
of 2019. Many important upstream projects have already removed support
for Python 2. Those packages are frequently dependencies of other
packages, causing the cost of maintaining Python 2 support to grow
exponentially.</p>
<p>Early removal of unnecessary Python 2 support will both reduce
the long-term maintenance costs, and give users better chance to prepare
than delaying it until the number of packages losing Python 2 support
will cause major upgrade issues.</p>
</section>
</section>
</section>
<span id="document-maintainer"></span><section id="package-maintainers">
<h2>Package Maintainers<a class="headerlink" href="#package-maintainers" title="Permalink to this headline">¶</a></h2>
<section id="pg0601">
<span id="adding-new-maintainers"></span><span id="index-0"></span><h3>Adding new maintainers<a class="headerlink" href="#pg0601" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0601</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>Developers must not add other developers as package maintainers, unless
the developers in question consent to that. Developers must not add
projects that they are not members of as package maintainers, unless
one of the project members explicitly agrees to that or the project
policy explicitly permits it.</p>
<p><em>Rationale</em>: this policy aims to prevent package maintainers being added
as backup maintainers without their consent or knowledge. What’s worse,
once the original maintainer resigns the packages frequently drop
to backup maintainers who are neither interested in maintaining them,
nor often aware why they are listed as maintainers.</p>
<p>For example, developers used to frequently add Python team as a backup
maintainer to various packages not fitting the project’s profile. This
includes various end-user programs written in Python. Many of those
packages ended up being maintained solely by Python, and distinguishing
them from packages actually within project’s profile was hard.</p>
</section>
<section id="pg0602">
<span id="new-packages-without-a-maintainer"></span><span id="index-1"></span><h3>New packages without a maintainer<a class="headerlink" href="#pg0602" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0602</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>It is explicitly forbidden to add new packages without a dedicated
maintainer. This does not apply if the package in question is not
technically a new one but merely split out of unmaintained package.</p>
<p><em>Rationale</em>: Gentoo is currently suffering from a very large number
of packages without a maintainer. There is a small group of developers
trying to fix them as necessary. It is unfair and inappropriate
to increase their maintenance burden by adding new packages and refusing
to take care of them.</p>
<span class="target" id="index-2"></span></section>
<section id="pg0603">
<span id="removing-package-maintainers"></span><span id="index-3"></span><h3>Removing package maintainers<a class="headerlink" href="#pg0603" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0603</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>When removing maintainers from a package, the developer must reassign
all bugs filed for it. Furthermore, when removing the last maintainer
for a package, the developer must add the following comment
to <code class="docutils literal notranslate"><span class="pre">metadata.xml</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><!-- maintainer-needed -->
</pre></div>
</div>
<p>Furthermore, the developer must send an ‘up for grabs’ mail
to gentoo-dev mailing list, containing the list of packages with
no maintainer. If possible, please include any information that could
be helpful to future maintainers.</p>
<p><em>Rationale</em>: reassigning bugs is necessary to make sure that old bugs
are not lost assigned to developers who are no longer interested
in them. The maintainer-needed comment is meant to make it possible
to easily grep for unmaintained packages. The ‘up for grabs’ mails aim
to increase the chances of packages finding a new maintainers (compared
to them silently becoming maintainer-needed).</p>
</section>
</section>
<span id="document-other-metadata"></span><section id="other-metadata-variables">
<h2>Other metadata variables<a class="headerlink" href="#other-metadata-variables" title="Permalink to this headline">¶</a></h2>
<span class="target" id="index-0"></span><section id="pg0701">
<span id="dynamic-slots-multislot-flag"></span><span id="index-1"></span><h3>Dynamic slots (multislot flag)<a class="headerlink" href="#pg0701" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0701</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA (inferred from PMS)</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT</a>, <a class="reference external" href="https://bugs.gentoo.org/174407">https://bugs.gentoo.org/174407</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p><code class="docutils literal notranslate"><span class="pre">use</span></code> in global scope triggers fatal error</p>
</dd>
</dl>
<p>The use of <code class="docutils literal notranslate"><span class="pre">multislot</span></code> to alter <code class="docutils literal notranslate"><span class="pre">SLOT</span></code> values (as well as any other
USE-dependent slot values) in the Gentoo repository is forbidden.
Such a feature can be used in overlays, and it is acceptable to provide
such support in eclasses as long as it is not used in ::gentoo.</p>
<p>This policy has been explicitly declared in response to historical
(pre-2016) use of <code class="docutils literal notranslate"><span class="pre">USE=multislot</span></code> in toolchain ebuilds. When the flag
was disabled, all package versions used the same slot, and upgrades were
handled as for non-slotted packages. When the flag was enabled, each
version used a separate slot, permitting multiple versions being
installed simultaneously. This allowed the user to choose between
the two options.</p>
<p>The original violation has been resolved by unconditionally slotting
the packages. This permitted the users to install multiple versions
in parallel, while removal of old versions was to be handled via
<code class="docutils literal notranslate"><span class="pre">emerge</span> <span class="pre">--depclean</span></code>.</p>
<p><em>Rationale</em>: this feature was in direct violation of PMS <a class="reference external" href="https://projects.gentoo.org/pms/7/pms.html#x1-600007.1">metadata
invariance</a> requirements. It caused the cached slot value to depend
on the state of querying the USE flag (which in turn could technically
depend on slot, via <code class="docutils literal notranslate"><span class="pre">package.use</span></code>). This caused undefined package
manager behavior which could include use of unpredictable slot, cache
invalidation or explicit errors.</p>
</section>
<section id="pg0702">
<span id="homepage-value-must-be-meaningful"></span><span id="index-2"></span><h3>HOMEPAGE value must be meaningful<a class="headerlink" href="#pg0702" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0702</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035">https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>known bad values are reported by pkgcheck</p>
</dd>
</dl>
<p>The HOMEPAGE specified for the package should either be dedicated
to the package in question or make it easy to find dedicated
information. Packages must not use <code class="docutils literal notranslate"><span class="pre">https://www.gentoo.org/</span></code>
or a similar generic homepage. If no homepage is available, the special
value of <code class="docutils literal notranslate"><span class="pre">https://wiki.gentoo.org/wiki/No_homepage</span></code> must be used.</p>
<p><em>Rationale</em>: The homepage specified in ebuilds is normally used to
locate information about the upstream project, e.g. downloads, source
code repository, bug tracker, documentation. Homepages that make it
hard to locate information about a specific project have little value,
and the Gentoo homepage generally does not do a good job at linking even
major Gentoo projects. Furthermore, many of the projects did not even
have a single dedicated subpage anywhere in Gentoo web space. In all
those cases, using the explicit No_homepage marker at least makes it
easy to identify such packages.</p>
</section>
<section id="pg0703">
<span id="restrict-test-for-use-test"></span><span id="index-3"></span><h3>RESTRICT=test for USE=-test<a class="headerlink" href="#pg0703" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0703</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>by pkgcheck</p>
</dd>
</dl>
<p>Whenever the package uses <code class="docutils literal notranslate"><span class="pre">test</span></code> flag to control test prerequisites
(or another flag with a similar purpose), it must explicitly restrict
tests when the flag is unset.</p>
<p><em>Example</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">IUSE</span><span class="o">=</span><span class="s2">"test"</span>
<span class="n">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span>
</pre></div>
</div>
<p><em>Rationale</em>: contrary to common assumption, <code class="docutils literal notranslate"><span class="pre">test</span></code> flag is not special
and the package manager can execute tests when the flag is disabled.
The explicit restriction guarantees that tests will be skipped under
this circumstance, and they will not fail for users.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Technically there are packages that do not strictly require this
restriction since they handle missing test prerequisites gracefully
(e.g. by skipping the tests). However, we enforce the rule for all
packages since omitting the restriction by mistake is much more
common, and there is little harm in overspecifying it.</p>
</div>
</section>
<section id="pg0704">
<span id="license"></span><span id="index-4"></span><h3>LICENSE<a class="headerlink" href="#pg0704" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0704</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reported</dt>
<dd class="field-odd"><p>no</p>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> variable must explicitly list licenses for all files
installed by the package. If some of the applicable licenses are
conditional to USE flags, appropriate USE conditionals need to
be expressed in the variable.</p>
<p>If a package bundles any dependencies that are either installed,
statically linked or in any other way combined with installed files,
the licenses of these dependencies need to be listed as well. This
is not presently required when statically linking to dependencies
installed by separate packages in the repository.</p>
<p>The licenses for files that are not installed but that are used at build
time are not listed explicitly.</p>
<p><em>Rationale</em>: the primary purpose of the license support in the package
manager is to provide the users with ability to decide on acceptable
licenses for their installed systems (and binary packages). In order
for this to work effectively, the packages must provide a correct
and complete license list.</p>
<p>Static linking combines code from multiple packages, potentially covered
by different licenses. Listing all licenses is the simplest way
of ensuring that nothing is missed, as well as protecting against wrong
derivative work licenses stated upstream (i.e. when a less restrictively
licensed package links to a more restrictively licensed dependency).</p>
<p>Listing of licenses is enforced for bundled dependencies but not for
static linking to other packages, as in the latter case it is
non-trivial to implement and the package manager already verifies
the license while building dependencies (but not when installing binary
packages).</p>
<p>The ebuild format does not provide a separate variable to list licenses
needed only at build time. So far it has not been considered important
enough to have one, as the relevant files exist only temporarily
on the user’s system and do not affect the runtime use of packages.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Please remember to include the licenses of support files provided
by the ebuild, e.g. init.d scripts (usually GPL-2).</p>
</div>
</section>
</section>
<span id="document-use-flags"></span><section id="use-flags">
<h2>USE flags<a class="headerlink" href="#use-flags" title="Permalink to this headline">¶</a></h2>
<section id="pg0801">
<span id="versioned-use-flags"></span><span id="index-0"></span><h3>Versioned USE flags<a class="headerlink" href="#pg0801" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0801</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>If a need arises to create new USE flags responsible for switching
between multiple versions of a specific dependency, it is recommended
that flat, explicitly versioned flags are used (e.g. <code class="docutils literal notranslate"><span class="pre">qt4</span></code>, <code class="docutils literal notranslate"><span class="pre">qt5</span></code>).
The hierarchical form used e.g. by GTK+ (<code class="docutils literal notranslate"><span class="pre">gtk</span></code> meaning 2-or-3,
then optionally <code class="docutils literal notranslate"><span class="pre">gtk2</span></code> or <code class="docutils literal notranslate"><span class="pre">gtk3</span></code> to switch between both)
is discouraged.</p>
<p>Any future set of USE flags introduced in this way needs to be discussed
with the QA team before introduction.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This policy has historically been defined as an generalization
of the QA policy on gtk/gtk2/gtk3 flags. The latter policy has been
removed since.</p>
</div>
</section>
<section id="pg0802">
<span id="use-gui-flag"></span><span id="index-1"></span><h3>USE=gui flag<a class="headerlink" href="#pg0802" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0802</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722">https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>no</p>
</dd>
</dl>
<p>Whenever a package offers an optional GUI support, the <code class="docutils literal notranslate"><span class="pre">gui</span></code> flag must
be used to control that support rather than historically used <code class="docutils literal notranslate"><span class="pre">X</span></code>
or toolkit flags. Toolkit flags can still be used to choose between
multiple available GUIs, or when the toolkit is used in a more
specialized way than for GUI (e.g. to control installing widgets).</p>
<p><em>Rationale</em>: the historical use of toolkit flags to control building
GUIs made it very hard for users to express the simple wish of ‘I want
<em>any</em> GUI’. Installing various packages made it necessary to either
adjust flags per package (manually discovering which flags are necessary
to obtain the GUI) or enabling multiple toolkits globally which
afterwards caused issues with packages supporting a choice between
multiple GUIs.</p>
</section>
<section id="pg0803">
<span id="underscores-in-use-flag-names"></span><span id="index-2"></span><h3>Underscores in USE flag names<a class="headerlink" href="#pg0803" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0803</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>Council</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt">https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>by pkgcheck</p>
</dd>
</dl>
<p>Underscores are reserved for USE_EXPAND flags, and must not be used
within names of newly-defined regular flags. Existing uses are
considered technically valid, and phasing them out has low priority.</p>
<p>Flags that attempt to resemble USE_EXPAND should be either converted
into proper (global) USE_EXPAND, or made into shorter (unprefixed)
local flags. In other flags, replacing underscore with hyphen is
recommended.</p>
<p><em>Rationale</em>: a few packages in Gentoo attempted to imitate USE_EXPAND
via local USE flags. This has no clear advantage, may be confusing
to end users who assume that they will work like USE_EXPAND
and in the end unnecessarily lengthens flag names or even causes
unnecessary mismatches between global flags and local flags.</p>
<p>Extending the rule to all flags containing underscores aims to make
distinguishing USE_EXPAND and regular flags easier. It also improves
consistency between flag names that historically used hyphens
or underscores depending on developer’s personal preference.</p>
</section>
</section>
<span id="document-user-group"></span><section id="users-and-groups">
<h2>Users and groups<a class="headerlink" href="#users-and-groups" title="Permalink to this headline">¶</a></h2>
<span class="target" id="index-0"></span><section id="pg0901">
<span id="user-and-group-account-policy"></span><span id="index-1"></span><h3>User and group account policy<a class="headerlink" href="#pg0901" title="Permalink to this headline">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">PG</dt>
<dd class="field-odd"><p>0901</p>
</dd>
<dt class="field-even">Source</dt>
<dd class="field-even"><p>QA</p>
</dd>
<dt class="field-odd">Reference</dt>
<dd class="field-odd"><p><a class="reference external" href="https://bugs.gentoo.org/702460">https://bugs.gentoo.org/702460</a></p>
</dd>
<dt class="field-even">Reported</dt>
<dd class="field-even"><p>by repoman and pkgcheck (as deprecated eclass)</p>
</dd>
</dl>
<p>All new user/group accounts must be created via <a class="reference external" href="https://www.gentoo.org/glep/glep-0081.html">GLEP 81</a> packages.
The existing packages should be migrated on the next version bump or
major update.</p>
<p>Existing and historical fixed UIDs/GIDs in range 0..499 (used
in baselayout or via user.eclass) as listed in uid-gid.txt can be reused
as-is in acct-* packages.</p>
<p>UIDs and GIDs in range 0..100 are reserved for important system
accounts. New assignments in that range need to be explicitly approved
by the QA lead, in response to a justified request from the developer.</p>
<p>The range 101..749 is provided for regular use by packages.
The assignments from this range follow the following rules:</p>
<ol class="arabic simple">
<li><p>A developer can select an arbitrary free UID/GID from this range.
If in doubt, it is recommended to select successive numbers from 101
upwards.</p></li>
<li><p>Unless there is a very good reason not to, matching users and groups
should use the same number. It is acceptable to leave gaps
in assignments as a result of that.</p></li>
<li><p>Before pushing the new acct-* packages, the developer must push
an update to uid-gid.txt adding the ‘acct’ entry for the desired
UID/GID. This serves as a synchronization primitive to prevent
collisions.</p></li>
</ol>
<p>Further UID/GID ranges will be open in the future as the need arises.</p>
<p><em>Rationale</em>: this is the second version of the policy for GLEP 81
packages. It simplifies the process to aid rapid adoption of the new
system. Review requirement and pointless cross-distro syncing were
removed, in favor of a simple process of allocating the next free number
and using it.</p>
<p>The ranges have been chosen to delay the imminent collision between
explicitly reserved UIDs / GIDs and the ones allocated dynamically by
user.eclass (starting from 999 downwards). The lowest GID range has
been reserved for true system users and groups.</p>
</section>
</section>
</div>
</section>
<section id="indices-and-tables">
<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
</ul>
</section>
</div>
<div class="col-md-3 hidden-sm hidden-xs" role="main">
<div class="" role="navigation" aria-label="main navigation">
<div class="">
<nav class="bs-docs-sidebar" data-spy="affix" data-offset-top="140" data-offset-bottom="400">
<p class="hidden" role="heading"><span class="hidden-text">Contents:</span></p>
<ul class='nav'>
<li class="toctree-l1"><a class="reference internal" href="#document-preface">Preface</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#authors">Authors</a></li>
<li class="toctree-l2"><a class="reference internal" href="#license">License</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-motivation">Motivation and history</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#historical-state-of-policy-documentation">Historical state of policy documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#purpose-of-the-policy-guide">Purpose of the Policy Guide</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-basics">Basic information</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#goals-of-policy-making">Goals of policy making</a></li>
<li class="toctree-l2"><a class="reference internal" href="#policy-compliance-checking">Policy compliance checking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#policy-enforcement">Policy enforcement</a></li>
<li class="toctree-l2"><a class="reference internal" href="#policy-making-changes-and-appeals">Policy making, changes and appeals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-other-docs">Other policy documents</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#gentoo-specific-documentation">Gentoo-specific documentation</a><ul class='nav'>
<li class="toctree-l3"><a class="reference internal" href="#package-manager-specification">Package Manager Specification</a></li>
<li class="toctree-l3"><a class="reference internal" href="#gleps">GLEPs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#developer-manual">Developer Manual</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#external-standards">External standards</a><ul class='nav'>
<li class="toctree-l3"><a class="reference internal" href="#posix">POSIX</a></li>
<li class="toctree-l3"><a class="reference internal" href="#fhs">FHS</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-dependencies">Dependencies</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0001">Optional runtime dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0002">=-dependencies with no revision</a></li>
<li class="toctree-l2"><a class="reference internal" href="#slot-and-subslot-dependencies">Slot and subslot dependencies</a><ul class='nav'>
<li class="toctree-l3"><a class="reference internal" href="#pg0011">on (sub-)slotted packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pg0012">special case: Qt packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#proactive-use-of-slot-operators">proactive use of slot operators</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#pg0003">Revision bumps on runtime dependency changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#use-dependencies">USE dependencies</a><ul class='nav'>
<li class="toctree-l3"><a class="reference internal" href="#pg0021">on packages without the flag</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-deprecation">Deprecations</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg1001">Deprecated EAPIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg1003">Deprecated eclasses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-ebuild-format">Ebuild file format</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0101">Coding style</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0102">Code must be contained within ebuild and eclasses</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0103">HOMEPAGE must not contain variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0104">SRC_URI must not refer to HOMEPAGE</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0105">KEYWORDS must be defined on a single line</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0106">LICENSE must not contain variables</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-filesystem">File system layout</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0201">Installation paths</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0202">Support for separate /usr</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0203">Strict multilib layout</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0204">Static libraries and libtool files</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0205">Game install locations and ownership</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0206">Absolute symbolic link targets</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-installed-files">Installed files</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0301">Installation of small files</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0302">Installation of static libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0303">Installation of libtool (.la) files</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0304">Virtuals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-keywords">Keywording and stabilization</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0401">Rekeywording on dropped keywords</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0402">Stabilizing new versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0403">Removing stable keywords</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-languages">Language-specific policies</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#python">Python</a><ul class='nav'>
<li class="toctree-l3"><a class="reference internal" href="#pg0501">Eclass usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pg0502">Python 2 deprecation</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-maintainer">Package Maintainers</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0601">Adding new maintainers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0602">New packages without a maintainer</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0603">Removing package maintainers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-other-metadata">Other metadata variables</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0701">Dynamic slots (multislot flag)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0702">HOMEPAGE value must be meaningful</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0703">RESTRICT=test for USE=-test</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0704">LICENSE</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-use-flags">USE flags</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0801">Versioned USE flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0802">USE=gui flag</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pg0803">Underscores in USE flag names</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#document-user-group">Users and groups</a><ul class='nav'>
<li class="toctree-l2"><a class="reference internal" href="#pg0901">User and group account policy</a></li>
</ul>
</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-xs-12 col-md-offset-2 col-md-7">
<h3 class="footerhead">None</h3>
<div class="row">
<div class="col-xs-12 col-md-4">
<span class="kk-group-header">Powered by</span><br><span><a href="http://sphinx-doc.org/">Sphinx 4.5.0</a> & <a href="https://github.com/mmagorsc/tyrian_sphinx_theme">Tyrian Theme 0.0.7</a></span>
</div>
<div class="col-xs-12 col-md-4">
</div>
<div class="col-xs-12 col-md-4">
</div>
</div>
</div>
<div class="col-xs-12 col-md-3">
<h3 class="footerhead">Questions or comments?</h3>
Please feel free to <a href="https://www.gentoo.org/inside-gentoo/contact/">contact us</a>.
</div>
</div>
<div class="row">
<div class="col-xs-2 col-sm-3 col-md-2">
<ul class="footerlinks three-icons">
<li><a href="https://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li>
<li><a href="https://plus.google.com/+Gentoo" title="+Gentoo on Google+"><span class="fa fa-google-plus fa-fw"></span></a></li>
<li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li>
</ul>
</div>
<div class="col-xs-10 col-sm-9 col-md-10">
<strong>© 2001–2020 Gentoo Foundation, Inc.</strong><br>
<small>
Gentoo is a trademark of the Gentoo Foundation, Inc.
The contents of this document, unless otherwise expressly stated, are licensed under the
<a href="https://creativecommons.org/licenses/by-sa/4.0/" rel="license">CC-BY-SA-4.0</a> license.
The <a href="https://www.gentoo.org/inside-gentoo/foundation/name-logo-guidelines.html">Gentoo Name and Logo Usage Guidelines</a> apply.
</small>
</div>
</div>
</div>
</footer>
<script src="https://assets.gentoo.org/tyrian/bootstrap.min.js"></script>
<div id="custom_toc">
<span style="border-bottom: 1px solid #e1e1e1;font-weight: bold;">Contents</span>
[<a class="" id="show_contents" role="button" data-toggle="collapse" href="#collapseExample" aria-expanded="false" aria-controls="collapseExample">show</a>]
<div class="collapse" id="collapseExample" style="margin-top:10px;">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-preface">Preface</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#authors">Authors</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#license">License</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-motivation">Motivation and history</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#historical-state-of-policy-documentation">Historical state of policy documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#purpose-of-the-policy-guide">Purpose of the Policy Guide</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-basics">Basic information</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#goals-of-policy-making">Goals of policy making</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#policy-compliance-checking">Policy compliance checking</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#policy-enforcement">Policy enforcement</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#policy-making-changes-and-appeals">Policy making, changes and appeals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-other-docs">Other policy documents</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#gentoo-specific-documentation">Gentoo-specific documentation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#package-manager-specification">Package Manager Specification</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#gleps">GLEPs</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#developer-manual">Developer Manual</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#external-standards">External standards</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#posix">POSIX</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#fhs">FHS</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-dependencies">Dependencies</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0001">Optional runtime dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0002">=-dependencies with no revision</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#slot-and-subslot-dependencies">Slot and subslot dependencies</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#pg0011">on (sub-)slotted packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#pg0012">special case: Qt packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proactive-use-of-slot-operators">proactive use of slot operators</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0003">Revision bumps on runtime dependency changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#use-dependencies">USE dependencies</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#pg0021">on packages without the flag</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-deprecation">Deprecations</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg1001">Deprecated EAPIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg1003">Deprecated eclasses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-ebuild-format">Ebuild file format</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0101">Coding style</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0102">Code must be contained within ebuild and eclasses</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0103">HOMEPAGE must not contain variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0104">SRC_URI must not refer to HOMEPAGE</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0105">KEYWORDS must be defined on a single line</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0106">LICENSE must not contain variables</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-filesystem">File system layout</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0201">Installation paths</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0202">Support for separate /usr</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0203">Strict multilib layout</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0204">Static libraries and libtool files</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0205">Game install locations and ownership</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0206">Absolute symbolic link targets</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-installed-files">Installed files</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0301">Installation of small files</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0302">Installation of static libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0303">Installation of libtool (.la) files</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0304">Virtuals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-keywords">Keywording and stabilization</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0401">Rekeywording on dropped keywords</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0402">Stabilizing new versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0403">Removing stable keywords</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-languages">Language-specific policies</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#python">Python</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#pg0501">Eclass usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#pg0502">Python 2 deprecation</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-maintainer">Package Maintainers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0601">Adding new maintainers</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0602">New packages without a maintainer</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0603">Removing package maintainers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-other-metadata">Other metadata variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0701">Dynamic slots (multislot flag)</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0702">HOMEPAGE value must be meaningful</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0703">RESTRICT=test for USE=-test</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0704">LICENSE</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-use-flags">USE flags</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0801">Versioned USE flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0802">USE=gui flag</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0803">Underscores in USE flag names</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-user-group">Users and groups</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#pg0901">User and group account policy</a></li>
</ul>
</li>
</ul>
</div>
</div>
<script type="text/javascript">
$("#custom_toc").prependTo(".toctree-wrapper");
$("#custom_toc").css("display", "inline-block");
$('#collapseExample').on('show.bs.collapse', function () {
$("#show_contents").html("hide");
})
$('#collapseExample').on('hide.bs.collapse', function () {
$("#show_contents").html("show");
})
$("#collapseExample").collapse('show');
$("#show_contents").html("hide");
</script>
<script type="text/javascript">
$('body').scrollspy({
target: '.bs-docs-sidebar',
offset: 40
});
</script>
<script type="text/javascript">
$('#indices-and-tables').hide()
</script>
</body>
</html>
|
GitWeb