all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob 1fb6ce2e1e4c170a417b33f34375abecc07d6fe5 153850 bytes (raw)
name: doc/contributing.texi 	 # note: path name is non-authoritative(*)

   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
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
 
@node Contributing
@chapter Contributing

This project is a cooperative effort, and we need your help to make it
grow!  Please get in touch with us on @email{guix-devel@@gnu.org} and
@code{#guix} on the Libera Chat IRC network.  We welcome ideas, bug
reports, patches, and anything that may be helpful to the project.  We
particularly welcome help on packaging (@pxref{Packaging Guidelines}).

@cindex code of conduct, of contributors
@cindex contributor covenant
We want to provide a warm, friendly, and harassment-free environment, so
that anyone can contribute to the best of their abilities.  To this end
our project uses a ``Contributor Covenant'', which was adapted from
@url{https://contributor-covenant.org/}.  You can find a local version in
the @file{CODE-OF-CONDUCT} file in the source tree.

Contributors are not required to use their legal name in patches and
on-line communication; they can use any name or pseudonym of their
choice.

@menu
* Requirements::                Software needed to build and run Guix.
* Building from Git::           The latest and greatest.
* Running the Test Suite::      Testing Guix.
* Running Guix Before It Is Installed::  Hacker tricks.
* The Perfect Setup::           The right tools.
* Alternative Setups::          Other possible tools that do the job.
* Source Tree Structure::       Source code guided tour.
* Packaging Guidelines::        Growing the distribution.
* Coding Style::                Hygiene of the contributor.
* Submitting Patches::          Share your work.
* Tracking Bugs and Changes::   Keeping it all organized.
* Commit Access::               Pushing to the official repository.
* Reviewing the Work of Others::  Some guidelines for sharing reviews.
* Updating the Guix Package::   Updating the Guix package definition.
* Deprecation Policy::          Commitments and tools for deprecation.
* Writing Documentation::       Improving documentation in GNU Guix.
* Translating Guix::            Make Guix speak your native language.
* Contributing to Guix's infrastructure::  Make Guix ecosystem work better.
@end menu

@node Requirements
@section Requirements

You can easily hack on Guix itself using Guix and Git, which we use for
version control (@pxref{Building from Git}).

But when packaging Guix for foreign distros or when bootstrapping on
systems without Guix, and if you decide to not just trust and install
our readily made binary (@pxref{Binary Installation}), you can download
a release version of our reproducible source tarball and read on.

This section lists requirements when building Guix from source.  The
build procedure for Guix is the same as for other GNU software, and is
not covered here.  Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.

@cindex official website
GNU Guix is available for download from its website at
@url{https://www.gnu.org/software/guix/}.

GNU Guix depends on the following packages:

@itemize
@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
version 3.0.3 or later;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
Preparations, how to install the GnuTLS bindings for Guile,,
gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
until version 3.7.8 included.};
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
version 0.1.0 or later;
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
or later;
@item @uref{https://git-scm.com, Git} (yes, both!);
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
4.3.0 or later;
@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize

The following dependencies are optional:

@itemize
@item
@c Note: We need at least 0.13.0 for #:nodelay.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
version 0.13.0 or later.

@item
@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
compression and decompression in @command{guix publish} and for
substitutes (@pxref{Invoking guix publish}).

@item
@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
the @code{crate} importer (@pxref{Invoking guix import}).

@item
@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
the @code{go} importer (@pxref{Invoking guix import}) and for some of
the ``updaters'' (@pxref{Invoking guix refresh}).

@item
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
@end itemize

Unless @option{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:

@itemize
@item @url{https://gnupg.org/, GNU libgcrypt};
@item @url{https://sqlite.org, SQLite 3};
@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize

@node Building from Git
@section Building from Git

If you want to hack Guix itself, it is recommended to use the latest
version from the Git repository:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex authentication, of a Guix checkout
How do you ensure that you obtained a genuine copy of the repository?
To do that, run @command{guix git authenticate}, passing it the commit
and OpenPGP fingerprint of the @dfn{channel introduction}
(@pxref{Invoking guix git authenticate}):

@c The commit and fingerprint below must match those of the channel
@c introduction in '%default-channels'.
@example
git fetch origin keyring:keyring
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@noindent
This command completes with exit code zero on success; it prints an
error message and exits with a non-zero code otherwise.

As you can see, there is a chicken-and-egg problem: you first need to
have Guix installed.  Typically you would install Guix System
(@pxref{System Installation}) or Guix on top of another distro
(@pxref{Binary Installation}); in either case, you would verify the
OpenPGP signature on the installation medium.  This ``bootstraps'' the
trust chain.

The easiest way to set up a development environment for Guix is, of
course, by using Guix!  The following command starts a new shell where
all the dependencies and appropriate environment variables are set up to
hack on Guix:

@example
guix shell -D guix -CPW
@end example

or even, from within a Git worktree for Guix:

@example
guix shell -CPW
@end example

If @option{-C} (short for @option{--container}) is not supported on your
system, try @command{--pure} instead of @option{-CPW}.
@xref{Invoking guix shell}, for more information on that command.

If you are unable to use Guix when building Guix from a checkout, the
following are the required packages in addition to those mentioned in the
installation instructions (@pxref{Requirements}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
@item @url{https://gnu.org/software/automake/, GNU Automake};
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
@item @url{https://www.graphviz.org/, Graphviz};
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

On Guix, extra dependencies can be added by instead running @command{guix
shell}:

@example
guix shell -D guix help2man git strace --pure
@end example

From there you can generate the build system infrastructure
using Autoconf and Automake:

@example
./bootstrap
@end example

If you get an error like this one:

@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example

@noindent
it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
provided by pkg-config.  Make sure that @file{pkg.m4} is available.  The
same holds for the @file{guile.m4} set of macros provided by Guile.  For
instance, if you installed Automake in @file{/usr/local}, it wouldn’t
look for @file{.m4} files in @file{/usr/share}.  In that case, you have
to invoke the following command:

@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example

@xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
more information.

@cindex state directory
@cindex localstatedir
@cindex system configuration directory
@cindex sysconfdir
Then, run:

@example
./configure
@end example

@noindent
... where @file{/var} is the normal @code{localstatedir} value
(@pxref{The Store}, for information about this) and @file{/etc} is the
normal @code{sysconfdir} value.  Note that you will probably not run
@command{make install} at the end (you don't have to) but it's still
important to pass the right @code{localstatedir} and @code{sysconfdir}
values, which get recorded in the @code{(guix config)} Guile module.

Finally, you can build Guix and, if you feel so inclined, run the tests
(@pxref{Running the Test Suite}):

@example
make
make check
@end example

@noindent
If anything fails, take a look at installation instructions
(@pxref{Installation}) or send a message to the
@email{guix-devel@@gnu.org, mailing list}.

From there on, you can authenticate all the commits included in your
checkout by running:

@example
guix git authenticate \
  9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

The first run takes a couple of minutes, but subsequent runs are faster.
On subsequent runs, you can run the command without any arguments since
the @dfn{introduction} (the commit ID and OpenPGP fingerprints above)
will have been recorded@footnote{This requires a recent version of Guix,
from May 2024 or more recent.}:

@example
guix git authenticate
@end example

When your configuration for your local Git repository doesn't match
the default one, you can provide the reference for the @code{keyring}
branch @i{via} the @option{-k} option.  The following
example assumes that you have a Git remote called @samp{myremote}
pointing to the official repository:

@example
guix git authenticate \
  -k myremote/keyring \
  9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@xref{Invoking guix git authenticate}, for more information on this
command.

@quotation Note
By default, hooks are installed such that @command{guix git
authenticate} is invoked anytime you run @command{git pull} or
@command{git push}.
@end quotation

After updating the repository, @command{make} might fail with an error
similar to the following example:

@example
error: failed to load 'gnu/packages/linux.scm':
ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
@end example

This means that one of the record types that Guix defines (in this
example, the @code{origin} record) has changed, and all of guix needs
to be recompiled to take that change into account.  To do so, run
@command{make clean-go} followed by @command{make}.

Should @command{make} fail with an Automake error message after
updating, you need to repeat the steps outlined in this section,
commencing with @command{./bootstrap}.

@node Running the Test Suite
@section Running the Test Suite

@cindex test suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite.  It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software.  To run the test
suite, type:

@example
make check
@end example

Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up.  The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
that is created for test purposes will already have various things in
cache.

It is also possible to run a subset of the tests by defining the
@code{TESTS} makefile variable as in this example:

@example
make check TESTS="tests/store.scm tests/cpio.scm"
@end example

By default, tests results are displayed at a file level.  In order to
see the details of every individual test cases, it is possible to define
the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:

@example
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
@end example

The underlying SRFI 64 custom Automake test driver used for the 'check'
test suite (located at @file{build-aux/test-driver.scm}) also allows
selecting which test cases to run at a finer level, via its
@option{--select} and @option{--exclude} options.  Here's an example, to
run all the test cases from the @file{tests/packages.scm} test file
whose names start with ``transaction-upgrade-entry'':

@example
export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
make check TESTS="tests/packages.scm"
@end example

Those wishing to inspect the results of failed tests directly from the
command line can add the @option{--errors-only=yes} option to the
@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
Automake makefile variable, as in:

@example
make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
@end example

The @option{--show-duration=yes} option can be used to print the
duration of the individual test cases, when used in combination with
@option{--brief=no}:

@example
make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
@end example

@xref{Parallel Test Harness,,,automake,GNU Automake} for more
information about the Automake Parallel Test Harness.

Upon failure, please email @email{bug-guix@@gnu.org} and attach the
@file{test-suite.log} file.  Please specify the Guix version being used
as well as version numbers of the dependencies (@pxref{Requirements}) in
your message.

Guix also comes with a whole-system test suite that tests complete
Guix System instances.  It can only run on systems where
Guix is already installed, using:

@example
make check-system
@end example

@noindent
or, again, by defining @code{TESTS} to select a subset of tests to run:

@example
make check-system TESTS="basic mcron"
@end example

These system tests are defined in the @code{(gnu tests @dots{})}
modules.  They work by running the operating systems under test with
lightweight instrumentation in a virtual machine (VM).  They can be
computationally intensive or rather cheap, depending on whether
substitutes are available for their dependencies (@pxref{Substitutes}).
Some of them require a lot of storage space to hold VM images.

If you encounter an error like:

@example
Compiling Scheme modules...
ice-9/eval.scm:142:16: In procedure compile-top-call:
error: all-system-tests: unbound variable
hint: Did you forget `(use-modules (gnu tests))'?
@end example

@noindent
there may be inconsistencies in the work tree from previous builds.  To
resolve this, try running @command{make clean-go} followed by
@command{make}.

Again in case of test failures, please send @email{bug-guix@@gnu.org}
all the details.

@node Running Guix Before It Is Installed
@section Running Guix Before It Is Installed

In order to keep a sane working environment, you will find it useful to
test the changes made in your local source tree checkout without
actually installing them.  So that you can distinguish between your
``end-user'' hat and your ``motley'' costume.

To that end, all the command-line tools can be used even if you have not
run @code{make install}.  To do that, you first need to have an
environment with all the dependencies available (@pxref{Building from
Git}), and then simply prefix each command with @command{./pre-inst-env}
(the @file{pre-inst-env} script lives in the top build tree of Guix;
@pxref{Building from Git} to generate it).  As an example, here is how you
would build the @code{hello} package as defined in your working tree (this
assumes @command{guix-daemon} is already running on your system; it's OK if
it's a different version):

@example
$ ./pre-inst-env guix build hello
@end example

@noindent
Similarly, an example for a Guile session using the Guix modules:

@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

;;; ("x86_64-linux")
@end example

@noindent
@cindex REPL
@cindex read-eval-print loop
@dots{} and for a REPL (@pxref{Using Guix Interactively}):

@example
$ ./pre-inst-env guile
scheme@@(guile-user)> ,use(guix)
scheme@@(guile-user)> ,use(gnu)
scheme@@(guile-user)> (define snakes
                       (fold-packages
                         (lambda (package lst)
                           (if (string-prefix? "python"
                                               (package-name package))
                               (cons package lst)
                               lst))
                         '()))
scheme@@(guile-user)> (length snakes)
$1 = 361
@end example

If you are hacking on the daemon and its supporting code or if
@command{guix-daemon} is not already running on your system, you can
launch it straight from the build tree@footnote{The @option{-E} flag to
@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
such that @command{guix-daemon} and the tools it uses can find the Guile
modules they need.}:

@example
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
@end example

The @command{pre-inst-env} script sets up all the environment variables
necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.

Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
local source tree; it simply updates the @file{~/.config/guix/current}
symlink (@pxref{Invoking guix pull}).  Run @command{git pull} instead if
you want to upgrade your local source tree.

Sometimes, especially if you have recently updated your repository,
running @command{./pre-inst-env} will print a message similar to the
following example:

@example
;;; note: source file /home/user/projects/guix/guix/progress.scm
;;;       newer than compiled /home/user/projects/guix/guix/progress.go
@end example

This is only a note and you can safely ignore it.  You can get rid of
the message by running @command{make -j4}.  Until you do, Guile will run
slightly slower because it will interpret the code instead of using
prepared Guile object (@file{.go}) files.

You can run @command{make} automatically as you work using
@command{watchexec} from the @code{watchexec} package.  For example,
to build again each time you update a package file, run
@samp{watchexec -w gnu/packages -- make -j4}.

@node The Perfect Setup
@section The Perfect Setup

The Perfect Setup to hack on Guix is basically the perfect setup used
for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
Manual}).  First, you need more than an editor, you need
@url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
wonderful @url{https://nongnu.org/geiser/, Geiser}.  To set that up, run:

@example
guix install emacs guile emacs-geiser emacs-geiser-guile
@end example

Geiser allows for interactive and incremental development from within
Emacs: code compilation and evaluation from within buffers, access to
on-line documentation (docstrings), context-sensitive completion,
@kbd{M-.} to jump to an object definition, a REPL to try out your code,
and more (@pxref{Introduction,,, geiser, Geiser User Manual}).  If you
allow Emacs to load the @file{.dir-locals.el} file at the root of the
project checkout, it will cause Geiser to automatically add the local
Guix sources to the Guile load path.

To actually edit the code, Emacs already has a neat Scheme mode.  But in
addition to that, you must not miss
@url{https://www.emacswiki.org/emacs/ParEdit, Paredit}.  It provides
facilities to directly operate on the syntax tree, such as raising an
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.

@cindex code snippets
@cindex templates
@cindex reducing boilerplate
We also provide templates for common git commit messages and package
definitions in the @file{etc/snippets} directory.  These templates can
be used to expand short trigger strings to interactive text snippets. If
you use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you
may want to add the @file{etc/snippets/yas} snippets directory to the
@var{yas-snippet-dirs} variable.  If you use
@url{https://github.com/minad/tempel/, Tempel}, you may want to add the
@file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in
Emacs.

@lisp
;; @r{Assuming the Guix checkout is in ~/src/guix.}
;; @r{Yasnippet configuration}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
;; @r{Tempel configuration}
(with-eval-after-load 'tempel
   ;; Ensure tempel-path is a list -- it may also be a string.
   (unless (listp 'tempel-path)
     (setq tempel-path (list tempel-path)))
   (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
@end lisp

The commit message snippets depend on @url{https://magit.vc/, Magit} to
display staged files.  When editing a commit message type @code{add}
followed by @kbd{TAB} to insert a commit message template for adding a
package; type @code{update} followed by @kbd{TAB} to insert a template
for updating a package; type @code{https} followed by @kbd{TAB} to
insert a template for changing the home page URI of a package to HTTPS.

The main snippet for @code{scheme-mode} is triggered by typing
@code{package...} followed by @kbd{TAB}.  This snippet also inserts the
trigger string @code{origin...}, which can be expanded further.  The
@code{origin} snippet in turn may insert other trigger strings ending on
@code{...}, which also can be expanded further.

@cindex insert or update copyright
@cindex @code{M-x guix-copyright}
@cindex @code{M-x copyright-update}
We additionally provide insertion and automatic update of a copyright in
@file{etc/copyright.el}.  You may want to set your full name, mail, and
load a file.

@lisp
(setq user-full-name "Alice Doe")
(setq user-mail-address "alice@@mail.org")
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(load-file "~/src/guix/etc/copyright.el")
@end lisp

To insert a copyright at the current line invoke @code{M-x guix-copyright}.

To update a copyright you need to specify a @code{copyright-names-regexp}.

@lisp
(setq copyright-names-regexp
      (format "%s <%s>" user-full-name user-mail-address))
@end lisp

You can check if your copyright is up to date by evaluating @code{M-x
copyright-update}.  If you want to do it automatically after each buffer
save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
Emacs.

@node Viewing Bugs within Emacs
@subsection Viewing Bugs within Emacs

Emacs has a nice minor mode called @code{bug-reference}, which, when
combined with @samp{emacs-debbugs} (the Emacs package), can be used to
open links such as @samp{<https://bugs.gnu.org/58697>} or
@samp{<https://issues.guix.gnu.org/58697>} as bug report buffers.  From
there you can easily consult the email thread via the Gnus interface,
reply or modify the bug status, all without leaving the comfort of
Emacs!  Below is a sample configuration to add to your @file{~/.emacs}
configuration file:

@lisp
;;; Bug references.
(require 'bug-reference)
(add-hook 'prog-mode-hook #'bug-reference-prog-mode)
(add-hook 'gnus-mode-hook #'bug-reference-mode)
(add-hook 'erc-mode-hook #'bug-reference-mode)
(add-hook 'gnus-summary-mode-hook #'bug-reference-mode)
(add-hook 'gnus-article-mode-hook #'bug-reference-mode)

;;; This extends the default expression (the top-most, first expression
;;; provided to 'or') to also match URLs such as
;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>.
;;; It is also extended to detect "Fixes: #NNNNN" git trailers.
(setq bug-reference-bug-regexp
      (rx (group (or (seq word-boundary
                          (or (seq (char "Bb") "ug"
                                   (zero-or-one " ")
                                   (zero-or-one "#"))
                              (seq (char "Pp") "atch"
                                   (zero-or-one " ")
                                   "#")
                              (seq (char "Ff") "ixes"
                                   (zero-or-one ":")
                                   (zero-or-one " ") "#")
                              (seq "RFE"
                                   (zero-or-one " ") "#")
                              (seq "PR "
                                   (one-or-more (char "a-z+-")) "/"))
                          (group (one-or-more (char "0-9"))
                                 (zero-or-one
                                  (seq "#" (one-or-more
                                            (char "0-9"))))))
                     (seq (? "<") "https://bugs.gnu.org/"
                          (group-n 2 (one-or-more (char "0-9")))
                          (? ">"))
                     (seq (? "<") "https://issues.guix.gnu.org/"
                          (? "issue/")
                          (group-n 2 (one-or-more (char "0-9")))
                          (? ">"))))))
(setq bug-reference-url-format "https://issues.guix.gnu.org/%s")

(require 'debbugs)
(require 'debbugs-browse)
(add-hook 'bug-reference-mode-hook #'debbugs-browse-mode)
(add-hook 'bug-reference-prog-mode-hook #'debbugs-browse-mode)

;; The following allows Emacs Debbugs user to open the issue directly within
;; Emacs.
(setq debbugs-browse-url-regexp
      (rx line-start
          "http" (zero-or-one "s") "://"
          (or "debbugs" "issues.guix" "bugs")
          ".gnu.org" (one-or-more "/")
          (group (zero-or-one "cgi/bugreport.cgi?bug="))
          (group-n 3 (one-or-more digit))
          line-end))

;; Change the default when run as 'M-x debbugs-gnu'.
(setq debbugs-gnu-default-packages '("guix" "guix-patches"))

;; Show feature requests.
(setq debbugs-gnu-default-severities
 '("serious" "important" "normal" "minor" "wishlist"))
@end lisp

For more information, refer to @ref{Bug Reference,,, emacs, The GNU
Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User
Guide}.

@node Alternative Setups
@section Alternative Setups

Alternative setups than Emacs may let you work on Guix with a
similar development experience and they might work better with the
tools you currently use or help you make the transition to Emacs.

The options listed below only provide the alternatives to the Emacs
based setup, which is the most widely used in the Guix community. If
you want to really understand how is the perfect setup for Guix
development supposed to work, we encourage you to read the section
before this regardless the editor you choose to use.

@menu
* Guile Studio::                First step in your transition to Emacs.
* Vim and NeoVim::              When you are evil to the root.
@end menu

@node Guile Studio
@subsection Guile Studio

Guile Studio is a pre-configured Emacs with mostly everything you need
to start hacking in Guile. If you are not familiar with Emacs it makes
the transition easier for you.

@example
guix install guile-studio
@end example

Guile Studio comes with Geiser preinstalled and prepared for action.

@node Vim and NeoVim
@subsection Vim and NeoVim


Vim (and NeoVim) are also packaged in Guix, just in case you decided
to go for the evil path.

@example
guix install vim
@end example

If you want to enjoy a similar development experience to that in the perfect
setup, you should install several plugins to configure the editor. Vim (and
NeoVim) have the equivalent to Paredit,
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}}, that will help you with the structural editing of Scheme
files (the support for very large files is not great, though).

@example
guix install vim-paredit
@end example

We also recommend that you run @code{:set autoindent} so that your code is
automatically indented as you type.

For the interaction with Git,
@uref{https://www.vim.org/scripts/script.php?script_id=2975,
@code{fugitive.vim}} is the most commonly used plugin:

@example
guix install vim-fugitive
@end example

And of course if you want to interact with Guix directly from inside of
vim, using the built-in terminal emulator, we have our very own
@code{guix.vim} package!

@example
guix install vim-guix-vim
@end example

In NeoVim you can even make a similar setup to Geiser using
@url{https://conjure.fun/, Conjure} that lets you connect to a running Guile
process and inject your code there live (sadly it's not packaged in Guix yet).


@node Source Tree Structure
@section Source Tree Structure

@cindex structure, of the source tree
If you're willing to contribute to Guix beyond packages, or if you'd
like to learn how it all fits together, this section provides a guided
tour in the code base that you may find useful.

Overall, the Guix source tree contains almost exclusively Guile
@dfn{modules}, each of which can be seen as an independent library
(@pxref{Modules,,, guile, GNU Guile Reference Manual}).

The following table gives an overview of the main directories and what
they contain.  Remember that in Guile, each module name is derived from
its file name---e.g., the module in file @file{guix/packages.scm} is
called @code{(guix packages)}.

@table @file
@item guix
This is the location of core Guix mechanisms.  To illustrate what is
meant by ``core'', here are a few examples, starting from low-level
tools and going towards higher-level tools:

@table @code
@item (guix store)
Connecting to and interacting with the build daemon (@pxref{The Store}).
@item (guix derivations)
Creating derivations (@pxref{Derivations}).
@item (guix gexps)
Writing G-expressions (@pxref{G-Expressions}).
@item (guix packages)
Defining packages and origins (@pxref{package Reference}).
@item (guix download)
@itemx (guix git-download)
The @code{url-fetch} and @code{git-fetch} origin download methods
(@pxref{origin Reference}).
@item (guix swh)
Fetching source code from the
@uref{https://archive.softwareheritage.org,Software Heritage archive}.
@item (guix search-paths)
Implementing search paths (@pxref{Search Paths}).
@item (guix build-system)
The build system interface (@pxref{Build Systems}).
@item (guix profiles)
Implementing profiles.
@end table

@cindex build system, directory structure
@item guix/build-system
This directory contains specific build system implementations
(@pxref{Build Systems}), such as:

@table @code
@item (guix build-system gnu)
the GNU build system;
@item (guix build-system cmake)
the CMake build system;
@item (guix build-system pyproject)
The Python ``pyproject'' build system.
@end table

@item guix/build
This contains code generally used on the ``build side''
(@pxref{G-Expressions, strata of code}).  This includes code used to
build packages or other operating system components, as well as
utilities:

@table @code
@item (guix build utils)
Utilities for package definitions and more (@pxref{Build Utilities}).
@item (guix build gnu-build-system)
@itemx (guix build cmake-build-system)
@itemx (guix build pyproject-build-system)
Implementation of build systems, and in particular definition of their
build phases (@pxref{Build Phases}).
@item (guix build syscalls)
Interface to the C library and to Linux system calls.
@end table

@cindex command-line tools, as Guile modules
@cindex command modules
@item guix/scripts
This contains modules corresponding to @command{guix} sub-commands.  For
example, the @code{(guix scripts shell)} module exports the
@code{guix-shell} procedure, which directly corresponds to the
@command{guix shell} command (@pxref{Invoking guix shell}).

@cindex importer modules
@item guix/import
This contains supporting code for the importers and updaters
(@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}).  For
example, @code{(guix import pypi)} defines the interface to PyPI, which
is used by the @code{guix import pypi} command.
@end table

The directories we have seen so far all live under @file{guix/}.  The
other important place is the @file{gnu/} directory, which contains
primarily package definitions as well as libraries and tools for Guix
System (@pxref{System Configuration}) and Guix Home (@pxref{Home
Configuration}), all of which build upon functionality provided by
@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix
@dots{})} modules must generally not depend on @code{(gnu @dots{})}
modules, with notable exceptions: @code{(guix build-system @dots{})}
modules may look up packages at run time---e.g., @code{(guix
build-system cmake)} needs to access the @code{cmake} variable at run
time---, @code{(guix scripts @dots{})} often rely on @code{(gnu @dots{})}
modules, and the same goes for some of the @code{(guix import @dots{})}
modules.}.

@table @file
@cindex package modules
@item gnu/packages
This is by far the most crowded directory of the source tree: it
contains @dfn{package modules} that export package definitions
(@pxref{Package Modules}).  A few examples:

@table @code
@item (gnu packages base)
Module providing ``base'' packages: @code{glibc}, @code{coreutils},
@code{grep}, etc.
@item (gnu packages guile)
Guile and core Guile packages.
@item (gnu packages linux)
The Linux-libre kernel and related packages.
@item (gnu packages python)
Python and core Python packages.
@item (gnu packages python-xyz)
Miscellaneous Python packages (we were not very creative).
@end table

In any case, you can jump to a package definition using @command{guix
edit} (@pxref{Invoking guix edit}) and view its location with
@command{guix show} (@pxref{Invoking guix package}).

@findex search-patches
@item gnu/packages/patches
This directory contains patches applied against packages and obtained
using the @code{search-patches} procedure.

@item gnu/services
This contains service definitions, primarily for Guix System
(@pxref{Services}) but some of them are adapted and reused for Guix Home
as we will see below.  Examples:

@table @code
@item (gnu services)
The service framework itself, which defines the service and service type
data types (@pxref{Service Composition}).
@item (gnu services base)
``Base'' services (@pxref{Base Services}).
@item (gnu services desktop)
``Desktop'' services (@pxref{Desktop Services}).
@item (gnu services shepherd)
Support for Shepherd services (@pxref{Shepherd Services}).
@end table

You can jump to a service definition using @command{guix system edit}
and view its location with @command{guix system search} (@pxref{Invoking
guix system}).

@item gnu/system
These are core Guix System modules, such as:

@table @code
@item (gnu system)
Defines @code{operating-system} (@pxref{operating-system Reference}).
@item (gnu system file-systems)
Defines @code{file-system} (@pxref{File Systems}).
@item (gnu system mapped-devices)
Defines @code{mapped-device} (@pxref{Mapped Devices}).
@end table

@item gnu/build
These are modules that are either used on the ``build side'' when
building operating systems or packages, or at run time by operating
systems.

@table @code
@item (gnu build accounts)
Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User
Accounts}).
@item (gnu build activation)
Activating an operating system at boot time or reconfiguration time.
@item (gnu build file-systems)
Searching, checking, and mounting file systems.
@item (gnu build linux-boot)
@itemx (gnu build hurd-boot)
Booting GNU/Linux and GNU/Hurd operating systems.
@item (gnu build linux-initrd)
Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}).
@end table

@item gnu/home
This contains all things Guix Home (@pxref{Home Configuration});
examples:

@table @code
@item (gnu home services)
Core services such as @code{home-files-service-type}.
@item (gnu home services ssh)
SSH-related services (@pxref{Secure Shell}).
@end table

@item gnu/installer
This contains the text-mode graphical system installer (@pxref{Guided
Graphical Installation}).

@item gnu/machine
These are the @dfn{machine abstractions} used by @command{guix deploy}
(@pxref{Invoking guix deploy}).

@item gnu/tests
This contains system tests---tests that spawn virtual machines to check
that system services work as expected (@pxref{Running the Test Suite}).
@end table

Last, there's also a few directories that contain files that are
@emph{not} Guile modules:

@table @file
@item nix
This is the C++ implementation of @command{guix-daemon}, inherited from
Nix (@pxref{Invoking guix-daemon}).

@item tests
These are unit tests, each file corresponding more or less to one
module, in particular @code{(guix @dots{})} modules (@pxref{Running the
Test Suite}).

@item doc
This is the documentation in the form of Texinfo files: this manual and
the Cookbook.  @xref{Writing a Texinfo File,,, texinfo, GNU Texinfo},
for information on Texinfo markup language.

@item po
This is the location of translations of Guix itself, of package synopses
and descriptions, of the manual, and of the cookbook.  Note that
@file{.po} files that live here are pulled directly from Weblate
(@pxref{Translating Guix}).

@item etc
Miscellaneous files: shell completions, support for systemd and other
init systems, Git hooks, etc.
@end table

With all this, a fair chunk of your operating system is at your
fingertips!  Beyond @command{grep} and @command{git grep}, @pxref{The
Perfect Setup} on how to navigate code from your editor, and
@pxref{Using Guix Interactively} for information on how to use Scheme
modules interactively.  Enjoy!

@node Packaging Guidelines
@section Packaging Guidelines

@cindex packages, creating
The GNU distribution is nascent and may well lack some of your favorite
packages.  This section describes how you can help make the distribution
grow.

Free software packages are usually distributed in the form of
@dfn{source code tarballs}---typically @file{tar.gz} files that contain
all the source files.  Adding a package to the distribution means
essentially two things: adding a @dfn{recipe} that describes how to
build the package, including a list of other packages required to build
it, and adding @dfn{package metadata} along with that recipe, such as a
description and licensing information.

In Guix all this information is embodied in @dfn{package definitions}.
Package definitions provide a high-level view of the package.  They are
written using the syntax of the Scheme programming language; in fact,
for each package we define a variable bound to the package definition,
and export that variable from a module (@pxref{Package Modules}).
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
creating packages.  For more information on package definitions,
@pxref{Defining Packages}.

Once a package definition is in place, stored in a file in the Guix
source tree, it can be tested using the @command{guix build} command
(@pxref{Invoking guix build}).  For example, assuming the new package is
called @code{gnew}, you may run this command from the Guix build tree
(@pxref{Running Guix Before It Is Installed}):

@example
./pre-inst-env guix build gnew --keep-failed
@end example

Using @code{--keep-failed} makes it easier to debug build failures since
it provides access to the failed build tree.  Another useful
command-line option when debugging is @code{--log-file}, to access the
build log.

If the package is unknown to the @command{guix} command, it may be that
the source file contains a syntax error, or lacks a @code{define-public}
clause to export the package variable.  To figure it out, you may load
the module from Guile to get more information about the actual error:

@example
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
@end example

Once your package builds correctly, please send us a patch
(@pxref{Submitting Patches}).  Well, if you need help, we will be happy to
help you too.  Once the patch is committed in the Guix repository, the
new package automatically gets built on the supported platforms by
@url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}.

@cindex substituter
Users can obtain the new package definition simply by running
@command{guix pull} (@pxref{Invoking guix pull}).  When
@code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the
package automatically downloads binaries from there
(@pxref{Substitutes}).  The only place where human intervention is
needed is to review and apply the patch.


@menu
* Software Freedom::            What may go into the distribution.
* Package Naming::              What's in a name?
* Version Numbers::             When the name is not enough.
* Synopses and Descriptions::   Helping users find the right package.
* Snippets versus Phases::      Whether to use a snippet, or a build phase.
* Cyclic Module Dependencies::  Going full circle.
* Emacs Packages::              Your Elisp fix.
* Python Modules::              A touch of British comedy.
* Perl Modules::                Little pearls.
* Java Packages::               Coffee break.
* Rust Crates::                 Beware of oxidation.
* Elm Packages::                Trees of browser code
* Fonts::                       Fond of fonts.
@end menu

@node Software Freedom
@subsection Software Freedom

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex free software
The GNU operating system has been developed so that users can have
freedom in their computing.  GNU is @dfn{free software}, meaning that
users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
essential freedoms}: to run the program, to study and change the program
in source code form, to redistribute exact copies, and to distribute
modified versions.  Packages found in the GNU distribution provide only
software that conveys these four freedoms.

In addition, the GNU distribution follow the
@url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
software distribution guidelines}.  Among other things, these guidelines
reject non-free firmware, recommendations of non-free software, and
discuss ways to deal with trademarks and patents.

Some otherwise free upstream package sources contain a small and optional
subset that violates the above guidelines, for instance because this subset
is itself non-free code.  When that happens, the offending items are removed
with appropriate patches or code snippets in the @code{origin} form of the
package (@pxref{Defining Packages}).  This way, @code{guix
build --source} returns the ``freed'' source rather than the unmodified
upstream source.


@node Package Naming
@subsection Package Naming

@cindex package name
A package actually has two names associated with it.
First, there is the name of the @emph{Scheme variable}, the one following
@code{define-public}.  By this name, the package can be made known in the
Scheme code, for instance as input to another package.  Second, there is
the string in the @code{name} field of a package definition.  This name
is used by package management commands such as
@command{guix package} and @command{guix build}.

Both are usually the same and correspond to the lowercase conversion of
the project name chosen upstream, with underscores replaced with
hyphens.  For instance, GNUnet is available as @code{gnunet}, and
SDL_net as @code{sdl-net}.

A noteworthy exception to this rule is when the project name is only a
single character, or if an older maintained project with the same name
already exists---regardless of whether it has already been packaged for
Guix.  Use common sense to make such names unambiguous and meaningful.
For example, Guix's package for the shell called ``s'' upstream is
@code{s-shell} and @emph{not} @code{s}.  Feel free to ask your fellow
hackers for inspiration.

We do not add @code{lib} prefixes for library packages, unless these are
already part of the official project name.  But @pxref{Python
Modules} and @ref{Perl Modules} for special rules concerning modules for
the Python and Perl languages.

Font package names are handled differently, @pxref{Fonts}.


@node Version Numbers
@subsection Version Numbers

@cindex package version
We usually package only the latest version of a given free software
project.  But sometimes, for instance for incompatible library versions,
two (or more) versions of the same package are needed.  These require
different Scheme variable names.  We use the name as defined
in @ref{Package Naming}
for the most recent version; previous versions use the same name, suffixed
by @code{-} and the smallest prefix of the version number that may
distinguish the two versions.

The name inside the package definition is the same for all versions of a
package and does not contain any version number.

For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:

@lisp
(define-public gtk+
  (package
    (name "gtk+")
    (version "3.9.12")
    ...))
(define-public gtk+-2
  (package
    (name "gtk+")
    (version "2.24.20")
    ...))
@end lisp
If we also wanted GTK+ 3.8.2, this would be packaged as
@lisp
(define-public gtk+-3.8
  (package
    (name "gtk+")
    (version "3.8.2")
    ...))
@end lisp

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
@c for a discussion of what follows.
@cindex version number, for VCS snapshots
Occasionally, we package snapshots of upstream's version control system
(VCS) instead of formal releases.  This should remain exceptional,
because it is up to upstream developers to clarify what the stable
release is.  Yet, it is sometimes necessary.  So, what should we put in
the @code{version} field?

Clearly, we need to make the commit identifier of the VCS snapshot
visible in the version string, but we also need to make sure that the
version string is monotonically increasing so that @command{guix package
--upgrade} can determine which version is newer.  Since commit
identifiers, notably with Git, are not monotonically increasing, we add
a revision number that we increase each time we upgrade to a newer
snapshot.  The resulting version string looks like this:

@example
2.0.11-3.cabba9e
  ^    ^    ^
  |    |    `-- upstream commit ID
  |    |
  |    `--- Guix package revision
  |
latest upstream version
@end example

It is a good idea to strip commit identifiers in the @code{version}
field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
aesthetics have a role to play here) as well as problems related to OS
limits such as the maximum shebang length (127 bytes for the Linux
kernel).  There are helper functions for doing this for packages using
@code{git-fetch} or @code{hg-fetch} (see below).  It is best to use the
full commit identifiers in @code{origin}s, though, to avoid ambiguities.
A typical package definition may look like this:


@lisp
(define my-package
  (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
        (revision "1"))          ;Guix package revision
    (package
      (version (git-version "0.9" revision commit))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                      (url "git://example.org/my-package.git")
                      (commit commit)))
                (sha256 (base32 "1mbikn@dots{}"))
                (file-name (git-file-name name version))))
      ;; @dots{}
      )))
@end lisp

@deffn {Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
Return the version string for packages using @code{git-fetch}.

@lisp
(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
@result{} "0.2.3-0.93818c9"
@end lisp
@end deffn

@deffn {Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
Return the version string for packages using @code{hg-fetch}.  It works
in the same way as @code{git-version}.
@end deffn

@node Synopses and Descriptions
@subsection Synopses and Descriptions

@cindex package description
@cindex package synopsis
As we have seen before, each package in GNU@tie{}Guix includes a
synopsis and a description (@pxref{Defining Packages}).  Synopses and
descriptions are important: They are what @command{guix package
--search} searches, and a crucial piece of information to help users
determine whether a given package suits their needs.  Consequently,
packagers should pay attention to what goes into them.

Synopses must start with a capital letter and must not end with a
period.  They must not start with ``a'' or ``the'', which usually does
not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
tool that frobs files''.  The synopsis should say what the package
is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
matching a pattern''.

Keep in mind that the synopsis must be meaningful for a very wide
audience.  For example, ``Manipulate alignments in the SAM format''
might make sense for a seasoned bioinformatics researcher, but might be
fairly unhelpful or even misleading to a non-specialized audience.  It
is a good idea to come up with a synopsis that gives an idea of the
application domain of the package.  In this example, this might give
something like ``Manipulate nucleotide sequence alignments'', which
hopefully gives the user a better idea of whether this is what they are
looking for.

Descriptions should take between five and ten lines.  Use full
sentences, and avoid using acronyms without first introducing them.
Please avoid marketing phrases such as ``world-leading'',
``industrial-strength'', and ``next-generation'', and avoid superlatives
like ``the most advanced''---they are not helpful to users looking for a
package and may even sound suspicious.  Instead, try to be factual,
mentioning use cases and features.

@cindex Texinfo markup, in package descriptions
Descriptions can include Texinfo markup, which is useful to introduce
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}).  However you
should be careful when using some characters for example @samp{@@} and
curly braces which are the basic special characters in Texinfo
(@pxref{Special Characters,,, texinfo, GNU Texinfo}).  User interfaces
such as @command{guix show} take care of rendering it
appropriately.

Synopses and descriptions are translated by volunteers
@uref{https://translate.fedoraproject.org/projects/guix/packages, at
Weblate} so that as many users as possible can read them in
their native language.  User interfaces search them and display them in
the language specified by the current locale.

To allow @command{xgettext} to extract them as translatable strings,
synopses and descriptions @emph{must be literal strings}.  This means
that you cannot use @code{string-append} or @code{format} to construct
these strings:

@lisp
(package
  ;; @dots{}
  (synopsis "This is translatable")
  (description (string-append "This is " "*not*" " translatable.")))
@end lisp

Translation is a lot of work so, as a packager, please pay even more
attention to your synopses and descriptions as every change may entail
additional work for translators.  In order to help them, it is possible
to make recommendations or instructions visible to them by inserting
special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
Gettext}):

@lisp
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. @dots{}")
@end lisp

@node Snippets versus Phases
@subsection Snippets versus Phases

@cindex snippets, when to use
The boundary between using an origin snippet versus a build phase to
modify the sources of a package can be elusive.  Origin snippets are
typically used to remove unwanted files such as bundled libraries,
nonfree sources, or to apply simple substitutions.  The source derived
from an origin should produce a source that can be used to build the
package on any system that the upstream package supports (i.e., act as
the corresponding source).  In particular, origin snippets must not
embed store items in the sources; such patching should rather be done
using build phases.  Refer to the @code{origin} record documentation for
more information (@pxref{origin Reference}).

@node Cyclic Module Dependencies
@subsection Cyclic Module Dependencies

While there cannot be circular dependencies between packages, Guile's
lax module loading mechanism allows circular dependencies between Guile
modules, which doesn't cause problems as long as the following
conditions are followed for two modules part of a dependency cycle:

@cindex rules to cope with circular module dependencies
@enumerate
@item
Macros are not shared between the co-dependent modules
@item
Top-level variables are only referenced in delayed (@i{thunked}) package
fields: @code{arguments}, @code{native-inputs}, @code{inputs},
@code{propagated-inputs} or @code{replacement}
@item
Procedures referencing top-level variables from another module are not
called at the top level of a module themselves.
@end enumerate

Straying away from the above rules may work while there are no
dependency cycles between modules, but given such cycles are confusing
and difficult to troubleshoot, it is best to follow the rules to avoid
introducing problems down the line.

@noindent
Here is a common trap to avoid:

@lisp
(define-public avr-binutils
  (package
    (inherit (cross-binutils "avr"))
    (name "avr-binutils")))
@end lisp

In the above example, the @code{avr-binutils} package was defined in the
module @code{(gnu packages avr)}, and the @code{cross-binutils}
procedure in @code{(gnu packages cross-base)}.  Because the
@code{inherit} field is not delayed (thunked), it is evaluated at the
top level at load time, which is problematic in the presence of module
dependency cycles.  This could be resolved by turning the package into a
procedure instead, like:

@lisp
(define (make-avr-binutils)
  (package
    (inherit (cross-binutils "avr"))
    (name "avr-binutils")))
@end lisp

Care would need to be taken to ensure the above procedure is only ever
used in a package delayed fields or within another procedure also not
called at the top level.

@node Emacs Packages
@subsection Emacs Packages

@cindex emacs, packaging
@cindex elisp, packaging
Emacs packages should preferably use the Emacs build system
(@pxref{emacs-build-system}), for uniformity and the benefits provided
by its build phases, such as the auto-generation of the autoloads file
and the byte compilation of the sources.  Because there is no
standardized way to run a test suite for Emacs packages, tests are
disabled by default.  When a test suite is available, it should be
enabled by setting the @code{#:tests?} argument to @code{#true}.  By
default, the command to run the test is @command{make check}, but any
command can be specified via the @code{#:test-command} argument.  The
@code{#:test-command} argument expects a list containing a command and
its arguments, to be invoked during the @code{check} phase.

The Elisp dependencies of Emacs packages are typically provided as
@code{propagated-inputs} when required at run time.  As for other
packages, build or test dependencies should be specified as
@code{native-inputs}.

Emacs packages sometimes depend on resources directories that should be
installed along the Elisp files.  The @code{#:include} argument can be
used for that purpose, by specifying a list of regexps to match.  The
best practice when using the @code{#:include} argument is to extend
rather than override its default value (accessible via the
@code{%default-include} variable).  As an example, a yasnippet extension
package typically include a @file{snippets} directory, which could be
copied to the installation directory using:

@lisp
#:include (cons "^snippets/" %default-include)
@end lisp

When encountering problems, it is wise to check for the presence of the
@code{Package-Requires} extension header in the package main source
file, and whether any dependencies and their versions listed therein are
satisfied.

@node Python Modules
@subsection Python Modules

@cindex python
We currently package Python 2 and Python 3, under the Scheme variable names
@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
To avoid confusion and naming clashes with other programming languages, it
seems desirable that the name of a package for a Python module contains
the word @code{python}.

Some modules are compatible with only one version of Python, others with
both.  If the package Foo is compiled with Python 3, we name it
@code{python-foo}.  If it is compiled with Python 2, we name it
@code{python2-foo}.  Python 2 packages are being removed from the
distribution; please do no not submit any new Python 2 packages.

If a project already contains the word @code{python}, we drop this;
for instance, the module python-dateutil is packaged under the names
@code{python-dateutil} and @code{python2-dateutil}.  If the project name
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
described above.

@quotation Note
Currently there are two different build systems for Python packages in Guix:
@var{python-build-system} and @var{pyproject-build-system}.  For the
longest time, Python packages were built from an informally specified
@file{setup.py} file.  That worked amazingly well, considering Python's
success, but was difficult to build tooling around.  As a result, a host
of alternative build systems emerged and the community eventually settled on a
@url{https://peps.python.org/pep-0517/, formal standard} for specifying build
requirements.  @var{pyproject-build-system} is Guix's implementation of this
standard.  It is considered ``experimental'' in that it does not yet support
all the various PEP-517 @emph{build backends}, but you are encouraged to try
it for new Python packages and report any problems.  It will eventually be
deprecated and merged into @var{python-build-system}.
@end quotation

@subsubsection Specifying Dependencies
@cindex inputs, for Python packages

Dependency information for Python packages is usually available in the
package source tree, with varying degrees of accuracy: in the
@file{pyproject.toml} file, the @file{setup.py} file, in
@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
test dependencies).

Your mission, when writing a recipe for a Python package, is to map
these dependencies to the appropriate type of ``input'' (@pxref{package
Reference, inputs}).  Although the @code{pypi} importer normally does a
good job (@pxref{Invoking guix import}), you may want to check the
following check list to determine which dependency goes where.

@itemize

@item
We currently package Python with @code{setuptools} and @code{pip}
installed per default.  This is about to change, and users are encouraged
to use @code{python-toolchain} if they want a build environment for Python.

@command{guix lint} will warn if @code{setuptools} or @code{pip} are
added as native-inputs because they are generally not necessary.

@item
Python dependencies required at run time go into
@code{propagated-inputs}.  They are typically defined with the
@code{install_requires} keyword in @file{setup.py}, or in the
@file{requirements.txt} file.

@item
Python packages required only at build time---e.g., those listed under
@code{build-system.requires} in @file{pyproject.toml} or with the
@code{setup_requires} keyword in @file{setup.py}---or dependencies only
for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
@code{native-inputs}.  The rationale is that (1) they do not need to be
propagated because they are not needed at run time, and (2) in a
cross-compilation context, it's the ``native'' input that we'd want.

Examples are the @code{pytest}, @code{mock}, and @code{nose} test
frameworks.  Of course if any of these packages is also required at
run-time, it needs to go to @code{propagated-inputs}.

@item
Anything that does not fall in the previous categories goes to
@code{inputs}, for example programs or C libraries required for building
Python packages containing C extensions.

@item
If a Python package has optional dependencies (@code{extras_require}),
it is up to you to decide whether to add them or not, based on their
usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
size}}).

@end itemize


@node Perl Modules
@subsection Perl Modules

@cindex perl
Perl programs standing for themselves are named as any other package,
using the lowercase upstream name.
For Perl packages containing a single class, we use the lowercase class name,
replace all occurrences of @code{::} by dashes and prepend the prefix
@code{perl-}.
So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
Modules containing several classes keep their lowercase upstream name and
are also prepended by @code{perl-}.  Such modules tend to have the word
@code{perl} somewhere in their name, which gets dropped in favor of the
prefix.  For instance, @code{libwww-perl} becomes @code{perl-libwww}.


@node Java Packages
@subsection Java Packages

@cindex java
Java programs standing for themselves are named as any other package,
using the lowercase upstream name.

To avoid confusion and naming clashes with other programming languages,
it is desirable that the name of a package for a Java package is
prefixed with @code{java-}.  If a project already contains the word
@code{java}, we drop this; for instance, the package @code{ngsjava} is
packaged under the name @code{java-ngs}.

For Java packages containing a single class or a small class hierarchy,
we use the lowercase class name, replace all occurrences of @code{.} by
dashes and prepend the prefix @code{java-}.  So the class
@code{apache.commons.cli} becomes package
@code{java-apache-commons-cli}.


@node Rust Crates
@subsection Rust Crates

@cindex rust
Rust programs standing for themselves are named as any other package, using the
lowercase upstream name.

To prevent namespace collisions we prefix all other Rust packages with the
@code{rust-} prefix.  The name should be changed to lowercase as appropriate and
dashes should remain in place.

In the rust ecosystem it is common for multiple incompatible versions of a
package to be used at any given time, so all package definitions should have a
versioned suffix.  The versioned suffix is the left-most non-zero digit (and
any leading zeros, of course).  This follows the ``caret'' version scheme
intended by Cargo.  Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.

Because of the difficulty in reusing rust packages as pre-compiled inputs for
other packages the Cargo build system (@pxref{Build Systems,
@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
@code{cargo-development-inputs} keywords as build system arguments.  It would be
helpful to think of these as similar to @code{propagated-inputs} and
@code{native-inputs}.  Rust @code{dependencies} and @code{build-dependencies}
should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
@code{#:cargo-development-inputs}.  If a Rust package links to other libraries
then the standard placement in @code{inputs} and the like should be used.

Care should be taken to ensure the correct version of dependencies are used; to
this end we try to refrain from skipping the tests or using @code{#:skip-build?}
when possible.  Of course this is not always possible, as the package may be
developed for a different Operating System, depend on features from the Nightly
Rust compiler, or the test suite may have atrophied since it was released.


@node Elm Packages
@subsection Elm Packages

@cindex Elm
Elm applications can be named like other software: their names need not
mention Elm.

Packages in the Elm sense (see @code{elm-build-system} under @ref{Build
Systems}) are required use names of the format
@var{author}@code{/}@var{project}, where both the @var{author} and the
@var{project} may contain hyphens internally, and the @var{author} sometimes
contains uppercase letters.

To form the Guix package name from the upstream name, we follow a convention
similar to Python packages (@pxref{Python Modules}), adding an @code{elm-}
prefix unless the name would already begin with @code{elm-}.

In many cases we can reconstruct an Elm package's upstream name heuristically,
but, since conversion to a Guix-style name involves a loss of information,
this is not always possible.  Care should be taken to add the
@code{'upstream-name} property when necessary so that @samp{guix import elm}
will work correctly (@pxref{Invoking guix import}). The most notable scenarios
when explicitly specifying the upstream name is necessary are:

@enumerate
@item
When the @var{author} is @code{elm} and the @var{project} contains one or more
hyphens, as with @code{elm/virtual-dom}; and

@item
When the @var{author} contains hyphens or uppercase letters, as with
@code{Elm-Canvas/raster-shapes}---unless the @var{author} is
@code{elm-explorations}, which is handled as a special case, so packages like
@code{elm-explorations/markdown} do @emph{not} need to use the
@code{'upstream-name} property.
@end enumerate

The module @code{(guix build-system elm)} provides the following utilities for
working with names and related conventions:

@deffn {Procedure} elm-package-origin @var{elm-name} @var{version} @
  @var{hash}
Returns a Git origin using the repository naming and tagging regime required
for a published Elm package with the upstream name @var{elm-name} at version
@var{version} with sha256 checksum @var{hash}.

For example:
@lisp
(package
  (name "elm-html")
  (version "1.0.0")
  (source
   (elm-package-origin
    "elm/html"
    version
    (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
  ...)
@end lisp
@end deffn

@deffn {Procedure} elm->package-name @var{elm-name}
Returns the Guix-style package name for an Elm package with upstream name
@var{elm-name}.

Note that there is more than one possible @var{elm-name} for which
@code{elm->package-name} will produce a given result.
@end deffn

@deffn {Procedure} guix-package->elm-name @var{package}
Given an Elm @var{package}, returns the possibly-inferred upstream name, or
@code{#f} the upstream name is not specified via the @code{'upstream-name}
property and can not be inferred by @code{infer-elm-package-name}.
@end deffn

@deffn {Procedure} infer-elm-package-name @var{guix-name}
Given the @var{guix-name} of an Elm package, returns the inferred upstream
name, or @code{#f} if the upstream name can't be inferred.  If the result is
not @code{#f}, supplying it to @code{elm->package-name} would produce
@var{guix-name}.
@end deffn

@node Fonts
@subsection Fonts

@cindex fonts
For fonts that are in general not installed by a user for typesetting
purposes, or that are distributed as part of a larger software package,
we rely on the general packaging rules for software; for instance, this
applies to the fonts delivered as part of the X.Org system or fonts that
are part of TeX Live.

To make it easier for a user to search for fonts, names for other packages
containing only fonts are constructed as follows, independently of the
upstream package name.

The name of a package containing only one font family starts with
@code{font-}; it is followed by the foundry name and a dash @code{-}
if the foundry is known, and the font family name, in which spaces are
replaced by dashes (and as usual, all upper case letters are transformed
to lower case).
For example, the Gentium font family by SIL is packaged under the name
@code{font-sil-gentium}.

For a package containing several font families, the name of the collection
is used in the place of the font family name.
For instance, the Liberation fonts consist of three families,
Liberation Sans, Liberation Serif and Liberation Mono.
These could be packaged separately under the names
@code{font-liberation-sans} and so on; but as they are distributed together
under a common name, we prefer to package them together as
@code{font-liberation}.

In the case where several formats of the same font family or font collection
are packaged separately, a short form of the format, prepended by a dash,
is added to the package name.  We use @code{-ttf} for TrueType fonts,
@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
fonts.


@node Coding Style
@section Coding Style

In general our code follows the GNU Coding Standards (@pxref{Top,,,
standards, GNU Coding Standards}).  However, they do not say much about
Scheme, so here are some additional rules.

@menu
* Programming Paradigm::        How to compose your elements.
* Modules::                     Where to store your code?
* Data Types and Pattern Matching::  Implementing data structures.
* Formatting Code::             Writing conventions.
@end menu

@node Programming Paradigm
@subsection Programming Paradigm

Scheme code in Guix is written in a purely functional style.  One
exception is code that involves input/output, and procedures that
implement low-level concepts, such as the @code{memoize} procedure.

@node Modules
@subsection Modules
@cindex build-side modules
@cindex host-side modules
Guile modules that are meant to be used on the builder side must live in
the @code{(guix build @dots{})} name space.  They must not refer to
other Guix or GNU modules.  However, it is OK for a ``host-side'' module
to use a build-side module.  As an example, the @code{(guix
search-paths)} module should not be imported and used by a package since
it isn't meant to be used as a ``build-side'' module.  It would also
couple the module with the package's dependency graph, which is
undesirable.

Modules that deal with the broader GNU system should be in the
@code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.

@node Data Types and Pattern Matching
@subsection Data Types and Pattern Matching

The tendency in classical Lisp is to use lists to represent everything,
and then to browse them ``by hand'' using @code{car}, @code{cdr},
@code{cadr}, and co.  There are several problems with that style,
notably the fact that it is hard to read, error-prone, and a hindrance
to proper type error reports.

@findex define-record-type*
@findex match-record
@cindex pattern matching
Guix code should define appropriate data types (for instance, using
@code{define-record-type*}) rather than abuse lists.  In addition, it
should use pattern matching, via Guile’s @code{(ice-9 match)} module,
especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
Guile Reference Manual}); pattern matching for records is better done
using @code{match-record} from @code{(guix records)}, which, unlike
@code{match}, verifies field names at macro-expansion time.

When defining a new record type, keep the @dfn{record type descriptor}
(RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for
more on records and RTDs).  As an example, the @code{(guix packages)}
module defines @code{<package>} as the RTD for package records but it
does not export it; instead, it exports a type predicate, a constructor,
and field accessors.  Exporting RTDs would make it harder to change the
application binary interface (because code in other modules might be
matching fields by position) and would make it trivial for users to
forge records of that type, bypassing any checks we may have in the
official constructor (such as ``field sanitizers'').

@node Formatting Code
@subsection Formatting Code

@cindex formatting code
@cindex coding style
When writing Scheme code, we follow common wisdom among Scheme
programmers.  In general, we follow the
@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
Style Rules}.  This document happens to describe the conventions mostly
used in Guile’s code too.  It is very thoughtful and well written, so
please do read it.

Some special forms introduced in Guix, such as the @code{substitute*}
macro, have special indentation rules.  These are defined in the
@file{.dir-locals.el} file, which Emacs automatically uses.  Also note
that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
highlights Guix code properly (@pxref{Development,,, emacs-guix, The
Emacs-Guix Reference Manual}).

@cindex indentation, of code
@cindex formatting, of code
If you do not use Emacs, please make sure to let your editor knows these
rules.  To automatically indent a package definition, you can also run:

@example
./pre-inst-env guix style @var{package}
@end example

@noindent
@xref{Invoking guix style}, for more information.

We require all top-level procedures to carry a docstring.  This
requirement can be relaxed for simple private procedures in the
@code{(guix build @dots{})} name space, though.

Procedures should not have more than four positional parameters.  Use
keyword parameters for procedures that take more than four parameters.


@node Submitting Patches
@section Submitting Patches

Development is done using the Git distributed version control system.
Thus, access to the repository is not strictly necessary.  We welcome
contributions in the form of patches as produced by @code{git
format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
(@pxref{Submitting patches to a project,,, git, Git User Manual}).
Contributors are encouraged to take a moment to set some Git repository
options (@pxref{Configuring Git}) first, which can improve the
readability of patches.  Seasoned Guix developers may also want to look
at the section on commit access (@pxref{Commit Access}).

This mailing list is backed by a Debbugs instance, which allows us to
keep track of submissions (@pxref{Tracking Bugs and Changes}).
Each message sent to that mailing list gets a new tracking number
assigned; people can then follow up on the submission by sending email
to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
is the tracking number (@pxref{Sending a Patch Series}).

Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
standards, GNU Coding Standards}); you can check the commit history for
examples.

You can help make the review process more efficient, and increase the
chance that your patch will be reviewed quickly, by describing the
context of your patch and the impact you expect it to have.  For
example, if your patch is fixing something that is broken, describe the
problem and how your patch fixes it.  Tell us how you have tested your
patch.  Will users of the code changed by your patch have to adjust
their workflow at all?  If so, tell us how.  In general, try to imagine
what questions a reviewer will ask, and answer those questions in
advance.

Before submitting a patch that adds or modifies a package definition,
please run through this check list:

@enumerate
@item
If the authors of the packaged software provide a cryptographic
signature for the release tarball, make an effort to verify the
authenticity of the archive.  For a detached GPG signature file this
would be done with the @code{gpg --verify} command.

@item
Take some time to provide an adequate synopsis and description for the
package.  @xref{Synopses and Descriptions}, for some guidelines.

@item
Run @code{guix lint @var{package}}, where @var{package} is the
name of the new or modified package, and fix any errors it reports
(@pxref{Invoking guix lint}).

@item
Run @code{guix style @var{package}} to format the new package definition
according to the project's conventions (@pxref{Invoking guix style}).

@item
Make sure the package builds on your platform, using @code{guix build
@var{package}}.

@item
We recommend you also try building the package on other supported
platforms.  As you may not have access to actual hardware platforms, we
recommend using the @code{qemu-binfmt-service-type} to emulate them.  In
order to enable it, add the @code{virtualization} service module and the
following service to the list of services in your @code{operating-system}
configuration:

@lisp
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
@end lisp

Then reconfigure your system.

You can then build packages for different platforms by specifying the
@code{--system} option.  For example, to build the "hello" package for
the armhf or aarch64 architectures, you would run the following
commands, respectively:
@example
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
@end example

@item
@cindex bundling
Make sure the package does not use bundled copies of software already
available as separate packages.

Sometimes, packages include copies of the source code of their
dependencies as a convenience for users.  However, as a distribution, we
want to make sure that such packages end up using the copy we already
have in the distribution, if there is one.  This improves resource usage
(the dependency is built and stored only once), and allows the
distribution to make transverse changes such as applying security
updates for a given software package in a single place and have them
affect the whole system---something that bundled copies prevent.

@item
Take a look at the profile reported by @command{guix size}
(@pxref{Invoking guix size}).  This will allow you to notice references
to other packages unwillingly retained.  It may also help determine
whether to split the package (@pxref{Packages with Multiple Outputs}),
and which optional dependencies should be used.  In particular, avoid
adding @code{texlive} as a dependency: because of its extreme size, use
@code{texlive-updmap.cfg} procedure instead.

@item
Check that dependent packages (if applicable) are not affected by the
change; @code{guix refresh --list-dependent @var{package}} will help you
do that (@pxref{Invoking guix refresh}).

@item
@cindex determinism, of build processes
@cindex reproducible builds, checking
Check whether the package's build process is deterministic.  This
typically means checking whether an independent build of the package
yields the exact same result that you obtained, bit for bit.

A simple way to do that is by building the same package several times in
a row on your machine (@pxref{Invoking guix build}):

@example
guix build --rounds=2 my-package
@end example

This is enough to catch a class of common non-determinism issues, such
as timestamps or randomly-generated output in the build result.

Another option is to use @command{guix challenge} (@pxref{Invoking guix
challenge}).  You may run it once the package has been committed and
built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
result as you did.  Better yet: Find another machine that can build it
and run @command{guix publish}.  Since the remote build machine is
likely different from yours, this can catch non-determinism issues
related to the hardware---e.g., use of different instruction set
extensions---or to the operating system kernel---e.g., reliance on
@code{uname} or @file{/proc} files.

@item
When writing documentation, please use gender-neutral wording when
referring to people, such as
@uref{https://en.wikipedia.org/wiki/Singular_they, singular
``they''@comma{} ``their''@comma{} ``them''}, and so forth.

@item
Verify that your patch contains only one set of related changes.
Bundling unrelated changes together makes reviewing harder and slower.

Examples of unrelated changes include the addition of several packages,
or a package update along with fixes to that package.

@item
Please follow our code formatting rules, possibly running
@command{guix style} script to do that automatically for you
(@pxref{Formatting Code}).

@item
When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
Use reliable URLs, not generated ones.  For instance, GitHub archives are not
necessarily identical from one generation to the next, so in this case it's
often better to clone the repository.  Don't use the @command{name} field in
the URL: it is not very useful and if the name changes, the URL will probably
be wrong.

@item
Check if Guix builds (@pxref{Building from Git}) and address the
warnings, especially those about use of undefined symbols.

@item
Make sure your changes do not break Guix and simulate a @code{guix pull} with:
@example
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
@end example

@end enumerate

When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
a subject, if your patch is to be applied on a branch other than
@code{master}, say @code{core-updates}, specify it in the subject like
@samp{[PATCH core-updates] @dots{}}.

You may use your email client, the @command{git send-email} command
(@pxref{Sending a Patch Series}) or the @command{mumi send-email}
command (@pxref{Debbugs User Interfaces}).  We prefer to get patches in
plain text messages, either inline or as MIME attachments.  You are
advised to pay attention if your email client changes anything like line
breaks or indentation which could potentially break the patches.

Expect some delay when you submit your very first patch to
@email{guix-patches@@gnu.org}. You have to wait until you get an
acknowledgement with the assigned tracking number. Future acknowledgements
should not be delayed.

When a bug is resolved, please close the thread by sending an email to
@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.

@menu
* Configuring Git::
* Sending a Patch Series::
* Teams::
@end menu

@node Configuring Git
@subsection Configuring Git
@cindex git configuration
@cindex @code{git format-patch}
@cindex @code{git send-email}

If you have not done so already, you may wish to set a name and email
that will be associated with your commits (@pxref{telling git your name,
, Telling Git your name, git, Git User Manual}).  If you wish to use a
different name or email just for commits in this repository, you can
use @command{git config --local}, or edit @file{.git/config} in the
repository instead of @file{~/.gitconfig}.

@cindex commit-msg hook
Other important Git configuration will automatically be configured when
building the project (@pxref{Building from Git}).  A
@file{.git/hooks/commit-msg} hook will be installed that embeds
@samp{Change-Id} Git @emph{trailers} in your commit messages for
traceability purposes.  It is important to preserve these when editing
your commit messages, particularly if a first version of your proposed
changes was already submitted for review.  If you have a
@file{commit-msg} hook of your own you would like to use with Guix, you
can place it under the @file{.git/hooks/commit-msg.d/} directory.

@node Sending a Patch Series
@subsection Sending a Patch Series
@cindex patch series
@cindex @code{git send-email}
@cindex @code{git format-patch}

@unnumberedsubsubsec Single Patches
@anchor{Single Patches}
The @command{git send-email} command is the best way to send both single
patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
list.  Sending patches as email attachments may make them difficult to
review in some mail clients, and @command{git diff} does not store commit
metadata.

@quotation Note
The @command{git send-email} command is provided by the @code{send-email}
output of the @code{git} package, i.e. @code{git:send-email}.
@end quotation

The following command will create a patch email from the latest commit,
open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
the Guix mailing list to be reviewed and merged.  Assuming you have
already configured Git according to @xref{Configuring Git}, you can
simply use:

@example
$ git send-email --annotate -1
@end example

@quotation Tip
To add a prefix to the subject of your patch, you may use the
@option{--subject-prefix} option.  The Guix project uses this to
specify that the patch is intended for a branch or repository
other than the @code{master} branch of
@url{https://git.savannah.gnu.org/cgit/guix.git}.

@example
git send-email --annotate --subject-prefix='PATCH core-updates' -1
@end example
@end quotation

The patch email contains a three-dash separator line after the commit
message.  You may ``annotate'' the patch with explanatory text by adding
it under this line.  If you do not wish to annotate the email, you may
drop the @option{--annotate} option.

If you need to send a revised patch, don't resend it like this or send
a ``fix'' patch to be applied on top of the last one; instead, use
@command{git commit --amend} or @url{https://git-rebase.io,
@command{git rebase}} to modify the commit, and use the
@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
flag with @command{git send-email}.

@example
$ git commit --amend
$ git send-email --annotate -v@var{REVISION} \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
@end example

@quotation Note
Due to an apparent bug in @command{git send-email},
@option{-v @var{REVISION}} (with the space) will not work; you
@emph{must} use @option{-v@var{REVISION}}.
@end quotation

You can find out @var{ISSUE_NUMBER} either by searching on the mumi
interface at @url{https://issues.guix.gnu.org} for the name of your patch or
reading the acknowledgement email sent automatically by Debbugs in
reply to incoming bugs and patches, which contains the bug number.

@unnumberedsubsubsec Notifying Teams
@anchor{Notifying Teams}
@cindex teams
If your git checkout has been correctly configured (@pxref{Configuring
Git}), the @command{git send-email} command will automatically notify
the appropriate team members, based on the scope of your changes.  This
relies on the @file{etc/teams.scm} script, which can also be invoked
manually if you do not use the preferred @command{git send-email}
command to submit patches.  To list the available actions of the script,
you can invoke it via the @command{etc/teams.scm help} command.  For
more information regarding teams, @pxref{Teams}.

@quotation Note
On foreign distros, you might have to use @command{./pre-inst-env git
send-email} for @file{etc/teams.scm} to work.
@end quotation

@unnumberedsubsubsec Multiple Patches
@anchor{Multiple Patches}
@cindex cover letter
While @command{git send-email} alone will suffice for a single
patch, an unfortunate flaw in Debbugs means you need to be more
careful when sending multiple patches: if you send them all to the
@email{guix-patches@@gnu.org} address, a new issue will be created
for each patch!

When sending a series of patches, it's best to send a Git ``cover
letter'' first, to give reviewers an overview of the patch series.
We can create a directory called @file{outgoing} containing both
our patch series and a cover letter called @file{0000-cover-letter.patch}
with @command{git format-patch}.

@example
$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
      --cover-letter --base=auto
@end example

We can now send @emph{just} the cover letter to the
@email{guix-patches@@gnu.org} address, which will create an issue
that we can send the rest of the patches to.

@example
$ git send-email outgoing/0000-cover-letter.patch --annotate
$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
@end example

Ensure you edit the email to add an appropriate subject line and
blurb before sending it.  Note the automatically generated shortlog
and diffstat below the blurb.

Once the Debbugs mailer has replied to your cover letter email, you
can send the actual patches to the newly-created issue address.

@example
$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
$ rm -rf outgoing # we don't need these anymore
@end example

Thankfully, this @command{git format-patch} dance is not necessary
to send an amended patch series, since an issue already exists for
the patchset.

@example
$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
@end example

If need be, you may use @option{--cover-letter --annotate} to send
another cover letter, e.g. for explaining what's changed since the last
revision, and these changes are necessary.

@node Teams
@subsection Teams
@cindex teams

To organize work on Guix, including but not just development efforts,
the project has a set of @dfn{teams}.  Each team has its own focus and
interests and is the primary contact point for questions and
contributions in those areas.  A team's primary mission is to coordinate
and review the work of individuals in its scope (@pxref{Reviewing the
Work of Others}); it can make decisions within its scope, in agreement
with other teams whenever there is overlap or a close connection, and in
accordance with other project rules such as seeking consensus.
@c TODO: Currently ``consensus-based decision making'' is discussed
@c under ``Commit Access''.  Move that elsewhere and refer to it from
@c here.

As an example, the Python team is responsible for core Python packaging
matters; it can decide to upgrade core Python packages in a dedicated
@code{python-team} branch, in collaboration with any team whose scope is
directly dependent on Python---e.g., the Science team---and following
branching rules (@pxref{Managing Patches and Branches}).  The
Documentation team helps review changes to the documentation and can
initiate overarching documentation changes.  The Translations team
organizes translation of Guix and its manual and coordinates efforts in
that area.  The Core team is responsible for the development of core
functionality and interfaces of Guix; because of its central nature,
some of its work may require soliciting input from the community at
large and seeking consensus before enacting decisions that would affect
the entire community.

Teams are defined in the @file{etc/teams.scm} file in the Guix
repository.  The scope of each team is defined, when applicable, as a
set of files or as a regular expression matching file names.

@cindex team membership
Anyone with interest in a team's domain and willing to contribute to its
work can apply to become a member by contacting current members by
email; commit access is not a precondition.  Membership is formalized by
adding the person's name and email address to @file{etc/teams.scm}.
Members who have not been participating in the team's work for one year
or more may be removed; they are free to reapply for membership later.

@cindex team creation
One or more people may propose the creation of a new team by reaching
out to the community by email at @email{guix-devel@@gnu.org}, clarifying
the intended scope and purpose.  When consensus is reached on the
creation of this team, someone with commit access formalizes its
creation by adding it and its initial members to @file{etc/teams.scm}.

To list existing teams, run the following command from a Guix checkout:

@example
$ ./etc/teams.scm list-teams
id: mentors
name: Mentors
description: A group of mentors who chaperone contributions by newcomers.
members:
+ Charlie Smith <charlie@@example.org>
@dots{}
@end example

@cindex mentoring
You can run the following command to have the Mentors team put in
CC of a patch series:

@example
$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
  --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
@end example

The appropriate team or teams can also be inferred from the modified
files.  For instance, if you want to send the two latest commits of the
current Git repository to review, you can run:

@example
$ guix shell -D guix
[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
@end example

@node Tracking Bugs and Changes
@section Tracking Bugs and Changes

This section describes how the Guix project tracks its bug reports,
patch submissions and topic branches.

@menu
* The Issue Tracker::           The official bug and patch tracker.
* Managing Patches and Branches::  How changes to Guix are managed.
* Debbugs User Interfaces::     Ways to interact with Debbugs.
* Debbugs Usertags::            Tag reports with custom labels.
* Cuirass Build Notifications::  Be alerted of any breakage via RSS feeds.
@end menu

@node The Issue Tracker
@subsection The Issue Tracker

@cindex bug reports, tracking
@cindex patch submissions, tracking
@cindex issue tracking
@cindex Debbugs, issue tracking system
Bug reports and patch submissions are currently tracked using the
Debbugs instance at @uref{https://bugs.gnu.org}.  Bug reports are filed
against the @code{guix} ``package'' (in Debbugs parlance), by sending
email to @email{bug-guix@@gnu.org}, while patch submissions are filed
against the @code{guix-patches} package by sending email to
@email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).

@node Managing Patches and Branches
@subsection Managing Patches and Branches
@cindex branching strategy
@cindex rebuild scheduling strategy

Changes should be posted to @email{guix-patches@@gnu.org}.  This mailing
list fills the patch-tracking database (@pxref{The Issue Tracker}).  It
also allows patches to be picked up and tested by the quality assurance
tooling; the result of that testing eventually shows up on the dashboard
at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where
@var{ISSUE_NUMBER} is the number assigned by the issue tracker.  Leave
time for a review, without committing anything.

As an exception, some changes considered ``trivial'' or ``obvious'' may
be pushed directly to the @code{master} branch.  This includes changes
to fix typos and reverting commits that caused immediate problems.  This
is subject to being adjusted, allowing individuals to commit directly on
non-controversial changes on parts they’re familiar with.

Changes which affect more than 300 dependent packages (@pxref{Invoking
guix refresh}) should first be pushed to a topic branch other than
@code{master}; the set of changes should be consistent---e.g., ``GNOME
update'', ``NumPy update'', etc.  This allows for testing: the branch
will automatically show up at
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an
indication of its build status on various platforms.

@cindex feature branches, coordination
To help coordinate the merging of branches, you must create a new
guix-patches issue each time you create a branch (@pxref{The Issue
Tracker}).  The title of the issue requesting to merge a branch should
have the following format:

@cindex merge requests, template
@example
Request for merging "@var{name}" branch
@end example

The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
issues and lists the merge requests on its main page.  The following
points apply to managing these branches:

@enumerate
@item
The commits on the branch should be a combination of the patches
relevant to the branch.  Patches not related to the topic of the branch
should go elsewhere.

@item
Any changes that can be made on the master branch, should be made on the
master branch.  If a commit can be split to apply part of the changes on
master, this is good to do.

@item
It should be possible to re-create the branch by starting from master
and applying the relevant patches.

@item
Avoid merging master in to the branch.  Prefer rebasing or re-creating
the branch on top of an updated master revision.

@item
Minimise the changes on master that are missing on the branch prior to
merging the branch in to master.  This means that the state of the
branch better reflects the state of master should the branch be merged.

@item
If you don't have commit access, create the ``Request for merging''
issue and request that someone creates the branch.  Include a list of
issues/patches to include on the branch.
@end enumerate

Normally branches will be merged in a ``first come, first merged''
manner, tracked through the guix-patches issues.  If you agree on a
different order with those involved, you can track this by updating
which issues block@footnote{You can mark an issue as blocked by another
by emailing @email{control@@debbugs.gnu.org} with the following line in
the body of the email: @code{block XXXXX by YYYYY}.  Where @code{XXXXX}
is the number for the blocked issue, and @code{YYYYY} is the number for
the issue blocking it.} which other issues.  Therefore, to know which
branch is at the front of the queue, look for the oldest issue, or the
issue that isn't @dfn{blocked} by any other branch merges.  An ordered
list of branches with the open issues is available at
@url{https://qa.guix.gnu.org}.

Once a branch is at the front of the queue, wait until sufficient time
has passed for the build farms to have processed the changes, and for
the necessary testing to have happened.  For example, you can check
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
information on some builds and substitute availability.

Once the branch has been merged, the issue should be closed and the
branch deleted.

@node Debbugs User Interfaces
@subsection Debbugs User Interfaces

@subsubsection Web interface

@cindex mumi, web interface for issues
A web interface (actually @emph{two} web interfaces!) are available to
browse issues:

@itemize
@item
@url{https://issues.guix.gnu.org} provides a pleasant interface powered
by mumi@footnote{Mumi is a nice piece of software written in Guile, and
you can help!  See
@url{https://git.savannah.gnu.org/cgit/guix/mumi.git}.} to browse bug
reports and patches, and to participate in discussions; mumi also has a
command-line interface as we will see below;
@item
@url{https://bugs.gnu.org/guix} lists bug reports;
@item
@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
@end itemize

To view discussions related to issue number @var{n}, go to
@indicateurl{https://issues.guix.gnu.org/@var{n}} or
@indicateurl{https://bugs.gnu.org/@var{n}}.

@subsubsection Command-Line Interface

@cindex mumi command-line interface
@cindex mumi am
@cindex mumi compose
@cindex mumi send-email
@cindex mumi www
Mumi also comes with a command-line interface that can be used to search
existing issues, open new issues, compose replies, apply and send
patches.  You do not need to use Emacs to use the mumi command-line
client.  You interact with it only on the command-line.

To use the mumi command-line interface, navigate to a local clone of the
Guix git repository, and drop into a shell with mumi, git and
git:send-email installed.

@example
$ cd guix
~/guix$ guix shell mumi git git:send-email
@end example

To search for issues, say all open issues about "zig", run

@example
~/guix [env]$ mumi search zig is:open

#60889 Add zig-build-system
opened on 17 Jan 17:37 Z by Ekaitz Zarraga
#61036 [PATCH 0/3] Update zig to 0.10.1
opened on 24 Jan 09:42 Z by Efraim Flashner
#39136 [PATCH] gnu: services: Add endlessh.
opened on 14 Jan 2020 21:21 by Nicol? Balzarotti
#60424 [PATCH] gnu: Add python-online-judge-tools
opened on 30 Dec 2022 07:03 by gemmaro
#45601 [PATCH 0/6] vlang 0.2 update
opened on  1 Jan 2021 19:23 by Ryan Prior
@end example

Pick an issue and make it the "current" issue.

@example
~/guix [env]$ mumi current 61036

#61036 [PATCH 0/3] Update zig to 0.10.1
opened on 24 Jan 09:42 Z by Efraim Flashner
@end example

Once an issue is the current issue, you can open the issue in a web
browser, compose replies, apply patches, send patches, etc. with short
succinct commands.

Open the issue in your web browser using

@example
~/guix [env]$ mumi www
@end example

Compose a reply using

@example
~/guix [env]$ mumi compose
@end example

Compose a reply and close the issue using

@example
~/guix [env]$ mumi compose --close
@end example

@command{mumi compose} opens your mail client by passing @samp{mailto:}
URIs to @command{xdg-open}.  So, you need to have @command{xdg-open} set
up to open your mail client correctly.

Apply the latest patchset from the issue using

@example
~/guix [env]$ mumi am
@end example

You may also apply a patchset of a specific version (say, v3) using

@example
~/guix [env]$ mumi am v3
@end example

Or, you may apply a patch from a specific e-mail message.  For example,
to apply the patch from the 4th message (message index starts from 0),
run

@example
~/guix [env]$ mumi am @@4
@end example

@command{mumi am} is a wrapper around @command{git am}.  You can pass
@command{git am} arguments to it after a @samp{--}.  For example, to add
a Signed-off-by trailer, run

@example
~/guix [env]$ mumi am -- -s
@end example

Create and send patches to the issue using

@example
~/guix [env]$ git format-patch origin/master
~/guix [env]$ mumi send-email foo.patch bar.patch
@end example

Note that you do not have to pass in @samp{--to} or @samp{--cc}
arguments to @command{git format-patch}.  @command{mumi send-email} will
put them in correctly when sending the patches.

To open a new issue, run

@example
~/guix [env]$ mumi new
@end example

and send an email (using @command{mumi compose}) or patches (using
@command{mumi send-email}).

@command{mumi send-email} is really a wrapper around @command{git
send-email} that automates away all the nitty-gritty of sending patches.
It uses the current issue state to automatically figure out the correct
@samp{To} address to send to, other participants to @samp{Cc}, headers
to add, etc.

Also note that, unlike @command{git send-email}, @command{mumi
send-email} works perfectly well with single and multiple patches alike.
It automates away the debbugs dance of sending the first patch, waiting
for a response from debbugs and sending the remaining patches.  It does
so by sending the first patch, polling the server for a response, and
then sending the remaining patches.  This polling can unfortunately take
a few minutes.  So, please be patient.

@subsubsection Emacs Interface

If you use Emacs, you may find it more convenient to interact with
issues using @file{debbugs.el}, which you can install with:

@example
guix install emacs-debbugs
@end example

For example, to list all open issues on @code{guix-patches}, hit:

@example
@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
@end example

For a more convenient (shorter) way to access both the bugs and patches
submissions, you may want to configure the
@code{debbugs-gnu-default-packages} and
@code{debbugs-gnu-default-severities} Emacs variables (@pxref{Viewing
Bugs within Emacs}).

To search for bugs, @samp{@kbd{M-x} debbugs-gnu-guix-search} can be
used.

@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
this nifty tool!

@node Debbugs Usertags
@subsection Debbugs Usertags

@cindex usertags, for debbugs
@cindex Debbugs usertags
Debbugs provides a feature called @dfn{usertags} that allows any user to
tag any bug with an arbitrary label.  Bugs can be searched by usertag,
so this is a handy way to organize bugs@footnote{The list of usertags is
public information, and anyone can modify any user's list of usertags,
so keep that in mind if you choose to use this feature.}.  If you use
Emacs Debbugs, the entry-point to consult existing usertags is the
@samp{C-u M-x debbugs-gnu-usertags} procedure.  To set a usertag, press
@samp{C} while consulting a bug within the *Guix-Patches* buffer opened
with @samp{C-u M-x debbugs-gnu-bugs} buffer, then select @code{usertag}
and follow the instructions.

For example, to view all the bug reports (or patches, in the case of
@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux}
for the user @code{guix}, open a URL like the following in a web
browser:
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.

For more information on how to use usertags, please refer to the
documentation for Debbugs or the documentation for whatever tool you use
to interact with Debbugs.

In Guix, we are experimenting with usertags to keep track of
architecture-specific issues, as well as reviewed ones.  To facilitate
collaboration, all our usertags are associated with the single user
@code{guix}.  The following usertags currently exist for that user:

@table @code

@item powerpc64le-linux
The purpose of this usertag is to make it easy to find the issues that
matter most for the @code{powerpc64le-linux} system type.  Please assign
this usertag to bugs or patches that affect @code{powerpc64le-linux} but
not other system types.  In addition, you may use it to identify issues
that for some reason are particularly important for the
@code{powerpc64le-linux} system type, even if the issue affects other
system types, too.

@item reproducibility
For issues related to reproducibility.  For example, it would be
appropriate to assign this usertag to a bug report for a package that
fails to build reproducibly.

@item reviewed-looks-good
You have reviewed the series and it looks good to you (LGTM).

@end table

If you're a committer and you want to add a usertag, just start using it
with the @code{guix} user.  If the usertag proves useful to you,
consider updating this section of the manual so that others will know
what your usertag means.

@node Cuirass Build Notifications
@subsection Cuirass Build Notifications

@cindex build event notifications, RSS feed
@cindex notifications, build events
Cuirass includes @acronym{RSS, Really Simple Syndication} feeds as one
of its features (@pxref{Notifications,,,cuirass}).  Since
@url{https://ci.guix.gnu.org/, Berlin} runs an instance of Cuirass, this
feature can be used to keep track of recently broken or fixed packages
caused by changes pushed to the Guix git repository.  Any RSS client can
be used.  A good one, included with Emacs, is @xref{Gnus,,,gnus}.  To
register the feed, copy its URL, then from the main Gnus buffer,
@samp{*Group*}, do the following:

@cindex Gnus, configuration to read CI RSS feeds
@cindex RSS feeds, Gnus configuration
@example
@kbd{G R} https://ci.guix.gnu.org/events/rss/?specification=master RET
Guix CI - master RET Build events for specification master. RET
@end example

@noindent
Then, back at the @samp{*Group*} buffer, press @kbd{s} to save the newly
added RSS group.  As for any other Gnus group, you can update its
content by pressing the @kbd{g} key.  You should now receive
notifications that read like:

@example
 . [ ?: Cuirass ] Build tree-sitter-meson.aarch64-linux on master is fixed.
 . [ ?: Cuirass ] Build rust-pbkdf2.aarch64-linux on master is fixed.
 . [ ?: Cuirass ] Build rust-pbkdf2.x86_64-linux on master is fixed.
@end example

@noindent
where each RSS entry contains a link to the Cuirass build details page
of the associated build.

@node Commit Access
@section Commit Access

@cindex commit access, for developers
Everyone can contribute to Guix without having commit access
(@pxref{Submitting Patches}).  However, for frequent contributors,
having write access to the repository can be convenient.  As a rule of
thumb, a contributor should have accumulated fifty (50) reviewed commits
to be considered as a committer and have sustained their activity in the
project for at least 6 months.  This ensures enough interactions with
the contributor, which is essential for mentoring and assessing whether
they are ready to become a committer.  Commit access should not be
thought of as a ``badge of honor'' but rather as a responsibility a
contributor is willing to take to help the project.

It is expected from all contributors, and even more so from committers,
to help build consensus and make decisions based on consensus.  By using
consensus, we are committed to finding solutions that everyone can live
with.  It implies that no decision is made against significant concerns
and these concerns are actively resolved with proposals that work for
everyone.

A contributor (who may or may not have commit access) wishing to block
a proposal bears a special responsibility for finding alternatives,
proposing ideas/code or explain the rationale for the status quo to
resolve the deadlock.  To learn what consensus decision making means and
understand its finer details, you are encouraged to read
@url{https://www.seedsforchange.org.uk/consensus}.

The following sections explain how to get commit access, how to be ready
to push commits, and the policies and community expectations for commits
pushed upstream.

@subsection Applying for Commit Access

When you deem it necessary, consider applying for commit
access by following these steps:

@enumerate
@item
Find three committers who would vouch for you.  You can view the list of
committers at
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.  Each
of them should email a statement to @email{guix-maintainers@@gnu.org} (a
private alias for the collective of maintainers), signed with their
OpenPGP key.

Committers are expected to have had some interactions with you as a
contributor and to be able to judge whether you are sufficiently
familiar with the project's practices.  It is @emph{not} a judgment on
the value of your work, so a refusal should rather be interpreted as
``let's try again later''.

@item
Send @email{guix-maintainers@@gnu.org} a message stating your intent,
listing the three committers who support your application, signed with
the OpenPGP key you will use to sign commits, and giving its fingerprint
(see below).  See @uref{https://emailselfdefense.fsf.org/en/}, for an
introduction to public-key cryptography with GnuPG.

@c See <https://sha-mbles.github.io/>.
Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
signatures, which is known to be unsafe since 2019, for instance by
adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Maintainers ultimately decide whether to grant you commit access,
usually following your referrals' recommendation.

@item
@cindex OpenPGP, signed commits
If and once you've been given access, please send a message to
@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
you will use to sign commits (do that before pushing your first commit).
That way, everyone can notice and ensure you control that OpenPGP key.

@quotation Important
Before you can push for the first time, maintainers must:

@enumerate
@item
add your OpenPGP key to the @code{keyring} branch;
@item
add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
the branch(es) you will commit to.
@end enumerate
@end quotation

@item
Make sure to read the rest of this section and... profit!
@end enumerate

@quotation Note
Maintainers are happy to give commit access to people who have been
contributing for some time and have a track record---don't be shy and
don't underestimate your work!

However, note that the project is working towards a more automated patch
review and merging system, which, as a consequence, may lead us to have
fewer people with commit access to the main repository.  Stay tuned!
@end quotation

All commits that are pushed to the central repository on Savannah must
be signed with an OpenPGP key, and the public key should be uploaded to
your user account on Savannah and to public key servers, such as
@code{keys.openpgp.org}.  To configure Git to automatically sign
commits, run:

@example
git config commit.gpgsign true

# Substitute the fingerprint of your public PGP key.
git config user.signingkey CABBA6EA1DC0FF33
@end example

To check that commits are signed with correct key, use:

@example
guix git authenticate
@end example

@xref{Building from Git} for running the first authentication of a Guix
checkout.

To avoid accidentally pushing unsigned or signed with the wrong key
commits to Savannah, make sure to configure Git according to
@xref{Configuring Git}.

@subsection Commit Policy

If you get commit access, please make sure to follow the policy below
(discussions of the policy can take place on
@email{guix-devel@@gnu.org}).

Ensure you're aware of how the changes should be handled
(@pxref{Managing Patches and Branches}) prior to being pushed to the
repository, especially for the @code{master} branch.

If you're committing and pushing your own changes, try and wait at least
one week (two weeks for more significant changes, up to one month for
changes such as removing a package---@pxref{package-removal-policy,
Package Removal}) after you send them for review.  After this, if no one
else is available to review them and if you're confident about the
changes, it's OK to commit.

When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g.,
with @command{git am --signoff}.  This improves tracking of who did
what.

When adding channel news entries (@pxref{Channels, Writing Channel
News}), make sure they are well-formed by running the following command
right before pushing:

@example
make check-channel-news
@end example

@subsection Addressing Issues

Peer review (@pxref{Submitting Patches}) and tools such as
@command{guix lint} (@pxref{Invoking guix lint}) and the test suite
(@pxref{Running the Test Suite}) should catch issues before they are
pushed.  Yet, commits that ``break'' functionality might occasionally
go through.  When that happens, there are two priorities: mitigating
the impact, and understanding what happened to reduce the chance of
similar incidents in the future.  The responsibility for both these
things primarily lies with those involved, but like everything this is
a group effort.

Some issues can directly affect all users---for instance because they
make @command{guix pull} fail or break core functionality, because they
break major packages (at build time or run time), or because they
introduce known security vulnerabilities.

@cindex reverting commits
The people involved in authoring, reviewing, and pushing such
commit(s) should be at the forefront to mitigate their impact in a
timely fashion: by pushing a followup commit to fix it (if possible),
or by reverting it to leave time to come up with a proper fix, and by
communicating with other developers about the problem.

If these persons are unavailable to address the issue in time, other
committers are entitled to revert the commit(s), explaining in the
commit log and on the mailing list what the problem was, with the goal
of leaving time to the original committer, reviewer(s), and author(s)
to propose a way forward.

Once the problem has been dealt with, it is the responsibility of
those involved to make sure the situation is understood.  If you are
working to understand what happened, focus on gathering information
and avoid assigning any blame.  Do ask those involved to describe what
happened, do not ask them to explain the situation---this would
implicitly blame them, which is unhelpful.  Accountability comes from
a consensus about the problem, learning from it and improving
processes so that it's less likely to reoccur.

@subsection Commit Revocation

In order to reduce the possibility of mistakes, committers will have
their Savannah account removed from the Guix Savannah project and their
key removed from @file{.guix-authorizations} after 12 months of
inactivity; they can ask to regain commit access by emailing the
maintainers, without going through the vouching process.

Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
current list of maintainers.  You can email them privately at
@email{guix-maintainers@@gnu.org}.} may also revoke an individual's
commit rights, as a last resort, if cooperation with the rest of the
community has caused too much friction---even within the bounds of the
project's code of conduct (@pxref{Contributing}).  They would only do so
after public or private discussion with the individual and a clear
notice.  Examples of behavior that hinders cooperation and could lead to
such a decision include:

@itemize
@item repeated violation of the commit policy stated above;
@item repeated failure to take peer criticism into account;
@item breaching trust through a series of grave incidents.
@end itemize

When maintainers resort to such a decision, they notify developers on
@email{guix-devel@@gnu.org}; inquiries may be sent to
@email{guix-maintainers@@gnu.org}.  Depending on the situation, the
individual may still be welcome to contribute.

@subsection Helping Out

One last thing: the project keeps moving forward because committers not
only push their own awesome changes, but also offer some of their time
@emph{reviewing} and pushing other people's changes.  As a committer,
you're welcome to use your expertise and commit rights to help other
contributors, too!

@node Reviewing the Work of Others
@section Reviewing the Work of Others

Perhaps the biggest action you can do to help GNU Guix grow as a project
is to review the work contributed by others.  You do not need to be a
committer to do so; applying, reading the source, building, linting and
running other people's series and sharing your comments about your
experience will give some confidence to committers.  You must
ensure the check list found in the @ref{Submitting Patches} section has
been correctly followed.  A reviewed patch series should give the best
chances for the proposed change to be merged faster, so if a change you
would like to see merged hasn't yet been reviewed, this is the most
appropriate thing to do!  If you would like to review changes in a
specific area and to receive notifications for incoming patches relevant
to that domain, consider joining the relevant team(s) (@pxref{Teams}).

@cindex reviewing, guidelines
Review comments should be unambiguous; be as clear and explicit as you
can about what you think should be changed, ensuring the author can take
action on it.  Please try to keep the following guidelines in mind
during review:

@enumerate
@item
@emph{Be clear and explicit about changes you are suggesting}, ensuring
the author can take action on it.  In particular, it is a good idea to
explicitly ask for new revisions when you want it.

@item
@emph{Remain focused: do not change the scope of the work being
reviewed.}  For example, if the contribution touches code that follows a
pattern deemed unwieldy, it would be unfair to ask the submitter to fix
all occurrences of that pattern in the code; to put it simply, if a
problem unrelated to the patch at hand was already there, do not ask the
submitter to fix it.

@item
@emph{Ensure progress.}  As they respond to review, submitters may
submit new revisions of their changes; avoid requesting changes that you
did not request in the previous round of comments.  Overall, the
submitter should get a clear sense of progress; the number of items open
for discussion should clearly decrease over time.

@item
@emph{Aim for finalization.}  Reviewing code is time-consuming.  Your
goal as a reviewer is to put the process on a clear path towards
integration, possibly with agreed-upon changes, or rejection, with a
clear and mutually-understood reasoning.  Avoid leaving the review
process in a lingering state with no clear way out.

@item
@emph{Review is a discussion.}  The submitter's and reviewer's views on
how to achieve a particular change may not always be aligned.  To lead
the discussion, remain focused, ensure progress and aim for
finalization, spending time proportional to the stakes@footnote{The
tendency to discuss minute details at length is often referred to as
``bikeshedding'', where much time is spent discussing each one's
preference for the color of the shed at the expense of progress made on
the project to keep bikes dry.}.  As a reviewer, try hard to explain the
rationale for suggestions you make, and to understand and take into
account the submitter's motivation for doing things in a certain way.
@end enumerate

@cindex LGTM, Looks Good To Me
@cindex review tags
@cindex Reviewed-by, git trailer
When you deem the proposed change adequate and ready for inclusion
within Guix, the following well understood/codified
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
@footnote{The @samp{Reviewed-by} Git trailer is used by other projects
such as Linux, and is understood by third-party tools such as the
@samp{b4 am} sub-command, which is able to retrieve the complete
submission email thread from a public-inbox instance and add the Git
trailers found in replies to the commit patches.} line should be used to
sign off as a reviewer, meaning you have reviewed the change and that it
looks good to you:

@itemize
@item
If the @emph{whole} series (containing multiple commits) looks good to
you, reply with
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
to the cover page if it has one, or to the last patch of the series
otherwise, adding another @samp{(for the whole series)} comment on the
line below to explicit this fact.

@item
If you instead want to mark a @emph{single commit} as reviewed (but not
the whole series), simply reply with
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
to that commit message.
@end itemize

If you are not a committer, you can help others find a @emph{series} you
have reviewed more easily by adding a @code{reviewed-looks-good} usertag
for the @code{guix} user (@pxref{Debbugs Usertags}).

@node Updating the Guix Package
@section Updating the Guix Package

@cindex update-guix-package, updating the guix package
It is sometimes desirable to update the @code{guix} package itself (the
package defined in @code{(gnu packages package-management)}), for
example to make new daemon features available for use by the
@code{guix-service-type} service type.  In order to simplify this task,
the following command can be used:

@example
make update-guix-package
@end example

The @code{update-guix-package} make target will use the last known
@emph{commit} corresponding to @code{HEAD} in your Guix checkout,
compute the hash of the Guix sources corresponding to that commit and
update the @code{commit}, @code{revision} and hash of the @code{guix}
package definition.

To validate that the updated @code{guix} package hashes are correct and
that it can be built successfully, the following command can be run from
the directory of your Guix checkout:

@example
./pre-inst-env guix build guix
@end example

To guard against accidentally updating the @code{guix} package to a
commit that others can't refer to, a check is made that the commit used
has already been pushed to the Savannah-hosted Guix git repository.

This check can be disabled, @emph{at your own peril}, by setting the
@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable.  When
this variable is set, the updated package source is also added to the
store.  This is used as part of the release process of Guix.

@node Deprecation Policy
@section Deprecation Policy

@cindex deprecation policy
As any lively project with a broad scope, Guix changes all the time and
at all levels.  Because it's user-extensible and programmable,
incompatible changes can directly impact users and make their life
harder.  It is thus important to reduce user-visible incompatible
changes to a minimum and, when such changes are deemed necessary, to
clearly communicate them through a @dfn{deprecation period} so everyone
can adapt with minimum hassle.  This section defines the project's
commitments for smooth deprecation and describes procedures and
mechanisms to honor them.

There are several ways to use Guix; how to handle deprecation will
depend on each use case.  Those can be roughly categorized like this:

@itemize
@item
package management exclusively through the command line;

@item
advanced package management using the manifest and package interfaces;

@item
Home and System management, using the @code{operating-system} and/or
@code{home-environment} interfaces together with the service interfaces;

@item
development or use of external tools that use programming interfaces
such as the @code{(guix ...)} modules.
@end itemize

These use cases form a spectrum with varying degrees of coupling---from
``distant'' to tightly coupled.  Based on this insight, we define the
following @dfn{deprecation policies} that we consider suitable for each
of these levels.

@table @asis
@item Command-line tools
Guix sub-commands should be thought of as remaining available
``forever''.  Once a Guix sub-command is to be removed, it should be
deprecated first, and then remain available for @b{at least one year}
after the first release that deprecated it.

Deprecation should first be announced in the manual and as an entry in
@file{etc/news.scm}; additional communication such as a blog post
explaining the rationale is welcome.  Months before the scheduled
removal date, the command should print a warning explaining how to
migrate.  An example of this is the replacement of @command{guix
environment} by @command{guix shell}, started in October
2021@footnote{For more details on the @command{guix shell} transition,
see
@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.

Because of the broad impact of such a change, we recommend conducting a
user survey before enacting a plan.

@cindex package deprecation
@item Package name changes
When a package name changes, it must remain available under its old name
for @b{at least one year}.  For example, @code{go-ipfs} was renamed to
@code{kubo} following a decision made upstream; to communicate the name
change to users, the package module provided this definition:

@findex deprecated-package
@lisp
(define-public go-ipfs
  (deprecated-package "go-ipfs" kubo))
@end lisp

That way, someone running @command{guix install go-ipfs} or similar sees
a deprecation warning mentioning the new name.

@cindex package removal policy
@anchor{package-removal-policy}
@item Package removal
Packages whose upstream developers have declared as having reached ``end
of life'' or being unmaintained may be removed; likewise, packages that
have been @b{failing to build for two months or more} may be removed.

There is no formal deprecation mechanism for this case, unless a
replacement exists, in which case the @code{deprecated-package}
procedure mentioned above can be used.

If the package being removed is a ``leaf'' (no other packages depend on
it), it may be removed after a @b{one-month review period} of the patch
removing it (this applies even when the removal has additional
motivations such as security problems affecting the package).

If it has many dependent packages---as is the case for example with
Python version@tie{}2---the relevant team must propose a deprecation
removal agenda and seek consensus with other packagers for @b{at least
one month}.  It may also invite feedback from the broader user
community, for example through a survey.  Removal of all impacted
packages may be gradual, spanning multiple months, to accommodate all
use cases.

When the package being removed is considered popular, whether or not it
is a leaf, its deprecation must be announced as an entry in
@code{etc/news.scm}.

@item Package upgrade
In the case of packages with many dependents and/or many users, an
upgrade may be treated like the @emph{removal} of the previous version.

Examples include major version upgrades of programming language
implementations, as we've seen above with Python, and major upgrades of
``big'' libraries such as Qt or GTK.

@cindex service deprecation
@item Services
Changes to services for Guix Home and Guix System have a direct impact
on user configuration.  For a user, adjusting to interface changes is
rarely rewarding, which is why any such change must be clearly
communicated in advance through deprecation warnings and documentation.

Renaming of variables related to service, home, or system configuration
must be communicated for at least six months before removal using the
@code{(guix deprecation)} mechanisms.  For example, renaming of
@code{murmur-configuration} to @code{mumble-server-configuration} was
communicated through a series of definitions like this one:

@findex define-deprecated/public-alias
@lisp
(define-deprecated/public-alias
  murmur-configuration
  mumble-server-configuration)
@end lisp

Procedures slated for removal may be defined like this:

@findex define-deprecated
@lisp
(define-deprecated (elogind-service #:key (config (elogind-configuration)))
  elogind-service-type
  (service elogind-service-type config))
@end lisp

Record fields, notably fields of service configuration records, must
follow a similar deprecation period.  This is usually achieved through
@i{ad hoc} means though.  For example, the @code{hosts-file} field of
@code{operating-system} was deprecated by adding a @code{sanitized}
property that would emit a warning:

@lisp
(define-record-type* <operating-system>
  ;; @dots{}
  (hosts-file %operating-system-hosts-file         ;deprecated
              (default #f)
              (sanitize warn-hosts-file-field-deprecation)))

(define-deprecated (operating-system-hosts-file os)
  hosts-service-type
  (%operating-system-hosts-file os))
@end lisp

When deprecating interfaces in @code{operating-system},
@code{home-environment}, @code{(gnu services)}, or any popular service,
the deprecation must come with an entry in @code{etc/news.scm}.

@cindex deprecation of programming interfaces
@item Core interfaces
Core programming interfaces, in particular the @code{(guix ...)}
modules, may be relied on by a variety of external tools and channels.
Any incompatible change must be formally deprecated with
@code{define-deprecated}, as shown above, for @b{at least one year}
before removal.  The manual must clearly document the new interface and,
except in obvious cases, explain how to migrate from the old one.

As an example, the @code{build-expression->derivation} procedure was
superseded by @code{gexp->derivation} and remained available as a
deprecated symbol:

@lisp
(define-deprecated (build-expression->derivation store name exp
                                                 #:key @dots{})
  gexp->derivation
  @dots{})
@end lisp

Sometimes bindings are moved from one module to another.  In those
cases, bindings must be reexported from the original module for at least
one year.
@end table

This section does not cover all possible situations but hopefully allows
users to know what to expect and developers to stick to its spirit.
Please email @email{guix-devel@@gnu.org} for any questions.

@cindex documentation
@node Writing Documentation
@section Writing Documentation

Guix is documented using the Texinfo system.  If you are not yet
familiar with it, we accept contributions for documentation in most
formats.  That includes plain text, Markdown, Org, etc.

Documentation contributions can be sent to
@email{guix-patches@@gnu.org}.  Prepend @samp{[DOCUMENTATION]} to the
subject.

When you need to make more than a simple addition to the documentation,
we prefer that you send a proper patch as opposed to sending an email
as described above.  @xref{Submitting Patches} for more information on
how to send your patches.

To modify the documentation, you need to edit @file{doc/guix.texi} and
@file{doc/contributing.texi} (which contains this documentation
section), or @file{doc/guix-cookbook.texi} for the cookbook.  If
you compiled the Guix repository before, you will have
many more @file{.texi} files that are translations of these
documents.  Do not modify them, the translation is managed through
@uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
@xref{Translating Guix} for more information.

To render documentation, you must first make sure that you ran
@command{./configure} in your source tree (@pxref{Running Guix Before
It Is Installed}).  After that you can run one of the following
commands:

@itemize
@item @samp{make doc/guix.info} to compile the Info manual.
      You can check it with @command{info doc/guix.info}.
@item @samp{make doc/guix.html} to compile the HTML version.
      You can point your browser to the relevant file in the
      @file{doc/guix.html} directory.
@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
@end itemize

@cindex translation
@cindex l10n
@cindex i18n
@cindex native language support
@node Translating Guix
@section Translating Guix

Writing code and packages is not the only way to provide a meaningful
contribution to Guix.  Translating to a language you speak is another
example of a valuable contribution you can make.  This section is designed
to describe the translation process.  It gives you advice on how you can
get involved, what can be translated, what mistakes you should avoid and
what we can do to help you!

Guix is a big project that has multiple components that can be translated.
We coordinate the translation effort on a
@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
hosted by our friends at Fedora.  You will need an account to submit
translations.

Some of the software packaged in Guix also contain translations.  We do not
host a translation platform for them.  If you want to translate a package
provided by Guix, you should contact their developers or find the information
on their website.  As an example, you can find the homepage of the
@code{hello} package by typing @code{guix show hello}.  On the ``homepage''
line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.

Many GNU and non-GNU packages can be translated on the
@uref{https://translationproject.org,Translation Project}.  Some projects
with multiple components have their own platform.  For instance, GNOME has
its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.

Guix has five components hosted on Weblate.

@itemize
@item @code{guix} contains all the strings from the Guix software (the
      guided system installer, the package manager, etc), excluding packages.
@item @code{packages} contains the synopsis (single-sentence description
      of a package) and description (longer description) of packages in Guix.
@item @code{website} contains the official Guix website, except for
      blog posts and multimedia content.
@item @code{documentation-manual} corresponds to this manual.
@item @code{documentation-cookbook} is the component for the cookbook.
@end itemize

@subsubheading General Directions

Once you get an account, you should be able to select a component from
@uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
and select a language.  If your language does not appear in the list, go
to the bottom and click on the ``Start new translation'' button.  Select
the language you want to translate to from the list, to start your new
translation.

Like lots of other free software packages, Guix uses
@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
with which translatable strings are extracted from the source code to so-called
PO files.

Even though PO files are text files, changes should not be made with a text
editor but with PO editing software.  Weblate integrates PO editing
functionality.  Alternatively, translators can use any of various
free-software tools for filling in translations, of which
@uref{https://poedit.net/,Poedit} is one example, and (after logging in)
@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
file.  There is also a special
@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
Emacs.  Over time translators find out what software they are happy with and
what features they need.

On Weblate, you will find various links to the editor, that will show various
subsets (or all) of the strings.  Have a look around and at the
@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
yourself with the platform.

@subsubheading Translation Components

In this section, we provide more detailed guidance on the translation
process, as well as details on what you should or should not do.  When in
doubt, please contact us, we will be happy to help!

@table @asis
@item guix
Guix is written in the Guile programming language, and some strings contain
special formatting that is interpreted by Guile.  These special formatting
should be highlighted by Weblate.  They start with @code{~} followed by one
or more characters.

When printing the string, Guile replaces the special formatting symbols with
actual values.  For instance, the string @samp{ambiguous package specification
`~a'} would be substituted to contain said package specification instead of
@code{~a}.  To properly translate this string, you must keep the formatting
code in your translation, although you can place it where it makes sense in
your language.  For instance, the French translation says @samp{spécification
du paquet « ~a » ambiguë} because the adjective needs to be placed in the
end of the sentence.

If there are multiple formatting symbols, make sure to respect the order.
Guile does not know in which order you intended the string to be read, so it
will substitute the symbols in the same order as the English sentence.

As an example, you cannot translate @samp{package '~a' has been superseded by
'~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
reversed.  If @var{foo} is superseded by @var{bar}, the translation would read
@samp{'foo' superseeds package 'bar'}.  To work around this problem, it
is possible to use more advanced formatting to select a given piece of data,
instead of following the default English order.  @xref{Formatted Output,,,
guile, GNU Guile Reference Manual}, for more information on formatting in Guile.

@item packages

Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
and Descriptions}).   Texinfo markup looks like @samp{@@code@{rm -rf@}},
@samp{@@emph@{important@}}, etc.  When translating, please leave markup as is.

The characters after ``@@'' form the name of the markup, and the text between
``@{'' and ``@}'' is its content.  In general, you should not translate the
content of markup like @code{@@code}, as it contains literal code that do not
change with language.  You can translate the content of formatting markup such
as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}.  However, do
not translate the name of the markup, or it will not be recognized.  Do
not translate the word after @code{@@end}, it is the name of the markup that
is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).

@item documentation-manual and documentation-cookbook

The first step to ensure a successful translation of the manual is to find
and translate the following strings @emph{first}:

@itemize
@item @code{version.texi}: Translate this string as @code{version-xx.texi},
      where @code{xx} is your language code (the one shown in the URL on
      weblate).
@item @code{contributing.texi}: Translate this string as
      @code{contributing.xx.texi}, where @code{xx} is the same language code.
@item @code{Top}: Do not translate this string, it is important for Texinfo.
      If you translate it, the document will be empty (missing a Top node).
      Please look for it, and register @code{Top} as its translation.
@end itemize

Translating these strings first ensure we can include your translation in
the guix repository without breaking the make process or the
@command{guix pull} machinery.

The manual and the cookbook both use Texinfo.  As for @code{packages}, please
keep Texinfo markup as is.  There are more possible markup types in the manual
than in the package descriptions.  In general, do not translate the content
of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc.  You
should translate the content of formatting markup such as @code{@@emph},
@code{@@i}, etc.

The manual contains sections that can be referred to by name by @code{@@ref},
@code{@@xref} and @code{@@pxref}.  We have a mechanism in place so you do
not have to translate their content.  If you keep the English title, we will
automatically replace it with your translation of that title.  This ensures
that Texinfo will always be able to find the node. If you decide to change
the translation of the title, the references will automatically be updated
and you will not have to update them all yourself.

When translating references from the cookbook to the manual, you need to
replace the name of the manual and the name of the section.  For instance,
to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
Manual@}}, you would replace @code{Defining Packages} with the title of that
section in the translated manual @emph{only} if that title is translated.
If the title is not translated in your language yet, do not translate it here,
or the link will be broken.  Replace @code{guix} with @code{guix.xx} where
@code{xx} is your language code.  @code{GNU Guix Reference Manual} is the
text of the link.  You can translate it however you wish.

@item website

The website pages are written using SXML, an s-expression version of HTML,
the basic language of the web.  We have a process to extract translatable
strings from the source, and replace complex s-expressions with a more familiar
XML markup, where each markup is numbered.  Translators can arbitrarily change
the ordering, as in the following example.

@example
#. TRANSLATORS: Defining Packages is a section name
#. in the English (en) manual.
#: apps/base/templates/about.scm:64
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
@end example

Note that you need to include the same markups.  You cannot skip any.
@end table

In case you make a mistake, the component might fail to build properly with your
language, or even make guix pull fail.  To prevent that, we have a process
in place to check the content of the files before pushing to our repository.
We will not be able to update the translation for your language in Guix, so
we will notify you (through weblate and/or by email) so you get a chance to
fix the issue.

@subsubheading Outside of Weblate

Currently, some parts of Guix cannot be translated on Weblate, help wanted!

@itemize
@item @command{guix pull} news can be translated in @file{news.scm}, but is not
      available from Weblate.  If you want to provide a translation, you
      can prepare a patch as described above, or simply send us your
      translation with the name of the news entry you translated and your
      language. @xref{Writing Channel News}, for more information about
      channel news.
@item Guix blog posts cannot currently be translated.
@item The installer script (for foreign distributions) is entirely in English.
@item Some of the libraries Guix uses cannot be translated or are translated
      outside of the Guix project.  Guile itself is not internationalized.
@item Other manuals linked from this manual or the cookbook might not be
      translated.
@end itemize

@subsubheading Conditions for Inclusion

There are no conditions for adding new translations of the @code{guix} and
@code{guix-packages} components, other than they need at least one translated
string.  New languages will be added to Guix as soon as possible.  The
files may be removed if they fall out of sync and have no more translated
strings.

Given that the web site is dedicated to new users, we want its translation
to be as complete as possible before we include it in the language menu.
For a new language to be included, it needs to reach at least 80% completion.
When a language is included, it may be removed in the future if it stays
out of sync and falls below 60% completion.

The manual and cookbook are automatically added in the default compilation
target.  Every time we synchronize translations, developers need to
recompile all the translated manuals and cookbooks.  This is useless for what
is essentially the English manual or cookbook.  Therefore, we will only
include a new language when it reaches 10% completion in the component.
When a language is included, it may be removed in the future if it stays
out of sync and falls below 5% completion.

@subsubheading Translation Infrastructure

Weblate is backed by a git repository from which it discovers new strings to
translate and pushes new and updated translations.  Normally, it would be
enough to give it commit access to our repositories.  However, we decided
to use a separate repository for two reasons.  First, we would have to give
Weblate commit access and authorize its signing key, but we do not trust it
in the same way we trust guix developers, especially since we do not manage
the instance ourselves.  Second, if translators mess something up, it can
break the generation of the website and/or guix pull for all our users,
independently of their language.

For these reasons, we use a dedicated repository to host translations, and we
synchronize it with our guix and artworks repositories after checking no issue
was introduced in the translation.

Developers can download the latest PO files from weblate in the Guix
repository by running the @command{make download-po} command.  It will
automatically download the latest files from weblate, reformat them to a
canonical form, and check they do not contain issues.  The manual needs to be
built again to check for additional issues that might crash Texinfo.

Before pushing new translation files, developers should add them to the
make machinery so the translations are actually available.  The process
differs for the various components.

@itemize
@item New po files for the @code{guix} and @code{packages} components must
      be registered by adding the new language to @file{po/guix/LINGUAS} or
      @file{po/packages/LINGUAS}.
@item New po files for the @code{documentation-manual} component must be
      registered by adding the file name to @code{DOC_PO_FILES} in
      @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
      @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
      @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
      @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
@item New po files for the @code{documentation-cookbook} component must be
      registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
      @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
      manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
      @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
      in @file{doc/local.mk}.
@item New po files for the @code{website} component must be added to the
      @code{guix-artwork} repository, in @file{website/po/}.
      @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
      be updated accordingly (see @file{website/i18n-howto.txt} for more
      information on the process).
@end itemize


@cindex infrastructure
@node Contributing to Guix's infrastructure
@section Contributing to Guix's infrastructure

Since its inception, the Guix project has always valued its autonomy, and that
reflects in its infrastructure: our servers run Guix System and exclusively
free software, and are administered by volunteers.

Of course this comes at a cost and this is why we need contributions.  Our hope
is to make infrastructure-related activity more legible so that maybe you can
picture yourself helping in one of these areas.


@menu
* Coding::
* System administration::
* Day-to-day system administration::
* On-site intervention::
* Hosting::
* Administrative tasks::
@end menu

@node Coding
@subsection Coding

Guix runs many Guix-specific services; this is all lovely Scheme code but it
tends to receive less attention than Guix itself:

@itemize
@item Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe}
@item Cuirass: @url{https://guix.gnu.org/cuirass/}
@item Goggles (IRC logger):
@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm}
@item Guix Build Coordinator:
@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/}
@item Guix Data Service:
@url{https://git.savannah.gnu.org/git/guix/data-service.git/}
@item Guix Packages Website:
@url{https://codeberg.org/luis-felipe/guix-packages-website.git}
@item mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/}
@item nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/}
@item QA Frontpage: @url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git}
@end itemize

There is no time constraint on this coding activity: any improvement is
welcome, whenever it comes.  Most of these code bases are relatively small,
which should make it easier to get started.

Prerequisites: Familiarity with Guile, HTTP, and databases.

If you wish to get started, check out the README of the project of your choice
and get in touch with guix-devel and the primary developer(s) of the tool as
per @code{git shortlog -s | sort -k1 -n}.

@node System administration
@subsection System administration

Guix System configuration for all our systems is held in this repository:

@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/}

The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org)
and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org,
guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more).  Both connect to a
number of build machines and helpers.

