/
proc
/
1387184
/
root
/
snap
/
lxd
/
current
/
share
/
lxd-documentation
/
contributing
/
File Upload :
llllll
Current File: //proc/1387184/root/snap/lxd/current/share/lxd-documentation/contributing/index.html
<!doctype html> <html class="no-js" lang="en" data-content_root="../"> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="How to contribute to LXD" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://documentation.ubuntu.com/lxd/latest/contributing/" /> <meta property="og:site_name" content="LXD documentation" /> <meta property="og:description" content="The LXD team welcomes contributions through pull requests, issue reports, and discussions. Contribute to the code or documentation, report bugs, or request features in the GitHub repository, Ask qu..." /> <meta property="og:image" content="https://documentation.ubuntu.com/lxd/latest/_static/tag.png" /> <meta property="og:image:alt" content="LXD documentation" /> <meta name="description" content="The LXD team welcomes contributions through pull requests, issue reports, and discussions. Contribute to the code or documentation, report bugs, or request features in the GitHub repository, Ask qu..." /> <link rel="index" title="Index" href="../genindex/" /><link rel="search" title="Search" href="../search/" /><link rel="next" title="Explanation" href="../explanation/" /><link rel="prev" title="How to get support" href="../support/" /> <link rel="canonical" href="https://documentation.ubuntu.com/lxd/contributing/" /> <link rel="shortcut icon" href="../_static/favicon.ico"/><!-- Generated with Sphinx 8.2.3 and Furo 2025.07.19 --> <title>How to contribute to LXD</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d111a655" /> <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=25af2a20" /> <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../_static/youtube.css" /> <link rel="stylesheet" type="text/css" href="../_static/related-links.css" /> <link rel="stylesheet" type="text/css" href="../_static/terminal-output.css" /> <link rel="stylesheet" type="text/css" href="../_static/config-options.css" /> <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=95c83b7e" /> <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=8dab3a3b" /> <link rel="stylesheet" type="text/css" href="../_static/custom.css?v=66d86e9d" /> <link rel="stylesheet" type="text/css" href="../_static/header.css?v=84f70f09" /> <link rel="stylesheet" type="text/css" href="../_static/github_issue_links.css?v=af88fb93" /> <link rel="stylesheet" type="text/css" href="../_static/furo_colors.css?v=c4ccdb8a" /> <link rel="stylesheet" type="text/css" href="../_static/footer.css?v=bd05fc90" /> <link rel="stylesheet" type="text/css" href="../_static/cookie-banner.css?v=b74831ab" /> </head> <body> <header id="header" class="p-navigation"> <script type="module" src="../_static/js/bundle.js"> </script> <!-- Google Tag Manager --> <script> (function(w, d, s, l, i) { w[l] = w[l] || []; w[l].push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' }); var f = d.getElementsByTagName(s)[0]; var j = d.createElement(s); var dl = ''; if (l != 'dataLayer') { dl = '&l=' + l; } j.async = true; j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl; f.parentNode.insertBefore(j, f); })(window, document, 'script', 'dataLayer', 'GTM-KNX3CJC'); </script> <div class="p-navigation__nav" role="menubar"> <ul class="p-navigation__links" role="menu"> <li> <a class="p-logo" href="https://canonical.com/lxd" aria-current="page"> <img src="../_static/tag.png" alt="Logo" class="p-logo-image"> <div class="p-logo-text p-heading--4">LXD </div> </a> </li> <li class="nav-ubuntu-com"> <a href="https://canonical.com/lxd" class="p-navigation__link">canonical.com/lxd</a> </li> <li> <a href="#" class="p-navigation__link nav-more-links">More resources</a> <ul class="more-links-dropdown"> <li> <a href="https://ubuntu.com/lxd/install/" class="p-navigation__sub-link p-dropdown__link">Install LXD</a> </li> <li> <a href="https://ubuntu.com/lxd/manage/" class="p-navigation__sub-link p-dropdown__link">Manage LXD</a> </li> <li> <a href="https://discourse.ubuntu.com/c/lxd/" class="p-navigation__sub-link p-dropdown__link">Forum</a> </li> <li> <a href="https://github.com/canonical/lxd" class="p-navigation__sub-link p-dropdown__link">GitHub</a> </li> </ul> </li> </ul> </div> </header> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> </svg> </symbol> <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> <title>Auto light/dark, in light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> <circle cx="14.5" cy="9.55" r="3.6"/> </svg> </symbol> <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> <title>Auto light/dark, in dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> </svg> </symbol> <symbol id="svg-pencil" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> <path d="M13.5 6.5l4 4" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> <symbol id="svg-eye" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> <path d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"> <div class="visually-hidden">Hide navigation sidebar</div> </label> <label class="overlay toc-overlay" for="__toc"> <div class="visually-hidden">Hide table of contents sidebar</div> </label> <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <div class="visually-hidden">Toggle site navigation sidebar</div> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="../"><div class="brand">LXD</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand" href="../"> </a><form class="sidebar-search-container" method="get" action="../search/" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="submit" value="Go"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../">LXD</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorial/">Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Tutorials</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../tutorial/first_steps/">First steps with LXD</a></li> <li class="toctree-l2"><a class="reference internal" href="../tutorial/ui/">Getting started with the UI</a></li> </ul> </li> <li class="toctree-l1 current has-children"><a class="reference internal" href="../howto/">How-to guides</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of How-to guides</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current"> <li class="toctree-l2 has-children"><a class="reference internal" href="../getting_started/">Getting started</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Getting started</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../installing/">Install LXD</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/initialize/">Initialize LXD</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/access_ui/">Access the UI</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/access_documentation/">Access documentation locally</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../operation/">LXD server and client</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of LXD server and client</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/server_expose/">Expose LXD to the network</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/server_configure/">Configure the LXD server</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/oidc_auth0/">Configure OIDC authentication with Auth0</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/oidc_ory/">Configure OIDC authentication with Ory Hydra</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/oidc_keycloak/">Configure OIDC authentication with Keycloak</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/oidc_entra_id/">Configure OIDC authentication with Microsoft Entra ID</a></li> <li class="toctree-l3"><a class="reference internal" href="../remotes/">Add remote servers</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/lxc_alias/">Add command aliases</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../instances/">Instances</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Instances</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_create/">Create instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_configure/">Configure instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_manage/">Manage instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../profiles/">Use profiles</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_troubleshoot/">Troubleshoot errors</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_ubuntu_pro_attach/">Auto attach Ubuntu Pro</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_access_files/">Access files</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_console/">Access the console</a></li> <li class="toctree-l3"><a class="reference internal" href="../instance-exec/">Run commands</a></li> <li class="toctree-l3"><a class="reference internal" href="../cloud-init/">Use cloud-init</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_routed_nic_vm/">Add a routed NIC to a VM</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_backup/">Back up instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_migrate/">Migrate instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/import_machines_to_instances/">Import existing machines</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/container_gpu_passthrough_with_docker/">Pass NVIDIA GPUs</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../images/">Images</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Images</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/images_remote/">Use remote images</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/images_manage/">Manage images</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/images_profiles/">Associate profiles</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/images_copy/">Copy and import images</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/images_create/">Create images</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../projects/">Projects</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of Projects</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/projects_create/">Create and configure</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/projects_work/">Work with projects</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/projects_confine/">Confine users to projects</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../storage/">Storage</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of Storage</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_pools/">Manage pools</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_volumes/">Manage volumes</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_buckets/">Manage buckets</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_create_instance/">Create an instance in a pool</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_backup_volume/">Back up a volume</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/storage_move_volume/">Move or copy a volume</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../networks/">Networking</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of Networking</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/network_create/">Create a network</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_configure/">Configure a network</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_bgp/">Configure as BGP server</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_acls/">Configure network ACLs</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_forwards/">Configure forwards</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_zones/">Configure network zones</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_bridge_firewalld/">Configure your firewall</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_bridge_resolved/">Integrate with resolved</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_ovn_setup/">Set up OVN</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_load_balancers/">Configure load balancers</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_ovn_peers/">Configure peer routing</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_ipam/">Display IPAM information</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../clustering/">Clustering</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle navigation of Clustering</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_form/">Form a cluster</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_manage/">Manage a cluster</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_config_networks/">Configure networks</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_config_storage/">Configure storage</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_manage_instance/">Manage instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_groups/">Set up cluster groups</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/cluster_recover/">Recover a cluster</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../production-setup/">Production setup</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle navigation of Production setup</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/benchmark_performance/">Benchmark performance</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/network_increase_bandwidth/">Increase bandwidth</a></li> <li class="toctree-l3"><a class="reference internal" href="../metrics/">Monitor metrics</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/logs_loki/">Send logs to Loki</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/grafana/">Set up Grafana</a></li> <li class="toctree-l3"><a class="reference internal" href="../backup/">Back up a server</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/disaster_recovery/">Recover instances</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../howto/snap/">Manage the snap</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../howto/troubleshoot/">Troubleshooting</a><input class="toctree-checkbox" id="toctree-checkbox-12" name="toctree-checkbox-12" role="switch" type="checkbox"/><label for="toctree-checkbox-12"><div class="visually-hidden">Toggle navigation of Troubleshooting</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../howto/network_bridge_firewalld/">Configure your firewall</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/instances_troubleshoot/">Troubleshoot instances</a></li> <li class="toctree-l3"><a class="reference internal" href="../howto/dqlite_troubleshoot/">Troubleshoot Dqlite</a></li> <li class="toctree-l3"><a class="reference internal" href="../debugging/">Debug LXD</a></li> <li class="toctree-l3"><a class="reference internal" href="../faq/">Frequently asked</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../support/">Get support</a></li> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Contribute to LXD</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../explanation/">Explanation</a><input class="toctree-checkbox" id="toctree-checkbox-13" name="toctree-checkbox-13" role="switch" type="checkbox"/><label for="toctree-checkbox-13"><div class="visually-hidden">Toggle navigation of Explanation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../explanation/lxd_lxc/"><code class="docutils literal notranslate"><span class="pre">lxd</span></code> and <code class="docutils literal notranslate"><span class="pre">lxc</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/instances/">Containers and VMs</a></li> <li class="toctree-l2"><a class="reference internal" href="../image-handling/">Local and remote images</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/storage/">Storage pools, volumes, and buckets</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/networks/">Networking setups</a></li> <li class="toctree-l2"><a class="reference internal" href="../database/">The LXD Dqlite database</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/lxc_show_info/"><code class="docutils literal notranslate"><span class="pre">lxc</span></code> <code class="docutils literal notranslate"><span class="pre">show</span></code> and <code class="docutils literal notranslate"><span class="pre">info</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="../authentication/">Remote API authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/authorization/">Remote API authorization</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/projects/">Instances grouping with projects</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/clusters/">Clusters</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/performance_tuning/">Performance tuning</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/security/">Security</a></li> <li class="toctree-l2"><a class="reference internal" href="../explanation/bpf/">Privilege delegation using BPF Token</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../reference/">Reference</a><input class="toctree-checkbox" id="toctree-checkbox-14" name="toctree-checkbox-14" role="switch" type="checkbox"/><label for="toctree-checkbox-14"><div class="visually-hidden">Toggle navigation of Reference</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../requirements/">Requirements</a></li> <li class="toctree-l2"><a class="reference internal" href="../architectures/">Architectures</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/releases-snap/">Releases and snap</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/remote_image_servers/">Remote image servers</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/image_format/">Image format</a></li> <li class="toctree-l2"><a class="reference internal" href="../guest-os-compatibility/">Guest OS compatibility</a></li> <li class="toctree-l2"><a class="reference internal" href="../container-environment/">Container environment</a></li> <li class="toctree-l2"><a class="reference internal" href="../config-options/">Configuration option index</a></li> <li class="toctree-l2"><a class="reference internal" href="../server/">Server configuration</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../explanation/instance_config/">Instance configuration</a><input class="toctree-checkbox" id="toctree-checkbox-15" name="toctree-checkbox-15" role="switch" type="checkbox"/><label for="toctree-checkbox-15"><div class="visually-hidden">Toggle navigation of Instance configuration</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../reference/instance_properties/">Instance properties</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/instance_options/">Instance options</a></li> <li class="toctree-l3 has-children"><a class="reference internal" href="../reference/devices/">Devices</a><input class="toctree-checkbox" id="toctree-checkbox-16" name="toctree-checkbox-16" role="switch" type="checkbox"/><label for="toctree-checkbox-16"><div class="visually-hidden">Toggle navigation of Devices</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../reference/standard_devices/">Standard devices</a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_none/">Type: <code class="docutils literal notranslate"><span class="pre">none</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_nic/">Type: <code class="docutils literal notranslate"><span class="pre">nic</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_disk/">Type: <code class="docutils literal notranslate"><span class="pre">disk</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_unix_char/">Type: <code class="docutils literal notranslate"><span class="pre">unix-char</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_unix_block/">Type: <code class="docutils literal notranslate"><span class="pre">unix-block</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_usb/">Type: <code class="docutils literal notranslate"><span class="pre">usb</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_gpu/">Type: <code class="docutils literal notranslate"><span class="pre">gpu</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_infiniband/">Type: <code class="docutils literal notranslate"><span class="pre">infiniband</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_proxy/">Type: <code class="docutils literal notranslate"><span class="pre">proxy</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_unix_hotplug/">Type: <code class="docutils literal notranslate"><span class="pre">unix-hotplug</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_tpm/">Type: <code class="docutils literal notranslate"><span class="pre">tpm</span></code></a></li> <li class="toctree-l4"><a class="reference internal" href="../reference/devices_pci/">Type: <code class="docutils literal notranslate"><span class="pre">pci</span></code></a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="../reference/instance_units/">Units for storage and network limits</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../reference/preseed_yaml_fields/">Preseed YAML file fields</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/projects/">Project configuration</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../reference/storage_drivers/">Storage drivers</a><input class="toctree-checkbox" id="toctree-checkbox-17" name="toctree-checkbox-17" role="switch" type="checkbox"/><label for="toctree-checkbox-17"><div class="visually-hidden">Toggle navigation of Storage drivers</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_btrfs/">Btrfs - <code class="docutils literal notranslate"><span class="pre">btrfs</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_cephfs/">CephFS - <code class="docutils literal notranslate"><span class="pre">cephfs</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_cephobject/">Ceph Object - <code class="docutils literal notranslate"><span class="pre">cephobject</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_ceph/">Ceph RBD - <code class="docutils literal notranslate"><span class="pre">ceph</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_powerflex/">Dell PowerFlex - <code class="docutils literal notranslate"><span class="pre">powerflex</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_pure/">Pure Storage - <code class="docutils literal notranslate"><span class="pre">pure</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_dir/">Directory - <code class="docutils literal notranslate"><span class="pre">dir</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_lvm/">LVM - <code class="docutils literal notranslate"><span class="pre">lvm</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/storage_zfs/">ZFS - <code class="docutils literal notranslate"><span class="pre">zfs</span></code></a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../reference/networks/">Networks</a><input class="toctree-checkbox" id="toctree-checkbox-18" name="toctree-checkbox-18" role="switch" type="checkbox"/><label for="toctree-checkbox-18"><div class="visually-hidden">Toggle navigation of Networks</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../reference/network_bridge/">Bridge network</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/network_ovn/">OVN network</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/network_macvlan/">Macvlan network</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/network_physical/">Physical network</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/network_sriov/">SR-IOV network</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../reference/cluster_member_config/">Cluster configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/server_settings/">Production server settings</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/provided_metrics/">Provided metrics</a></li> <li class="toctree-l2"><a class="reference internal" href="../reference/permissions/">Permissions</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../restapi_landing/">REST API</a><input class="toctree-checkbox" id="toctree-checkbox-19" name="toctree-checkbox-19" role="switch" type="checkbox"/><label for="toctree-checkbox-19"><div class="visually-hidden">Toggle navigation of REST API</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../rest-api/">Main API documentation</a></li> <li class="toctree-l3"><a class="reference internal" href="../api/">Main API specification</a></li> <li class="toctree-l3"><a class="reference internal" href="../api-extensions/">Main API extensions</a></li> <li class="toctree-l3"><a class="reference internal" href="../events/">Events API documentation</a></li> <li class="toctree-l3"><a class="reference internal" href="../dev-lxd/">Instance API</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../reference/manpages/">Man pages</a><input class="toctree-checkbox" id="toctree-checkbox-20" name="toctree-checkbox-20" role="switch" type="checkbox"/><label for="toctree-checkbox-20"><div class="visually-hidden">Toggle navigation of Man pages</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../reference/manpages/lxc/"><code class="docutils literal notranslate"><span class="pre">lxc</span></code></a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../internals/">Internals</a><input class="toctree-checkbox" id="toctree-checkbox-21" name="toctree-checkbox-21" role="switch" type="checkbox"/><label for="toctree-checkbox-21"><div class="visually-hidden">Toggle navigation of Internals</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../environment/">Environment variables</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/uefi_variables/">UEFI variables for VMs</a></li> <li class="toctree-l3"><a class="reference internal" href="../daemon-behavior/">Daemon behavior</a></li> <li class="toctree-l3"><a class="reference internal" href="../syscall-interception/">System call interception</a></li> <li class="toctree-l3"><a class="reference internal" href="../userns-idmap/">User namespace setup</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/ovn-internals/">OVN implementation</a></li> <li class="toctree-l3"><a class="reference internal" href="../reference/vm_live_migration_internals/">VM live migration implementation</a></li> </ul> </li> <li class="toctree-l2"><a class="reference external" href="https://github.com/canonical/lxd">Project repository</a></li> <li class="toctree-l2"><a class="reference external" href="https://images.lxd.canonical.com">Image server</a></li> </ul> </li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="view-this-page"> <a class="muted-link" href="../_sources/contributing.md.txt" title="View this page"> <svg><use href="#svg-eye"></use></svg> <span class="visually-hidden">View this page</span> </a> </div> <div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main" id="furo-main-content"> <section id="how-to-contribute-to-lxd"> <h1>How to contribute to LXD<a class="headerlink" href="#how-to-contribute-to-lxd" title="Link to this heading">¶</a></h1> <p>The LXD team welcomes contributions through pull requests, issue reports, and discussions.</p> <ul class="simple"> <li><p>Contribute to the code or documentation, report bugs, or request features in the <a class="reference external" href="https://github.com/canonical/lxd">GitHub repository</a></p></li> <li><p>Ask questions or join discussions in the <a class="reference external" href="https://discourse.ubuntu.com/c/lxd/126">LXD forum</a>.</p></li> </ul> <p>Review the following guidelines before contributing to the project.</p> <section id="code-of-conduct"> <h2>Code of Conduct<a class="headerlink" href="#code-of-conduct" title="Link to this heading">¶</a></h2> <p>All contributors must adhere to the <a class="reference external" href="https://ubuntu.com/community/ethos/code-of-conduct">Ubuntu Code of Conduct</a>.</p> </section> <section id="license-and-copyright"> <h2>License and copyright<a class="headerlink" href="#license-and-copyright" title="Link to this heading">¶</a></h2> <p>All contributors must sign the <a class="reference external" href="https://ubuntu.com/legal/contributors">Canonical contributor license agreement (CCLA)</a>, which grants Canonical permission to use the contributions.</p> <ul class="simple"> <li><p>You retain copyright ownership of your contributions (no copyright assignment).</p></li> <li><p>By default, contributions are licensed under the project’s <strong>AGPL-3.0-only</strong> license.</p></li> <li><p>Exceptions:</p> <ul> <li><p>Canonical may import code under AGPL-3.0-only compatible licenses, such as Apache-2.0.</p></li> <li><p>Such code retains its original license and is marked as such in commit messages or file headers.</p></li> <li><p>Some files and commits are licensed under Apache-2.0 rather than AGPL-3.0-only. These are indicated in their package-level COPYING file, file header, or commit message.</p></li> </ul> </li> </ul> </section> <section id="pull-requests"> <h2>Pull requests<a class="headerlink" href="#pull-requests" title="Link to this heading">¶</a></h2> <p>Submit pull requests on GitHub at: <a class="reference external" href="https://github.com/canonical/lxd"><code class="docutils literal notranslate"><span class="pre">https://github.com/canonical/lxd</span></code></a>.</p> <p>All pull requests undergo review and must be approved before being merged into the main branch.</p> <section id="commit-structure"> <h3>Commit structure<a class="headerlink" href="#commit-structure" title="Link to this heading">¶</a></h3> <p>Use separate commits for different types of changes:</p> <div class="table-wrapper colwidths-auto docutils container"> <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head"><p>Type</p></th> <th class="head"><p>Affects files</p></th> <th class="head"><p>Commit message format</p></th> </tr> </thead> <tbody> <tr class="row-even"><td><p><strong>API extensions</strong></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">doc/api-extensions.md</span></code>, <code class="docutils literal notranslate"><span class="pre">shared/version/api.go</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">api:</span> <span class="pre">Add</span> <span class="pre">XYZ</span> <span class="pre">extension</span></code></p></td> </tr> <tr class="row-odd"><td><p><strong>Documentation</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">doc/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">doc:</span> <span class="pre">Update</span> <span class="pre">XYZ</span></code></p></td> </tr> <tr class="row-even"><td><p><strong>API structure</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">shared/api/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">shared/api:</span> <span class="pre">Add</span> <span class="pre">XYZ</span></code></p></td> </tr> <tr class="row-odd"><td><p><strong>Go client package</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">client/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">client:</span> <span class="pre">Add</span> <span class="pre">XYZ</span></code></p></td> </tr> <tr class="row-even"><td><p><strong>CLI changes</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">lxc/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">lxc/<command>:</span> <span class="pre">Change</span> <span class="pre">XYZ</span></code></p></td> </tr> <tr class="row-odd"><td><p><strong>LXD daemon</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">lxd/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">lxd/<package>:</span> <span class="pre">Add</span> <span class="pre">support</span> <span class="pre">for</span> <span class="pre">XYZ</span></code></p></td> </tr> <tr class="row-even"><td><p><strong>Tests</strong></p></td> <td><p>Files in <code class="docutils literal notranslate"><span class="pre">tests/</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">tests:</span> <span class="pre">Add</span> <span class="pre">test</span> <span class="pre">for</span> <span class="pre">XYZ</span></code></p></td> </tr> </tbody> </table> </div> <p>Depending on complexity, large changes might be further split into smaller, logical commits. This commit structure facilitates the review process and simplifies backporting fixes to stable branches.</p> </section> <section id="developer-certificate-of-origin-sign-off"> <h3>Developer Certificate of Origin sign-off<a class="headerlink" href="#developer-certificate-of-origin-sign-off" title="Link to this heading">¶</a></h3> <p>To ensure transparency and accountability in contributions to this project, all contributors must include a <strong>Signed-off-by</strong> line in their commits in accordance with DCO 1.1:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Developer</span> <span class="n">Certificate</span> <span class="n">of</span> <span class="n">Origin</span> <span class="n">Version</span> <span class="mf">1.1</span> <span class="n">Copyright</span> <span class="p">(</span><span class="n">C</span><span class="p">)</span> <span class="mi">2004</span><span class="p">,</span> <span class="mi">2006</span> <span class="n">The</span> <span class="n">Linux</span> <span class="n">Foundation</span> <span class="ow">and</span> <span class="n">its</span> <span class="n">contributors</span><span class="o">.</span> <span class="mi">660</span> <span class="n">York</span> <span class="n">Street</span><span class="p">,</span> <span class="n">Suite</span> <span class="mi">102</span><span class="p">,</span> <span class="n">San</span> <span class="n">Francisco</span><span class="p">,</span> <span class="n">CA</span> <span class="mi">94110</span> <span class="n">USA</span> <span class="n">Everyone</span> <span class="ow">is</span> <span class="n">permitted</span> <span class="n">to</span> <span class="n">copy</span> <span class="ow">and</span> <span class="n">distribute</span> <span class="n">verbatim</span> <span class="n">copies</span> <span class="n">of</span> <span class="n">this</span> <span class="n">license</span> <span class="n">document</span><span class="p">,</span> <span class="n">but</span> <span class="n">changing</span> <span class="n">it</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">allowed</span><span class="o">.</span> <span class="n">Developer</span><span class="s1">'s Certificate of Origin 1.1</span> <span class="n">By</span> <span class="n">making</span> <span class="n">a</span> <span class="n">contribution</span> <span class="n">to</span> <span class="n">this</span> <span class="n">project</span><span class="p">,</span> <span class="n">I</span> <span class="n">certify</span> <span class="n">that</span><span class="p">:</span> <span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="n">was</span> <span class="n">created</span> <span class="ow">in</span> <span class="n">whole</span> <span class="ow">or</span> <span class="ow">in</span> <span class="n">part</span> <span class="n">by</span> <span class="n">me</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="n">the</span> <span class="n">right</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">it</span> <span class="n">under</span> <span class="n">the</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="n">indicated</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">file</span><span class="p">;</span> <span class="ow">or</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="ow">is</span> <span class="n">based</span> <span class="n">upon</span> <span class="n">previous</span> <span class="n">work</span> <span class="n">that</span><span class="p">,</span> <span class="n">to</span> <span class="n">the</span> <span class="n">best</span> <span class="n">of</span> <span class="n">my</span> <span class="n">knowledge</span><span class="p">,</span> <span class="ow">is</span> <span class="n">covered</span> <span class="n">under</span> <span class="n">an</span> <span class="n">appropriate</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="n">the</span> <span class="n">right</span> <span class="n">under</span> <span class="n">that</span> <span class="n">license</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">that</span> <span class="n">work</span> <span class="k">with</span> <span class="n">modifications</span><span class="p">,</span> <span class="n">whether</span> <span class="n">created</span> <span class="ow">in</span> <span class="n">whole</span> <span class="ow">or</span> <span class="ow">in</span> <span class="n">part</span> <span class="n">by</span> <span class="n">me</span><span class="p">,</span> <span class="n">under</span> <span class="n">the</span> <span class="n">same</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="p">(</span><span class="n">unless</span> <span class="n">I</span> <span class="n">am</span> <span class="n">permitted</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">under</span> <span class="n">a</span> <span class="n">different</span> <span class="n">license</span><span class="p">),</span> <span class="k">as</span> <span class="n">indicated</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">file</span><span class="p">;</span> <span class="ow">or</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="n">was</span> <span class="n">provided</span> <span class="n">directly</span> <span class="n">to</span> <span class="n">me</span> <span class="n">by</span> <span class="n">some</span> <span class="n">other</span> <span class="n">person</span> <span class="n">who</span> <span class="n">certified</span> <span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="ow">or</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="ow">not</span> <span class="n">modified</span> <span class="n">it</span><span class="o">.</span> <span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="n">I</span> <span class="n">understand</span> <span class="ow">and</span> <span class="n">agree</span> <span class="n">that</span> <span class="n">this</span> <span class="n">project</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">contribution</span> <span class="n">are</span> <span class="n">public</span> <span class="ow">and</span> <span class="n">that</span> <span class="n">a</span> <span class="n">record</span> <span class="n">of</span> <span class="n">the</span> <span class="n">contribution</span> <span class="p">(</span><span class="n">including</span> <span class="nb">all</span> <span class="n">personal</span> <span class="n">information</span> <span class="n">I</span> <span class="n">submit</span> <span class="k">with</span> <span class="n">it</span><span class="p">,</span> <span class="n">including</span> <span class="n">my</span> <span class="n">sign</span><span class="o">-</span><span class="n">off</span><span class="p">)</span> <span class="ow">is</span> <span class="n">maintained</span> <span class="n">indefinitely</span> <span class="ow">and</span> <span class="n">may</span> <span class="n">be</span> <span class="n">redistributed</span> <span class="n">consistent</span> <span class="k">with</span> <span class="n">this</span> <span class="n">project</span> <span class="ow">or</span> <span class="n">the</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="n">involved</span><span class="o">.</span> </pre></div> </div> <section id="including-a-signed-off-by-line-in-your-commits"> <h4>Including a Signed-off-by line in your commits<a class="headerlink" href="#including-a-signed-off-by-line-in-your-commits" title="Link to this heading">¶</a></h4> <p>Every commit must include a <strong>Signed-off-by</strong> line, even when part of a larger set of contributions. To do this, use the <code class="docutils literal notranslate"><span class="pre">-s</span></code> flag when committing:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -s -m "Your commit message" </pre></div> </div> <p>This automatically adds the following to your commit message:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Your</span> <span class="n">Name</span> <span class="o"><</span><span class="n">your</span><span class="o">.</span><span class="n">email</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">></span> </pre></div> </div> <p>By including this line, you acknowledge your agreement to the DCO 1.1 for that specific contribution.</p> <ul class="simple"> <li><p>Use a valid name and email address—anonymous contributions are not accepted.</p></li> <li><p>Ensure your email matches the one associated with your GitHub account.</p></li> </ul> </section> </section> <section id="commit-signature-verification"> <h3>Commit signature verification<a class="headerlink" href="#commit-signature-verification" title="Link to this heading">¶</a></h3> <p>In addition to the sign-off requirement, contributors must also cryptographically sign their commits to verify authenticity. See: <a class="reference external" href="https://docs.github.com/en/authentication/managing-commit-signature-verification">GitHub’s documentation on commit signature verification</a>.</p> </section> <section id="make-generated-files"> <h3>Make-generated files<a class="headerlink" href="#make-generated-files" title="Link to this heading">¶</a></h3> <p>Some changes require regenerating certain files using Makefile commands.</p> <p>After you run any of the commands below, you’ll be prompted whether to commit the changes. If you respond <code class="docutils literal notranslate"><span class="pre">Y</span></code>, only the re-generated files are committed—any other staged files are ignored.</p> <section id="formatting"> <h4>Formatting<a class="headerlink" href="#formatting" title="Link to this heading">¶</a></h4> <p>If you modify any Go source files, format them:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make update-fmt </pre></div> </div> </section> <section id="cli-tool-string-updates"> <h4>CLI tool string updates<a class="headerlink" href="#cli-tool-string-updates" title="Link to this heading">¶</a></h4> <p>If you modify CLI strings in <code class="docutils literal notranslate"><span class="pre">lxc/</span></code>, regenerate and commit translation files:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make i18n </pre></div> </div> </section> <section id="api-updates"> <h4>API updates<a class="headerlink" href="#api-updates" title="Link to this heading">¶</a></h4> <p>If you modify the LXD API (<code class="docutils literal notranslate"><span class="pre">shared/api</span></code>), regenerate and commit the Swagger YAML file (<code class="docutils literal notranslate"><span class="pre">doc/rest-api.yaml</span></code>) used for API reference documentation:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make update-api </pre></div> </div> </section> <section id="configuration-options-updates"> <h4>Configuration options updates<a class="headerlink" href="#configuration-options-updates" title="Link to this heading">¶</a></h4> <p>If you add or update configuration options, regenerate and commit the documentation metadata files (<code class="docutils literal notranslate"><span class="pre">lxd/metadata/configuration.json</span></code> and <code class="docutils literal notranslate"><span class="pre">doc/metadata.txt</span></code>):</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make update-metadata </pre></div> </div> </section> <section id="development-environment-setup"> <h4>Development environment setup<a class="headerlink" href="#development-environment-setup" title="Link to this heading">¶</a></h4> <p>Several pieces of software are needed in order to build and test LXD. Here is an easy way to create a virtual-machine to use as a development environment. LXD itself is needed to power that virtual-machine so install it first: <a class="reference internal" href="../installing/#installing"><span class="std std-ref">How to install LXD</span></a>.</p> <p>Once LXD is installed and <a class="reference internal" href="../howto/initialize/#initialize"><span class="std std-ref">initialized</span></a>, a special profile (<code class="docutils literal notranslate"><span class="pre">lxd-test</span></code>) needs to be loaded. The profile requires includes a <code class="docutils literal notranslate"><span class="pre">lxd-git</span></code> device (see <a class="reference internal" href="../reference/devices_disk/#devices-disk-types"><span class="std std-ref">Types of disk devices</span></a> for details) that will share LXD’s git repository with the virtual-machine. Since this path is specific to your environment you need to adjust it when loading the profile:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># this needs to be run from inside the git repostory</span> <span class="nv">GIT_ROOT</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>git<span class="w"> </span>rev-parse<span class="w"> </span>--show-toplevel<span class="k">)</span><span class="s2">"</span> <span class="c1"># create or edit the profile based on the provided template</span> lxc<span class="w"> </span>profile<span class="w"> </span>list<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>-qwF<span class="w"> </span>lxd-test<span class="w"> </span><span class="o">||</span><span class="w"> </span>lxc<span class="w"> </span>profile<span class="w"> </span>create<span class="w"> </span>lxd-test sed<span class="w"> </span><span class="s2">"s|@@PATH_TO_LXD_GIT@@|</span><span class="si">${</span><span class="nv">GIT_ROOT</span><span class="si">}</span><span class="s2">|"</span><span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">GIT_ROOT</span><span class="si">}</span><span class="s2">/doc/lxd-test.yaml"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>lxc<span class="w"> </span>profile<span class="w"> </span>edit<span class="w"> </span>lxd-test </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">lxd-test</span></code> profile assigns CPU and memory limits similar to those available in free GitHub Action runners. Those can be adapted to the specifications of a more modest physical machine:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>lxc<span class="w"> </span>profile<span class="w"> </span><span class="nb">set</span><span class="w"> </span>lxd-test<span class="w"> </span>limits.cpu<span class="o">=</span><span class="m">2</span> lxc<span class="w"> </span>profile<span class="w"> </span><span class="nb">set</span><span class="w"> </span>lxd-test<span class="w"> </span>limits.memory<span class="o">=</span>4GiB lxc<span class="w"> </span>profile<span class="w"> </span>device<span class="w"> </span><span class="nb">set</span><span class="w"> </span>lxd-test<span class="w"> </span>root<span class="w"> </span><span class="nv">size</span><span class="o">=</span>8GiB </pre></div> </div> <p>This profile can then be used to launch an Ubuntu Noble VM and start using it:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>lxc<span class="w"> </span>launch<span class="w"> </span>ubuntu-minimal-daily:24.04<span class="w"> </span>v1<span class="w"> </span>--vm<span class="w"> </span>-p<span class="w"> </span>lxd-test sleep<span class="w"> </span><span class="m">30</span> <span class="c1"># this may take a while as many packages need to be installed</span> lxc<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>v1<span class="w"> </span>--<span class="w"> </span>cloud-init<span class="w"> </span>status<span class="w"> </span>--wait<span class="w"> </span>--long </pre></div> </div> <p>Then it is possible to build all the dependencies, LXD binaries and even run tests either automatically or manually:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># start a root shell in the VM</span> lxc<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>v1<span class="w"> </span>--<span class="w"> </span>bash <span class="c1"># go into the git repo</span> <span class="nb">cd</span><span class="w"> </span>lxd <span class="c1"># build deps and LXD binaries</span> make<span class="w"> </span>deps<span class="w"> </span><span class="o">&&</span><span class="w"> </span>make <span class="c1"># get an interactive test shell session with all the needed environment variables to use and test LXD</span> make<span class="w"> </span>test-shell <span class="c1"># run the `exec` and `query` tests</span> ./main.sh<span class="w"> </span><span class="nb">exec</span> ./main.sh<span class="w"> </span>query <span class="c1"># or manually interact with LXD, for example:</span> lxc<span class="w"> </span>launch<span class="w"> </span>ubuntu:24.04<span class="w"> </span>u1 lxc<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>u1<span class="w"> </span>--<span class="w"> </span>hostname lxc<span class="w"> </span>delete<span class="w"> </span>--force<span class="w"> </span>u1 <span class="c1"># for a barebones test instance with just busybox (note: no IP automatically configured)</span> ./deps/import-busybox<span class="w"> </span>--alias<span class="w"> </span>testimage lxc<span class="w"> </span>launch<span class="w"> </span>testimage<span class="w"> </span>c1 </pre></div> </div> <p>At this point you might want to learn more on <a class="reference internal" href="../debugging/"><span class="doc">How to debug LXD</span></a>.</p> </section> </section> </section> <section id="contribute-to-the-code"> <h2>Contribute to the code<a class="headerlink" href="#contribute-to-the-code" title="Link to this heading">¶</a></h2> <p>Follow the steps below to set up your development environment and start working on new LXD features.</p> <section id="install-lxd-from-source"> <h3>Install LXD from source<a class="headerlink" href="#install-lxd-from-source" title="Link to this heading">¶</a></h3> <p>To build the dependencies, follow the instructions in <a class="reference internal" href="../installing/#id1"><span class="std std-ref">Install LXD from source</span></a>.</p> </section> <section id="add-your-fork-as-a-remote"> <h3>Add your fork as a remote<a class="headerlink" href="#add-your-fork-as-a-remote" title="Link to this heading">¶</a></h3> <p>After setting up your build environment, add your GitHub fork as a remote and fetch the latest updates:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git remote add myfork git@github.com:<your_username>/lxd.git git remote update </pre></div> </div> <p>Then switch to the main branch of your fork:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git switch myfork/main </pre></div> </div> </section> <section id="build-lxd"> <h3>Build LXD<a class="headerlink" href="#build-lxd" title="Link to this heading">¶</a></h3> <p>Now you can build your fork of the project by running:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make </pre></div> </div> <p>Before making changes, create a new branch on your fork:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>switch<span class="w"> </span>-c<span class="w"> </span><name_of_your_new_branch> </pre></div> </div> <p>Set up tracking for the new branch to make future pushes easier:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>myfork<span class="w"> </span><name_of_your_new_branch> </pre></div> </div> </section> <section id="important-notes-for-new-lxd-contributors"> <h3>Important notes for new LXD contributors<a class="headerlink" href="#important-notes-for-new-lxd-contributors" title="Link to this heading">¶</a></h3> <ul class="simple"> <li><p>Persistent data is stored in the <code class="docutils literal notranslate"><span class="pre">LXD_DIR</span></code> directory, which is created by running <code class="docutils literal notranslate"><span class="pre">lxd</span> <span class="pre">init</span></code>.</p> <ul> <li><p>By default, <code class="docutils literal notranslate"><span class="pre">LXD_DIR</span></code> is located at <code class="docutils literal notranslate"><span class="pre">/var/lib/lxd</span></code> (for non-snap installations) or <code class="docutils literal notranslate"><span class="pre">/var/snap/lxd/common/lxd</span></code> (for snap users).</p></li> <li><p>To prevent version conflicts, consider setting a separate <code class="docutils literal notranslate"><span class="pre">LXD_DIR</span></code> for your development fork.</p></li> </ul> </li> <li><p>Binaries compiled from your source are placed in <code class="docutils literal notranslate"><span class="pre">$(go</span> <span class="pre">env</span> <span class="pre">GOPATH)/bin</span></code> by default.</p> <ul> <li><p>When testing, explicitly invoke these binaries instead of the global <code class="docutils literal notranslate"><span class="pre">lxd</span></code> you might have installed.</p></li> <li><p>For convenience, you can create an alias in your <code class="docutils literal notranslate"><span class="pre">~/.bashrc</span></code> to call these binaries with the appropriate flags.</p></li> </ul> </li> <li><p>If you have a <code class="docutils literal notranslate"><span class="pre">systemd</span></code> service running LXD from a previous installation, consider disabling it to prevent version conflicts with your development build.</p></li> </ul> </section> </section> <section id="contribute-to-the-documentation"> <h2>Contribute to the documentation<a class="headerlink" href="#contribute-to-the-documentation" title="Link to this heading">¶</a></h2> <p>We strive to make LXD as easy and straightforward to use as possible. To achieve this, our documentation aims to provide the information users need, cover all common use cases, and answer typical questions.</p> <p>You can contribute to the documentation in several ways. We appreciate your help!</p> <section id="ways-to-contribute"> <h3>Ways to contribute<a class="headerlink" href="#ways-to-contribute" title="Link to this heading">¶</a></h3> <dl class="simple myst"> <dt>Document new features or improvements you contribute to the code.</dt><dd><ul class="simple"> <li><p>Submit documentation updates in pull requests alongside your code changes. We will review and merge them together with the code.</p></li> </ul> </dd> <dt>Clarify concepts or common questions based on your own experience.</dt><dd><ul class="simple"> <li><p>Submit a pull request with your documentation improvements.</p></li> </ul> </dd> <dt>Report documentation issues by opening an issue on <a class="reference external" href="https://github.com/canonical/lxd/issues">GitHub</a>.</dt><dd><ul class="simple"> <li><p>We will evaluate and update the documentation as needed.</p></li> </ul> </dd> <dt>Ask questions or suggest improvements in the <a class="reference external" href="https://discourse.ubuntu.com/c/lxd">LXD forum</a>.</dt><dd><ul class="simple"> <li><p>We monitor discussions and update the documentation when necessary.</p></li> </ul> </dd> <dt>Join discussions in the <code class="docutils literal notranslate"><span class="pre">#lxd</span></code> channel on IRC via <a class="reference external" href="https://web.libera.chat/#lxd">Libera Chat</a>.</dt><dd><ul class="simple"> <li><p>While we cannot guarantee responses to IRC posts, we monitor the channel and use feedback to improve the documentation.</p></li> </ul> </dd> </dl> <p>If you contribute images to <code class="docutils literal notranslate"><span class="pre">doc/images</span></code>:</p> <ul class="simple"> <li><p>Use <strong>SVG</strong> or <strong>PNG</strong> formats.</p></li> <li><p>Optimize PNG images for smaller file size using a tool like <a class="reference external" href="https://tinypng.com/">TinyPNG</a> (web-based), <a class="reference external" href="https://optipng.sourceforge.net/">OptiPNG</a> (CLI-based), or similar.</p></li> </ul> </section> <section id="documentation-framework"> <h3>Documentation framework<a class="headerlink" href="#documentation-framework" title="Link to this heading">¶</a></h3> <p>LXD’s documentation is built with <a class="reference external" href="https://www.sphinx-doc.org">Sphinx</a> and hosted on <a class="reference external" href="https://about.readthedocs.com/">Read the Docs</a>.</p> <p>It is written in <a class="reference external" href="https://commonmark.org/">Markdown</a> with <a class="reference external" href="https://myst-parser.readthedocs.io/">MyST</a> extensions. For syntax help and guidelines, see the <a class="reference external" href="https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/">MyST style guide</a> and the <a class="reference external" href="https://documentation.ubuntu.com/lxd/latest/doc-cheat-sheet-myst/">documentation cheat sheet</a> (<a class="reference external" href="https://raw.githubusercontent.com/canonical/lxd/main/doc/doc-cheat-sheet-myst.md">source</a>).</p> <p>For structuring, the documentation uses the <a class="reference external" href="https://diataxis.fr/">Diátaxis</a> approach.</p> </section> <section id="build-the-documentation"> <h3>Build the documentation<a class="headerlink" href="#build-the-documentation" title="Link to this heading">¶</a></h3> <p>To build the documentation, run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc</span></code> from the root directory of the repository. This command installs the required tools and renders the output to the <code class="docutils literal notranslate"><span class="pre">doc/_build/</span></code> directory. To update the documentation for changed files only (without re-installing the tools), run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-incremental</span></code>.</p> <p>Before opening a pull request, make sure that the documentation builds without any warnings (warnings are treated as errors). To preview the documentation locally, run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-serve</span></code> and go to <a class="reference external" href="http://localhost:8000"><code class="docutils literal notranslate"><span class="pre">http://localhost:8000</span></code></a> to view the rendered documentation.</p> <p>When you open a pull request, a preview of the documentation hosted by Read the Docs is built automatically. To see this, view the details for the <code class="docutils literal notranslate"><span class="pre">docs/readthedocs.com:canonical-lxd</span></code> check on the pull request. Others can also use this preview to validate your changes.</p> </section> <section id="automatic-documentation-checks"> <h3>Automatic documentation checks<a class="headerlink" href="#automatic-documentation-checks" title="Link to this heading">¶</a></h3> <p>GitHub runs automatic checks on the documentation to verify the spelling, the validity of links, correct formatting of the Markdown files, and the use of inclusive language.</p> <p>You can (and should!) run these tests locally before pushing your changes:</p> <ul class="simple"> <li><p>Check the spelling: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-spellcheck</span></code> (or <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-spelling</span></code> to first build the documentation and then check it)</p></li> <li><p>Check the validity of links: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-linkcheck</span></code></p></li> <li><p>Check the Markdown formatting: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-lint</span></code></p></li> <li><p>Check for inclusive language: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc-woke</span></code></p></li> </ul> </section> <section id="document-instructions-how-to-guides"> <h3>Document instructions (how-to guides)<a class="headerlink" href="#document-instructions-how-to-guides" title="Link to this heading">¶</a></h3> <p>LXD can be used with different clients, primarily the command-line interface (CLI), API, and UI. The documentation contains instructions for all of these, so when adding or updating how-to guides, remember to update the documentation for all clients.</p> <section id="using-tabs-for-client-specific-information"> <h4>Using tabs for client-specific information<a class="headerlink" href="#using-tabs-for-client-specific-information" title="Link to this heading">¶</a></h4> <p>When instructions differ between clients, use tabs to organize them:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>````{tabs} ```{group-tab} CLI [...] ``` ```{group-tab} API [...] ``` ```{group-tab} UI [...] ``` ```` </pre></div> </div> <div class="admonition tip"> <p class="admonition-title">Tip</p> <p>You might need to increase the number of backticks (`) if there are code blocks or other directives in the tab content.</p> </div> </section> <section id="guidelines-for-writing-instructions"> <h4>Guidelines for writing instructions<a class="headerlink" href="#guidelines-for-writing-instructions" title="Link to this heading">¶</a></h4> <dl class="simple myst"> <dt>CLI instructions</dt><dd><ul class="simple"> <li><p>Link to the relevant <code class="docutils literal notranslate"><span class="pre">lxc</span></code> command reference. Example: <code class="docutils literal notranslate"><span class="pre">[`lxc</span> <span class="pre">init`](lxc_init.md)</span></code></p></li> <li><p>You don’t need to document all available command flags, but mention any that are especially relevant.</p></li> <li><p>Examples are very helpful, so add a few if it makes sense.</p></li> </ul> </dd> <dt>API instructions</dt><dd><ul class="simple"> <li><p>When possible, use <a class="reference internal" href="../reference/manpages/lxc/query/#lxc-query-md"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">lxc</span> <span class="pre">query</span></code></span></a> to demonstrate API calls. For complex calls, use <code class="docutils literal notranslate"><span class="pre">curl</span></code> or other widely available tools.</p></li> <li><p>In the request data, include all required fields but keep it minimal—there’s no need to list every possible field.</p></li> <li><p>Link to the API call reference. Example: <code class="docutils literal notranslate"><span class="pre">[`POST</span> <span class="pre">/1.0/instances`](swagger:/instances/instances_post)</span></code></p></li> </ul> </dd> <dt>UI instructions</dt><dd><ul class="simple"> <li><p>Use screenshots sparingly—they are difficult to keep up to date.</p></li> <li><p>When referring to labels in the UI, use the <code class="docutils literal notranslate"><span class="pre">{guilabel}</span></code> role. Example: <code class="docutils literal notranslate"><span class="pre">To</span> <span class="pre">create</span> <span class="pre">an</span> <span class="pre">instance,</span> <span class="pre">go</span> <span class="pre">to</span> <span class="pre">the</span> <span class="pre">{guilabel}`Instances`</span> <span class="pre">section</span> <span class="pre">and</span> <span class="pre">click</span> <span class="pre">{guilabel}`Create</span> <span class="pre">instance`.</span></code></p></li> </ul> </dd> </dl> </section> </section> <section id="document-configuration-options"> <h3>Document configuration options<a class="headerlink" href="#document-configuration-options" title="Link to this heading">¶</a></h3> <p>Configuration options are documented by comments in the Go code. These comments are extracted automatically.</p> <section id="adding-or-modifying-configuration-options"> <h4>Adding or modifying configuration options<a class="headerlink" href="#adding-or-modifying-configuration-options" title="Link to this heading">¶</a></h4> <ul class="simple"> <li><p>Look for comments that start with <code class="docutils literal notranslate"><span class="pre">lxdmeta:generate</span></code> in the code.</p></li> <li><p>When adding or modifying a configuration option, include the corresponding documentation comment.</p></li> <li><p>Refer to the <a class="reference external" href="https://github.com/canonical/lxd/blob/main/lxd/lxd-metadata/README.md"><code class="docutils literal notranslate"><span class="pre">lxd-metadata</span></code> README file</a> for formatting guidelines.</p></li> <li><p>When you add or modify configuration options, you must re-generate <code class="docutils literal notranslate"><span class="pre">doc/metadata.txt</span></code> and <code class="docutils literal notranslate"><span class="pre">lxd/metadata/configuration.json</span></code>. See the <a class="reference internal" href="#configuration-options-updates"><span class="std std-ref">Configuration options updates</span></a> section for instructions.</p></li> </ul> </section> <section id="including-configuration-options-in-documentation"> <h4>Including configuration options in documentation<a class="headerlink" href="#including-configuration-options-in-documentation" title="Link to this heading">¶</a></h4> <p>The documentation pulls sections from <code class="docutils literal notranslate"><span class="pre">doc/metadata.txt</span></code> to display a group of configuration options. For example, to include the core server options, use:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>% Include content from [metadata.txt](metadata.txt) ```{include} metadata.txt :start-after: <!-- config group server-core start --> :end-before: <!-- config group server-core end --> ``` </pre></div> </div> </section> <section id="when-to-update-documentation-files"> <h4>When to update documentation files<a class="headerlink" href="#when-to-update-documentation-files" title="Link to this heading">¶</a></h4> <ul class="simple"> <li><p>If you add a new option to an existing group, no changes to the documentation files are needed, aside from <a class="reference internal" href="#configuration-options-updates">re-generating <code class="docutils literal notranslate"><span class="pre">metadata.txt</span></code></a>. The option will be included automatically.</p></li> <li><p>If you define a new group, to add it to the documentation, you must add an <code class="docutils literal notranslate"><span class="pre">{include}</span></code> directive to the appropriate Markdown file in <code class="docutils literal notranslate"><span class="pre">doc/</span></code>.</p></li> </ul> </section> </section> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../explanation/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Explanation</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../support/"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">How to get support</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> Copyright © 2014-2025 LXD contributors </div> <div class="last-updated"> Last updated on Sep 08, 2025</div> <div class="show-source"> <a class="muted-link" href="../_sources/contributing.md.txt" rel="nofollow">Show source</a> </div> </div> <div> <a class="display-contributors">Thanks to the 11 contributors!</a> <div id="overlay"></div> <ul class="all-contributors"> <li> <a href="https://github.com/canonical/lxd/commit/7f485d401e36c4d19ca540f8edd397a4f1c0db0c" class="contributor">Alberto Donato</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/ec0b73fcca9109ba09f9f878348e6d3a001c1d56" class="contributor">Gabriel Mougard</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/6885be9401817a07764217134baa20ec2be3ee00" class="contributor">Grayson112233</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/18b4df801a55d4089c10e989410fe7efe5e8eb5c" class="contributor">KATOH Yasufumi</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/f5eaa6e9dcdd29c409aa0d746229ea39ee3bdb10" class="contributor">Mark Laing</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/8f2f29b51feeec0830c031df03d8223d7f22ee62" class="contributor">Minae Lee</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/dd7abeffe5ba32a963585f8deccdd67f20193717" class="contributor">Ruth Fuchss</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/4510d37295833fc84004a67b956b71e23e28e332" class="contributor">Simon Deziel</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/3e07561990b233e816311bfe36c424db8ad19873" class="contributor">Stéphane Graber</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/eb2de6562536d4b73704a882202889e3c793a7a0" class="contributor">Thomas Parrott</a> </li> <li> <a href="https://github.com/canonical/lxd/commit/c4eb17e5968fda9e86da4acd4aa44c9f38af8ae2" class="contributor">Tom Parrott</a> </li> </ul> </div> <div class="right-details"> <div class="ask-discourse"> <a class="muted-link" href="https://discourse.ubuntu.com/c/lxd/">Ask a question on Discourse</a> </div> <div class="ask-matrix"> <a class="muted-link" href="https://matrix.to/#/#documentation:ubuntu.com">Ask a question on Matrix</a> </div> <div class="issue-github"> <a class="muted-link" href="https://github.com/canonical/lxd/issues/new?title=doc%3A+ADD+A+TITLE&body=DESCRIBE+THE+ISSUE%0A%0A---%0ADocument: contributing.md">Open a GitHub issue for this page</a> </div> <div class="edit-github"> <a class="muted-link" href="https://github.com/canonical/lxd/edit/main/doc/contributing.md">Edit this page on GitHub</a> </div> </div> </div> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> Contents </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">How to contribute to LXD</a><ul> <li><a class="reference internal" href="#code-of-conduct">Code of Conduct</a></li> <li><a class="reference internal" href="#license-and-copyright">License and copyright</a></li> <li><a class="reference internal" href="#pull-requests">Pull requests</a><ul> <li><a class="reference internal" href="#commit-structure">Commit structure</a></li> <li><a class="reference internal" href="#developer-certificate-of-origin-sign-off">Developer Certificate of Origin sign-off</a><ul> <li><a class="reference internal" href="#including-a-signed-off-by-line-in-your-commits">Including a Signed-off-by line in your commits</a></li> </ul> </li> <li><a class="reference internal" href="#commit-signature-verification">Commit signature verification</a></li> <li><a class="reference internal" href="#make-generated-files">Make-generated files</a><ul> <li><a class="reference internal" href="#formatting">Formatting</a></li> <li><a class="reference internal" href="#cli-tool-string-updates">CLI tool string updates</a></li> <li><a class="reference internal" href="#api-updates">API updates</a></li> <li><a class="reference internal" href="#configuration-options-updates">Configuration options updates</a></li> <li><a class="reference internal" href="#development-environment-setup">Development environment setup</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#contribute-to-the-code">Contribute to the code</a><ul> <li><a class="reference internal" href="#install-lxd-from-source">Install LXD from source</a></li> <li><a class="reference internal" href="#add-your-fork-as-a-remote">Add your fork as a remote</a></li> <li><a class="reference internal" href="#build-lxd">Build LXD</a></li> <li><a class="reference internal" href="#important-notes-for-new-lxd-contributors">Important notes for new LXD contributors</a></li> </ul> </li> <li><a class="reference internal" href="#contribute-to-the-documentation">Contribute to the documentation</a><ul> <li><a class="reference internal" href="#ways-to-contribute">Ways to contribute</a></li> <li><a class="reference internal" href="#documentation-framework">Documentation framework</a></li> <li><a class="reference internal" href="#build-the-documentation">Build the documentation</a></li> <li><a class="reference internal" href="#automatic-documentation-checks">Automatic documentation checks</a></li> <li><a class="reference internal" href="#document-instructions-how-to-guides">Document instructions (how-to guides)</a><ul> <li><a class="reference internal" href="#using-tabs-for-client-specific-information">Using tabs for client-specific information</a></li> <li><a class="reference internal" href="#guidelines-for-writing-instructions">Guidelines for writing instructions</a></li> </ul> </li> <li><a class="reference internal" href="#document-configuration-options">Document configuration options</a><ul> <li><a class="reference internal" href="#adding-or-modifying-configuration-options">Adding or modifying configuration options</a></li> <li><a class="reference internal" href="#including-configuration-options-in-documentation">Including configuration options in documentation</a></li> <li><a class="reference internal" href="#when-to-update-documentation-files">When to update documentation files</a></li> </ul> </li> </ul> </li> </ul> </li> </ul> </div> </div> <div class="relatedlinks-title-container"> <span class="relatedlinks-title"> Related links </span> </div> <div class="relatedlinks-container"> <div class="relatedlinks"> <ul><li><a href="https://www.youtube.com/watch?v=pqV0Z1qwbkg" target="_blank">LXD's development process - YouTube</a></li></ul> </div> </div> </div> </aside> </div> </div><script src="../_static/jquery.js?v=5d32c60e"></script> <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../_static/documentation_options.js?v=187304be"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/scripts/furo.js?v=46bd48cc"></script> <script src="../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../_static/copybutton.js?v=f281be69"></script> <script src="../_static/config-options.js"></script> <script src="../_static/design-tabs.js?v=f930bc37"></script> <script src="../_static/header-nav.js?v=e117ad08"></script> <script src="../_static/footer.js?v=5acea47a"></script> <script src="../_static/github_issue_links.js?v=32bb732f"></script> <script src="../_static/js/bundle.js?v=a4d88309"></script> <script> const github_url = "https://github.com/canonical/lxd"; </script> </body> </html>
Copyright ©2k19 -
Hexid
|
Tex7ure