aboutsummaryrefslogtreecommitdiff
// -*- C++ -*-
//  Boost general library 'format'   ---------------------------
//  See http://www.boost.org for updates, documentation, and revision history.

//  (C) Samuel Krempp 2001
//                  krempp@crans.ens-cachan.fr
//  Permission to copy, use, modify, sell and
//  distribute this software is granted provided this copyright notice appears
//  in all copies. This software is provided "as is" without express or implied
//  warranty, and with no claim as to its suitability for any purpose.

// ideas taken from Rüdiger Loos's format class
// and Karl Nelson's ofstream (also took its parsing code as basis for printf parsing)

// ------------------------------------------------------------------------------
// format_fwd.hpp :  forward declarations, for primary header format.hpp
// ------------------------------------------------------------------------------

#ifndef BOOST_FORMAT_FWD_HPP
#define BOOST_FORMAT_FWD_HPP

#include <string>
#include <iosfwd>

namespace boost {

class basic_format;

typedef basic_format    format;

namespace io {
enum format_error_bits { bad_format_string_bit = 1, 
                         too_few_args_bit = 2, too_many_args_bit = 4,
                         out_of_range_bit = 8,
                         all_error_bits = 255, no_error_bits=0 };
                  
// Convertion:  format   to   string
std::string     str(const basic_format& ) ;

} // namespace io


BOOST_IO_STD ostream& 
operator<<( BOOST_IO_STD ostream&, const basic_format&);


} // namespace boost

#endif // BOOST_FORMAT_FWD_HPP
1'>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
@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
* Building from Git::           The latest and greatest.
* Running Guix Before It Is Installed::  Hacker tricks.
* The Perfect Setup::           The right tools.
* 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.
* Updating the Guix Package::   Updating the Guix package definition.
* Writing Documentation::       Improving documentation in GNU Guix.
* Translating Guix::            Make Guix speak your native language.
@end menu

@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 --pure
@end example

@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.

Then, run:

@example
./configure --localstatedir=/var --sysconfdir=/etc
@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
make authenticate
@end example

The first run takes a couple of minutes, but subsequent runs are faster.

Or, when your configuration for your local Git repository doesn't match
the default one, you can provide the reference for the @code{keyring}
branch through the variable @code{GUIX_GIT_KEYRING}.  The following
example assumes that you have a Git remote called @samp{myremote}
pointing to the official repository:

@example
make authenticate GUIX_GIT_KEYRING=myremote/keyring
@end example

@quotation Note
You are advised to run @command{make authenticate} after every
@command{git pull} invocation.  This ensures you keep receiving valid
changes to the repository.
@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/dunst.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}.

@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; it
is generated by running @command{./bootstrap} followed by
@command{./configure}).  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 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.
* 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 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

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.

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.

@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.

@cindex Vim, Scheme code editing
If you are editing code with Vim, we recommend that you run @code{:set
autoindent} so that your code is automatically indented as you type.
Additionally,
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}} may help you deal with all these parentheses.

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 or the @command{git send-email} command
(@pxref{Sending a Patch Series}).  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}.

Other important Git configuration will automatically be configured when
building the project (@pxref{Building from Git}).

@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, see @xref{Teams}.

@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

There are several teams mentoring different parts of the Guix source
code.  To list all those teams, you can run 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:
+ Christopher Baines <mail@@cbaines.net>
+ Ricardo Wurmus <rekado@@elephly.net>
+ Mathieu Othacehe <othacehe@@gnu.org>
+ jgart <jgart@@dismail.de>
+ Ludovic Courtès <ludo@@gnu.org>
@dots{}
@end example

You can run the following command to have the @code{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.
@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 wish to merge 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.  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.

@node Debbugs User Interfaces
@subsection Debbugs User Interfaces

@subsubsection Web interface

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@footnote{The web interface at
@url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
software written in Guile, and you can help!  See
@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
bug reports and patches, and to participate in discussions;
@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

Mumi also comes with a command-line interface that can be used to search
existing issues, open new issues 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 easily create and send
patches to it 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 patches

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

@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

@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.}.

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.  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.

@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 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.  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
make authenticate
@end example

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) 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 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.

@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