Without even having SSH access to the machine, you can help by posting patches
to improve the configuration (you can test it with @code{guix system vm}).
Here are ways you can help:

@itemize
@item
Improve infra monitoring: set up a dashboard to monitor all the infrastructure,
and an out-of-band channel to communicate about downtime.

@item
Implement web site redundancy: guix.gnu.org should be backed by several
machines on different sites.  Get in touch with us and/or send a patch!

@item
Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and
ci.guix.gnu.org should be backed by several head nodes.

@item
Improve backup: there's currently ad-hoc backup of selected pieces over rsync
between the two head nodes; we can improve on that, for example with a
dedicated backup site and proper testing of recoverability.

@item
Support mirroring: We'd like to make it easy for others to mirror substitutes
from ci.guix and bordeaux.guix, perhaps by offering public rsync access.

@item
Optimize our web services: Monitor the performance of our services and tweak
nginx config or whatever it takes to improve it.

There is no time constraint on this activity: any improvement is welcome,
whenever you can work on it.

Prerequisite: Familiarity with Guix System administration and ideally with the
infrastructure handbook:

@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org}

@end itemize

@node Day-to-day system administration
@subsection Day-to-day system administration

We're also looking for people who'd be willing to have SSH access to some of
the infrastructure to help with day-to-day maintenance: restarting a build,
restarting the occasional service that has gone wild (that can happen),
reconfiguring/upgrading a machine, rebooting, etc.

This day-to-day activity requires you to be available some of the time (during
office hours or not, during the week-end or not), whenever is convenient for
you, so you can react to issues reported on IRC, on the mailing list, or
elsewhere, and synchronize with other sysadmins.

Prerequisite: Being a “known” member of the community, familiarity with Guix
System administration, with some of the services/web sites being run, and with
the infrastructure handbook:

@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org}

@node On-site intervention
@subsection On-site intervention

The first front-end is currently generously hosted by the Max Delbrück Center
(MDC), a research institute in Berlin, Germany. Only authorized personnel can
physically access it.

The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a
professional data center shared with non-profit ISP Aquilenet.  If you live in
the region of Bordeaux and would like to help out when we need to go on-site,
please make yourself known by emailing @email{guix-sysadmin@@gnu.org}.

On-site interventions are rare, but they're usually in response to an
emergency.

@node Hosting
@subsection Hosting

We're looking for people who can host machines and help out whenever
physical access is needed.  More specifically:

@itemize
@item
We need hosting of “small” machines such as single-board computers (AArch64,
RISC-V) for use as build machines.

@item
We need hosting for front-ends and x86_64 build machines in a data center where
they can be racked and where, ideally, several local Guix sysadmins can
physically access them.
@end itemize

The machines should be accessible over Wireguard VPN most of the
time, so longer power or network interruptions should be the
exception.

Prerequisites: Familiarity with installing and remotely administering Guix
System.

@node Administrative tasks
@subsection Administrative tasks

The infra remains up and running thanks to crucial administrative tasks, which
includes:

@itemize
@item
Selecting and purchasing hardware, for example build machines.
@item
Renewing domain names.

@item
Securing funding, in particular via the Guix Foundation:
@url{https://foundation.guix.info}
@end itemize

Prerequisites: Familiarity with hardware, and/or DNS registrars,
and/or sponsorship, and/or crowdfunding.

debug log:

solving 1fb6ce2e1e ...
found 1fb6ce2e1e in https://yhetil.org/guix/e661d69afb3a40516403cc722ecbbe73639d3892.1730970238.git.ekaitz@elenq.tech/
found acdc303be6 in https://git.savannah.gnu.org/cgit/guix.git
preparing index
index prepared:
100644 acdc303be67f1b01c0d2ac0d54b55a45b6ef98ae	doc/contributing.texi

applying [1/1] https://yhetil.org/guix/e661d69afb3a40516403cc722ecbbe73639d3892.1730970238.git.ekaitz@elenq.tech/
diff --git a/doc/contributing.texi b/doc/contributing.texi
index acdc303be6..1fb6ce2e1e 100644

Checking patch doc/contributing.texi...
Applied patch doc/contributing.texi cleanly.

index at:
100644 1fb6ce2e1e4c170a417b33f34375abecc07d6fe5	doc/contributing.texi

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.