## 1. Project Overview & Quickstart (canonical/snapcraft) ## File: README.md # Snapcraft [![Snapcraft][snapcraft-badge]][snapcraft-site] [![Documentation Status][rtd-badge]][rtd-latest] [![Spread tests][gha-spread-badge]][gha-spread] [![Codecov Status][codecov-badge]][codecov-status] [![Ruff status][ruff-badge]][ruff-site] **Snapcraft** is the command-line build tool for packaging and distributing software and apps in the snap container format. It solves the problems of dependency management and architecture support by bundling all of a software's libraries into the container itself, and gives developers a way to package any app, program, toolkit, or library for all major Linux distributions and IoT devices. ## Basic usage A snap's build configuration is stored in simple language as a project file called `snapcraft.yaml`, making it easy to add as a new package format to your existing code base. From the root of the code base of any software project, Snapcraft creates a minimal `snapcraft.yaml` with: ```bash snapcraft init ``` After you add all your project's build and runtime details to the project file, bundle your project into a snap with: ```bash snapcraft pack ``` Your project can be registered on public and private app stores, including the Snap Store: ```bash snapcraft register ``` Snap versions and revisions, including parallel releases, are published to the store with: ```bash snapcraft upload ``` If you're interested in learning more about the Snapcraft commands and how to compose a project file, try [crafting your first snap](https://documentation.ubuntu.com/snapcraft/stable/tutorials/craft-a-snap). ## Installation Snapcraft is available on all major Linux distributions, Windows, and macOS. Snapcraft itself has first-class support as a snap. On snap-ready systems, you can install it on the command line with: ```bash sudo snap install snapcraft --classic ``` For complete installation, you need an additional Linux container tool. Snapcraft can also be installed as a traditional package on many popular Linux repositories. If you need help with either, the documentation covers how to [set up Snapcraft](https://documentation.ubuntu.com/snapcraft/stable/how-to/setup/set-up-snapcraft). ## Documentation The [Snapcraft documentation](https://documentation.ubuntu.com/snapcraft/stable) provides guidance and learning material about the full process of building a project file, debugging snaps, resolving interfaces, the command reference, and much more. ## Community and support We are a growing community of crafters who build snaps for all Linux software. Ask your questions about Snapcraft and what's on the horizon, and see who's working on what in the [Snapcraft Forum](https://forum.snapcraft.io) and on the [Snapcraft Matrix channel](https://matrix.to/#/#snapcraft:ubuntu.com). You can report any issues or bugs on the project's [GitHub repository](https://github.com/canonical/snapcraft/issues). Snapcraft is covered by the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). ## Contribute to Snapcraft Snapcraft is open source and part of the Canonical family. We would love your help. If you're interested, start with the [contribution guide](CONTRIBUTING.md). We welcome any suggestions and help with the docs. The [Canonical Open Documentation Academy](https://github.com/canonical/open-documentation-academy) is the hub for doc development, including Snapcraft docs. No prior coding experience is required. ## License and copyright Snapcraft is released under the [GPL-3.0 license](LICENSE). © 2015-2025 Canonical Ltd. [snapcraft-badge]: https://snapcraft.io/snapcraft/badge.svg [snapcraft-site]: https://snapcraft.io/snapcraft [rtd-badge]: https://readthedocs.com/projects/canonical-snapcraft/badge/?version=latest [rtd-latest]: https://documentation.ubuntu.com/snapcraft/latest/?badge=latest [gha-spread-badge]: https://github.com/canonical/snapcraft/actions/workflows/spread-manual.yaml/badge.svg?branch=main [gha-spread]: https://github.com/canonical/snapcraft/actions/workflows/spread-manual.yaml [ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json [ruff-site]: https://github.com/astral-sh/ruff [codecov-badge]: https://codecov.io/github/canonical/snapcraft/coverage.svg?branch=master [codecov-status]: https://codecov.io/github/canonical/snapcraft?branch=master --- ## File: docker/README.md # Docker images for `snapcraft` OCI-compliant container images and their sources are officially supported by the https://github.com/canonical/snapcraft-rocks/ project. To build a snap with the docker container, you need to choose an image that matches snap `base`. For example, to build `base: core24` snap: docker run -it -v `pwd`:/project ghcr.io/canonical/snapcraft:8_core24 - `8` in `8_core24` is the version of snapcraft. - `\; -v` construction at the end is required to see `snapcraft` output. For more details, see official `snapcraft-rocks` repo from Canonical. ### Building snaps with `podman` `podman` was born as a rootless alternative to Docker. It is default on Fedora to have `podman` instead of Docker, but SELinux there doesn't allow containers to write to volumes, so we just turn this "feature" off with `--security-opt label=disable`. ```sh podman run -it --rm --security-opt label=disable \ -v `pwd`:/project ghcr.io/canonical/snapcraft:8_core24 \; -v ``` --- ## File: docs/explanation/bases.rst .. _explanation-bases: About bases =========== Snaps declare a base in their project file. The base defines the feature set used by Snapcraft, the ``snapcraft.yaml`` project file, the environment where the snap is built, and which base snap is used at runtime. ``base`` and ``build-base`` --------------------------- If ``build-base`` is defined , then the ``build-base`` will determine the environment where the snap is built. If ``build-base`` is not defined, the ``base`` will determine the environment where the snap is built. For example, ``base: core26`` will build a snap in an Ubuntu 26.04 LTS environment with the core26 snap installed. Stage packages will be installed from the 26.04 repository. ``build-base: devel`` will build a snap using the upcoming Ubuntu release in development. This is defined as the Ubuntu image with the ``devel`` alias in the `Ubuntu buildd image server`_. For ``base: bare`` snaps, a ``build-base`` is required to determine the feature set, build environment, and ``snapcraft.yaml`` schema. .. _base-snaps: Base snaps ---------- A base snap is a special kind of snap that provides a run-time environment with a cardinal set of libraries that are common to most applications. They're transparent to users, but they need to be considered and specified when building a snap. Mounting -------- For strictly confined snaps, the base snap mounts itself as the root filesystem within a snap's runtime environment. When an application runs, the base's library paths are searched directly after the paths for that snap. For :ref:`classically-confined ` snaps, the base snap is not mounted as the root filesystem. The base snap is mounted as ``/snap//``, so the snap can still load libraries from the base snap. Choosing a base --------------- Core26 is the recommended base for most snaps. Much like choosing a distribution base for a project or server, the best base for an application is dependent on an application's requirements and which plugins or extensions a base supports. If there are specific dependencies that cannot be easily met then the next highest base, core24, is a valid and supported alternative. Snapcraft :ref:`explanation-extensions` enable bundling a set of common requirements into a snap, such as for running KDE Plasma or GNOME applications. Extensions support specific bases. :ref:`how-to-list-extensions` to view the latest extensions and which bases they're compatible with. ``bare`` is the recommended base for fully statically linked snaps because they will not have access to a base snap when running. The snap will have a smaller footprint at runtime because it does not require a base snap to be downloaded, installed, and mounted. .. _base-snap-explanation: Building a base snap -------------------- While uncommon, developers can build their own base snap. They are responsible for maintenance and updates, in particular: * bases need to be built from stable packages * ABI compatibility cannot broken (in other words, never replace symbols or libraries, and be strict) * security updates must be proactive `Ubuntu Core`_ systems need a base snap. These base snaps must be bootable and include ``systemd``. .. _`Ubuntu buildd image server`: https://cloud-images.ubuntu.com/buildd/daily/ --- ## File: docs/explanation/classic-confinement.rst .. _explanation-classic-confinement: Classic confinement =================== This page is for software developers who intend or need to craft their snaps classically, and provides explanations and examples on what happens to classic snaps at build-time. Requirements ------------ Snapcraft determines confinement based on the value of the ``confinement`` key in the project file. For classic confinement, it must be set as ``confinement: classic``. There are no further requirements for the configuration -- when Snapcraft builds the snap, it won't be sandboxed. That covers the build and local side of the confinement. Once the snap is prepared, if the snap author wishes to distribute it through official channels, they must :ref:`apply for classic confinement `. Build-time process ------------------ Snapcraft builds classic snaps differently from snaps with strict confinement. This is because in order to execute correctly, packages in classic snaps require dynamic executables to load shared libraries from the appropriate base snap instead of using the host's root filesystem. To prevent incompatibilities, binaries in classic snaps must be built with appropriate linker parameters, or patched to allow loading shared libraries from their base snap. In case of potential dynamic linking issues, the snap author must be aware that their package may not run as expected. There are multiple ways dynamic linking parameters can be manipulated: .. image:: https://assets.ubuntu.com/v1/24ce3093-confinement_03.png :alt: The flow diagram for dynamic linking parameters in the snap confinement process at build-time. - **Runtime library paths**. The dynamic section of an ELF file contains the RPATH entry, which lists the runtime paths to shared libraries to be searched before the paths set in the LD_LIBRARY_PATH environment variable. Multiple paths separated by a colon can be specified. - ``$ORIGIN`` **path**. The special value ``$ORIGIN`` represents the path where the binary is located, thus allowing the runtime library path to be set relative to that location. For example, ``$ORIGIN/../lib`` for an executable installed under ``bin/`` with libraries in ``lib/``. - **File interpreter**. The special ELF section ``.interp`` holds the path to the program interpreter. If used, it must be set to the path of the appropriate dynamic linker -- the dynamic linker from the snap package being created If libc is staged, or the dynamic linker provided by the base snap otherwise. Usually, the program interpreter is provided by the base, but it can also be provided by the snap. This happens before any library resolution takes place. To execute as expected, binaries in a classic snap must be configured to look for shared libraries provided by the base or bundled in the snap. This is achieved by setting the runtime path to shared libraries in all ELF binaries (except relocatable object files) that are present in the package payload. `PatchELF `_ is a recommended companion tool that helps automatically configure shared libraries in snaps. It ensures that: - The ``$RPATH`` value is set to reach all needed entries in the dynamic section of the ELF binary. - If the binary already contains an ``$RPATH``, only those that mention ``$ORIGIN`` are kept. - ``$RPATH`` entries that point to locations inside the payload are changed to be relative to ``$ORIGIN``. Potential conflicts ------------------- When crafting a classic snap, the snap author must consider the following conflicts that can arise. A guide for applying remedies to these conflicts can be found in :ref:`how-to-debug-classic-confinement`. At runtime ~~~~~~~~~~ Since there's no isolation between classic snaps and the underlying host system, at runtime, classic snaps may load dynamic library dependencies in a way that could create a possible error or conflict, leading to app instability, unknown behavior or crash. A classic snap created with Snapcraft using one of the Ubuntu bases with dynamically linked binaries will try to load the required dependencies at runtime: - It tries to load the dependencies, including stage packages and any other libraries, inside the snap. - Starting with core24, if not found, it looks for the dependencies in the base snap under ``/snap/``. The libraries must match the name and version of libraries as provided by the Ubuntu package archives for the specific base. In other words, snaps built with core24 and higher must use the relevant libraries by name or version, the way they are defined for their corresponding Ubuntu LTS release (such as Ubuntu 26.04 LTS for core26). - With core22, if not found, it looks for the dependencies on the host system. If found there, the snap daemon can't guarantee that the dependencies will match the expected snap and core version. They might result in app instability, unknown behavior, or crashing. With pre-built binaries ~~~~~~~~~~~~~~~~~~~~~~~ Since there's no isolation between classic snaps and the underlying host system, special care must be taken for any pre-built binaries with hard-coded library dependency paths, as they will skip the normal loading order of libraries at runtime. --- ## File: docs/explanation/components.rst .. _explanation-components: About components ================ A component is a bundle of files that can be packaged and uploaded in conjunction with a snap, and later optionally installed beside it. Components are defined with a top-level ``components`` key in the project file. Components are useful for distributing optional resources alongside a snap. For example, debug symbols are useful for the developer of an application and are closely linked to a particular build of an application. Debug symbols are not useful for the users. Including debug symbols in a snap package would waste user's network bandwidth and disk space. If an application packages debug symbols as a component alongside the snap, then the developers who require debug symbols can download and install them as a component. .. note:: Components are under development and not production ready. .. _components-and-partitions: Components and Partitions ------------------------- Components utilize a `Craft Parts`_ feature called ``partitions``. This feature is enabled only when the ``component`` key is defined in the project file. Each component has a namespaced partition ``component/`` where ``component`` is the partition's namespace and ```` is the name of the component from the project file. The partition for the snap itself is known as the ``default`` partition. Component lifecycle directories ------------------------------- When a part is built, the output is the default partition's install directory for that part. Each component has a partition. This means each component has its own install, stage, and prime directories. When a file is organized into a component's partition, it is moved to the part's install directory for that component's partition. For example, consider a part with the ``organize`` key: .. code-block:: yaml :caption: snapcraft.yaml parts: my-part: plugin: nil override-build: | touch $CRAFT_PART_INSTALL/hello organize: hello: (component/translations)/hello-world This part's build creates a file called ``hello`` in ``my-part``'s default install directory. If no ``organize`` key was used, this file would be included in the snap itself. However this example uses the ``organize`` key to move the file ``hello`` from ``my-part``'s default install directory to ``my-parts``'s install directory for the ``translations`` component. It also renames the file from ``hello`` to ``hello-world``. The packed snap will contain nothing from this part and the ``translations`` component will contain the ``hello-world`` file. --- ## File: docs/explanation/cryptography.rst .. _explanation-cryptographic-technology: Cryptographic technology in Snapcraft ===================================== Snapcraft uses cryptographic technologies to fetch arbitrary files over the internet, communicate with local processes, and store credentials. It does not directly implement its own cryptography, but it does depend on external libraries to do so. When building snaps, Snapcraft uses different codebases and libraries depending on the :ref:`base snap `. This means that the cryptographic technology used also depends on the base snap. .. _explanation_cryptography_core24: core24 and higher ----------------- Snapcraft is built upon Craft Application and derives much of its functionality from it. In particular, snaps using core24 or higher as their base use Craft Application to build, so much of Snapcraft's cryptographic functionality is described in the `Craft Application cryptography`_ documentation. Downloading build dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`Plugins ` use build tools to download and verify build dependencies. Some plugins can provision their own build tools, while others require the build tools to be available on the system. For more information on the use of cryptography for plugins provided by Craft Parts, see the `Craft Parts cryptography`_ documentation. For plugins provided by Snapcraft, the following table summarizes how they provision build tools, and which build tools they use to download and verify dependencies. .. list-table:: :header-rows: 1 * - Plugin - Build tools used - Method of provisioning the build tools * - :ref:`Colcon ` - ``colcon`` and ``rosdep`` - Not provisioned * - Conda - ``conda`` - Requests library and `curl`_ * - Flutter - ``flutter`` - Git core22 ------ Snaps using core22 as their base snap depend on various external libraries to build. Public key signing ~~~~~~~~~~~~~~~~~~ Snapcraft supports the adding and verification of arbitrary package repositories. For more information, see the `Craft Archives cryptography`_ documentation. The parts system ~~~~~~~~~~~~~~~~ Snapcraft makes use of *parts* in project files for declarative builds. Parts specified by the user may download arbitrary files, install packages, and modify files in the build environment. For more information, see the `Craft Parts cryptography`_ documentation. Creating virtual build environments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Snapcraft instantiates and executes builds on self-allocated virtual instances. For more information, see the `Craft Providers cryptography`_ documentation. Downloading build dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Snaps using core22 have the same plugin support as core24. See the :ref:`core24 ` section for more information on how Snapcraft downloads and verifies build dependencies. core20 ------ Snaps using core20 as their base snap depend on various external libraries to build. Creating virtual build environments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Snapcraft instantiates and builds snaps on self-allocated virtual instances. It uses the `Requests`_ library to install Multipass on Windows. Build environments for other operating systems are handled by the local :external+snap:doc:`snap daemon `. Communication with snapd ~~~~~~~~~~~~~~~~~~~~~~~~ Snapcraft uses the Requests library to communicate over Unix sockets with snapd. These requests fetch information about required software. If the software is missing, Snapcraft will install it through snapd. This is done by querying the :external+snap:doc:`reference/development/snapd-rest-api` with URLs built dynamically and sanitized by `urllib`_. Sources ~~~~~~~ Downloading repositories ^^^^^^^^^^^^^^^^^^^^^^^^ When a part sources a remote repository, Snapcraft clones the repository with the appropriate version control tool. The protocol used, such as ``SSH`` or ``HTTPS``, depends on the source URL and support from the version control tool. .. list-table:: :header-rows: 1 * - Version control system - Tool used * - `Git`_ - ``git`` * - `Bazaar`_ - ``bzr`` * - `Mercurial`_ - ``hg`` * - `Subversion`_ - ``svn`` Downloading source files ^^^^^^^^^^^^^^^^^^^^^^^^ When a part sources a ``.deb``, ``.rpm``, ``.snap``, ``.tar``, ``.zip``, ``.7z``, or an executable file, Snapcraft calls the Requests library to download it. If the part has the :ref:`source-type ` key, then the integrity of the source file will be verified. The checksum is verified using hashlib, so all `algorithms available to the hashlib library `_ can be used. Dependencies ~~~~~~~~~~~~ Downloading system packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^ System dependencies are downloaded and verified using snapd and `APT`_. Downloading build dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Plugins use build tools to download and verify build dependencies. Some plugins can provision their own build tools, while others require the build tools to be available on the system. The following table summarizes how plugins provision build tools and which build tools are used to download and verify dependencies. .. list-table:: :header-rows: 1 * - Plugin - Build tools used - Method of provisioning the build tools * - :ref:`Rust ` - `Cargo `_ - `rustup `_ * - Catkin - ``catkin`` and ``rosdep`` - Not provisioned * - :ref:`Colcon ` - ``colcon`` and ``rosdep`` - Not provisioned * - Conda - ``conda`` - Requests library and curl * - Crystal - ``shards`` - `Crystal snap`_ * - :ref:`Go ` - `Go toolchain `_ - Not provisioned * - :ref:`Meson ` - `Meson `_ - Not provisioned * - :ref:`NPM ` - `npm `_ - Requests library and curl * - :ref:`Python ` - `pip `_ - Not provisioned Public key signing ~~~~~~~~~~~~~~~~~~ Snapcraft uses cryptographic processes to parse public keys and optionally retrieve them from remote servers. It does not directly implement its own cryptography, but depends on `GNU Privacy Guard (GPG)`_ to do so. A declaration of a package repository includes a mandatory ``key-id`` field that specifies the fingerprint of the repository's public key. This public key can either be stored locally or automatically fetched by Snapcraft. If the key file is located as part of the project's assets, Snapcraft uses GPG as provided by the official Ubuntu archives to ensure that the file matches the declared fingerprint. If the key file is not present locally, Snapcraft uses GPG in conjunction with `dirmngr`_ (also from the Ubuntu archives) to fetch the key from the OpenPGP keyserver at ``keyserver.ubuntu.com``. In either scenario, Snapcraft then creates an APT data source for the package repository referencing the identified key. It does not validate that the remote repository is signed with the key, as APT itself does this as part of its normal operation. Remote building --------------- Remote snap builds use Craft Application. The cryptographic functionality used for remote builds is described in the `Craft Application cryptography`_ documentation. Snapcraft's legacy remote builder uses `launchpadlib`_ to interact with the `Launchpad`_ API and trigger remote builds. Login credentials for Launchpad are stored in a plain text file in the XDG data directory. Interaction with storefronts ---------------------------- Snapcraft interfaces with the Snap Store and private stores over the internet. Some store interactions are driven through Craft Store, such as authentication and listing releases. For more information, see the `Craft Store cryptography`_ documentation. For interactions that don't use Craft Store, Snapcraft uses cryptographic processes to send files between devices and endpoints through the internet. It does not directly implement its own cryptography, but it does depend on external libraries to do so. Authentication ~~~~~~~~~~~~~~ Snapcraft uses `macaroons`_, as an authentication mechanism, which are processed by the `macaroonbakery`_ library. This library validates and manages macaroons as returned by stores and simplifies the inclusion of macaroons in further requests to stores. Credentials may additionally be stored on-disk using the `keyring`_ library, which will use the keyring service provided by the host operating system. If the host does not have a keyring service, they will instead be stored in a plain text file called :file:`credentials.json` under the application's data storage directory. A warning is issued to the terminal when this behavior is triggered. This behavior is available to ease the usage of Snapcraft inside virtual machines and containers, but is generally discouraged. Network connectivity ~~~~~~~~~~~~~~~~~~~~ Snapcraft uses `urllib`_ to simplify and harden the parsing of URLs. Connections over the internet are mediated by the Requests or `httpx`_ libraries. libraries. These libraries handle cryptographic operations, such as the TLS handshake, that are standard requirements for modern internet connections. They are configured to always attempt HTTPS connections first, but have the ability to communicate over HTTP as a fallback. The Snap Store does not support HTTP, but this capability is retained to aid with local testing. Between these two libraries, Snapcraft will use whichever of the two is invoked by the consuming application. .. _Apt: https://wiki.debian.org/AptCLI .. _Bazaar: https://launchpad.net/bzr .. _Craft Application cryptography: https://canonical-craft-application.readthedocs-hosted.com/en/latest/explanation/cryptography/ .. _Craft Archives cryptography: https://documentation.ubuntu.com/craft-archives/latest/explanation/cryptography/ .. _Craft Parts cryptography: https://documentation.ubuntu.com/craft-parts/latest/explanation/cryptography/ .. _Craft Providers cryptography: https://documentation.ubuntu.com/craft-providers/latest/explanation/cryptography/ .. _Craft Store cryptography: https://documentation.ubuntu.com/craft-store/latest/explanation/cryptography/ .. _Crystal snap: https://snapcraft.io/crystal .. _curl: https://curl.se/ .. _dirmngr: https://manpages.ubuntu.com/manpages/noble/man8/dirmngr.8.html .. _Git: https://git-scm.com/ .. _GNU Privacy Guard (GPG): https://gnupg.org/ .. _httpx: https://www.python-httpx.org/ .. _keyring: https://pypi.org/project/keyring/ .. _Launchpad: https://launchpad.net .. _launchpadlib: https://ubuntu.com/docs/launchpad/user/how-to/launchpadlib/using-launchpadlib/ .. _macaroonbakery: https://pypi.org/project/macaroonbakery/ .. _macaroons: https://research.google/pubs/macaroons-cookies-with-contextual-caveats-for-decentralized-authorization-in-the-cloud/ .. _Mercurial: https://www.mercurial-scm.org/ .. _Requests: https://requests.readthedocs.io/ .. _Subversion: https://subversion.apache.org/ .. _urllib: https://docs.python.org/3/library/urllib.html --- ## File: docs/explanation/extensions.rst .. _explanation-extensions: About extensions ================ Snapcraft extensions enable snap developers to easily incorporate a set of common requirements into a snap. These requirements can include build and staging packages, plugs and interfaces, file layouts and environments, and whatever other project file elements may be required to build a functioning system. A snap developer creating a GTK3 application snap, for example, can use the gnome-3-28 extension to expose the GTK3 libraries to a snap at build and runtime without the snap developer needing specific deep knowledge about GTK3. There are extensions for building robotics (ROS 2) applications too, including the :ref:`ROS2 Humble Extension `. Extensions help: - Avoid repetitive tasks in the crafting process - Work around the need for in-depth knowledge of the target software stack - Create a standard template for common application requirements - Reduce the testing and security burden, as they're tested and updated independently For a full list of supported extensions, see the :ref:`reference-extensions` reference. --- ## File: docs/explanation/index.rst .. _explanation: Explanation =========== Explanations provide a wider perspective of Snapcraft. They aid in understanding the concepts and relationships of Snapcraft as a complete system. The project file ---------------- Snaps are blueprinted in the ``snapcraft.yaml`` file. Your understanding of Snapcraft should begin with an exploration of this file. - :ref:`explanation-snapcraft-yaml` Bases and architectures ----------------------- Bases and architectures are key concepts in snaps. They ensure that snaps are stable and compatible across different machines. - :ref:`explanation-bases` - :ref:`explanation-platforms` Parts ----- Parts are how software is brought into snaps. When a snap is packed, its parts are processed in a series of ordered, reproducible steps. - :ref:`explanation-parts` - :ref:`explanation-parts-lifecycle` Files travel as bundles through the parts lifecycle. These bundles are called *filesets*. - :ref:`filesets_explanation` Snap confinement ---------------- A snap's confinement determines how much access it has to the host system's resources. A snap is sandboxed by default, with basic access to the host's file system. If it needs other resources from the host, access is mediated through special interfaces. - :ref:`explanation-interfaces` A classically-confined snap has broad access to the host's resources and runs more like a traditional app. - :ref:`explanation-classic-confinement` Processes --------- During operation, Snapcraft follows underlying processes. - :ref:`explanation-snap-build-process` - :ref:`explanation-snap-publishing-process` Cryptography ------------ Snapcraft and its external libraries use cryptographic tools for fetching files, communicating with local processes, and storing user credentials. - :ref:`Cryptographic technology ` .. toctree:: :titlesonly: :hidden: snapcraft.yaml Platforms Bases Parts parts-lifecycle Interfaces Extensions Components snap-configurations services-daemons build-overrides remote-build /common/craft-parts/explanation/filesets classic-confinement snap-build-process snap-publishing-process Cryptographic technology --- ## File: docs/explanation/interfaces.rst .. _explanation-interfaces: About interfaces ================ A strictly-confined snap is considered untrusted and runs in a restricted environment. It's only able to access a limited set of resources outside the environment it runs in. Access to system resources and other snaps is granted on a granular basis using a mechanism called :external+snap:ref:`interfaces `. For example, a browser without network access doesn't serve its intended purpose. To that end, snap developers can use the :external+snap:ref:`interfaces-network-interface` to provide network access to the browser. Design ------ .. image:: https://assets.ubuntu.com/v1/59c290a8-snapd-interfaces.png :alt: Interface between slots and plugs. A slot can be connected to one or more plugs through an interface. The slot provides this interface and access to either a system resource or a resource from another snap. The plug connects to the provided interface and consumes the resource. Some interfaces connect automatically when a snap is installed, while others, such as those that have access to sensitive resources, need to be connected manually. See :external+snap:ref:`ref-index_interfaces` for details on which interfaces connect automatically. Users can control interfaces manually by connecting and disconnecting them with snapd. See :external+snap:ref:`explanation-interfaces-all-about-interfaces` for details. ## 2. Official Technical Reference & Guides (canonical/open-documentation-academy) ## File: README.md # Open Documentation Academy *Discover open source through documentation* The Open Documentation Academy combines Canonical’s documentation team with documentation newcomers, experts, and those in-between, to help us all improve documentation practice and become better writers. Fill blanks in your resume and paint your GitHub activity tracker golden. If you're a newcomer, we can provide help, advice, mentorship, and a hundred different tasks to get started on. If you're an expert, we want to create a place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects. A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway. [Join the academy HERE](https://discourse.ubuntu.com/t/getting-started/42769) ## This repository The purpose of this repository is to list and track global documentation tasks. These are filed as _issues_ in this repository. Tasks vary from broken formatting and missing documentation, to updates, re-structuring, and rewriting. Issues are identified and shared by participating projects at Canonical who control whether an issue is merged into their documentation. An academy participant and a mentor work together to guide a contribution through to completion. ### Participating projects The first words of an issue's title will typically indicate the project it involved. These include the following: - [ADSys](https://ubuntu.com/docs/adsys/stable/): Active Directory Group Policy client for Ubuntu - [Anbox Cloud](https://anbox-cloud.io/docs): Solution offering scalable Android in the cloud - [authd](https://ubuntu.com/docs/authd/stable-docs/): authentication service for Ubuntu that integrates with cloud identity providers - [Canonical Kubernetes](https://ubuntu.com/kubernetes/docs): the reference platform for Kubernetes on all major public clouds - [Charmed Ceph](https://ubuntu.com/ceph/docs): a Juju-native way of deploying a Ceph cluster - [Charmed OpenStack](https://ubuntu.com/openstack/docs): our traditional enterprise cloud solution - [Juju](https://juju.is/docs): open source orchestration engine - [LXD](https://documentation.ubuntu.com/lxd/en/latest/): open source container and VM management at any scale - [Landscape](https://ubuntu.com/landscape/docs): Ubuntu systems management, monitoring and administration platform - [Launchpad](https://documentation.ubuntu.com/launchpad/en/latest/): software development lifecycle and collaboration platform - [MAAS](https://maas.io/docs): bare metal cloud with on-demand servers - [MicroCeph](https://documentation.ubuntu.com/microceph/stable/): a Ceph orchestration tool; the easiest way to deploy and manage a Ceph cluster - [MicroStack](https://canonical-openstack.readthedocs-hosted.com/en/latest/): our next generation enterprise cloud solution - [Multipass](https://discourse.ubuntu.com/t/multipass-documentation/8294): tool to generate cloud-style Ubuntu virtual machines - [Netplan](https://github.com/canonical/netplan): network configuration for various backends - [Our Sphinx and RST starter pack](https://github.com/canonical/sphinx-docs-starter-pack): our open source template for building modern documentation - [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/): tool to create a new generation of secure container images - [Snap and Snapcraft](https://snapcraft.io/docs): Linux app packages and the build tools for desktop, cloud and IoT - [Ubuntu Developer Guide](https://github.com/canonical/ubuntu-for-developers-docs): guide for developers using Ubuntu Desktop as a development platform - [ubuntu-image](https://github.com/canonical/ubuntu-image): Tool for generating bootable Ubuntu images - [Ubuntu on public cloud](https://documentation.ubuntu.com/public-cloud/en/latest/): Optimised Ubuntu images for partner clouds - [Ubuntu Project Documentation](https://github.com/ubuntu/ubuntu-project-docs): manual for contributors to the Ubuntu Linux distribution - [Ubuntu Server documentation](https://github.com/canonical/ubuntu-server-documentation): Official documentation for the Ubuntu Server distribution - [Ubuntu WSL](https://ubuntu.com/wsl/docs/stable/): Ubuntu terminal environment on Windows with the Windows Subsystem for Linux (WSL) - [Ubuntu Core](https://ubuntu.com/core): A minimal, secure, containerized Ubuntu for IoT and embedded devices with transactional updates. This list will expand as more projects get involved. We're also happy to include projects outside of Canonical. ### Contributor licence agreement Many of the projects that participate in the Open Documentation Academy require that a contributor has signed a _Contributor licence agreement_, or CLA. Such an agreement will typically grant permission for the project to use a contribution while the contributor retains the copyright and the rights to modify their own work, or use it in other projects. The [Canonical contributor licence agreement](https://ubuntu.com/legal/contributors) is one such CLA. This [needs to be signed](https://ubuntu.com/legal/contributors/agreement) before a contribution can be considered for inclusion within one of Canonical's projects. Many GitHub repositories for Canonical projects will automatically check whether a contributor has signed the CLA when a contribution is made. The `cla` issue label is used to help identify which tasks require a contributor to have signed a CLA. ### Time considerations We’re completely flexible when it comes to how much time a task may take a contributor. Take as little or as much time as you need. However, we do ask that potential contributors indicate an estimated target date. This helps us to better manage the task list and to ensure tasks are being actively worked on. If you need to change your estimate, please let us know because it won’t be a problem. Similarly, let us know if you are unable to work on a task for a period of time. A comment attached to the task is enough. If there has been no activity on a task for several weeks, we'll initially reach out to the assignee before releasing the task back into the pool of unassigned tasks. ### Issue labels We use one or more of the following issue labels both for consistency and to indicate what might be expected from a task. #### https://github.com/canonical/open-documentation-academy/labels/cla Identifies tasks that require a contributor to have signed a [CLA](#contributor-licence-agreement). #### https://github.com/canonical/open-documentation-academy/labels/code Used for tasks that may require some programming knowledge, or a programmatic solution. #### https://github.com/canonical/open-documentation-academy/labels/di%C3%A1taxis Revise a document to better conform to a [Diátaxis](https://diataxis.fr/) type: - Tutorial - How-to - Reference - Explanation This may require a document to be split, edited, or sometimes re-written. #### https://github.com/canonical/open-documentation-academy/labels/edit Edit pre-existing documentation for consistency, accuracy, style and application. #### https://github.com/canonical/open-documentation-academy/labels/explanation Create or revise a document to better reflect an understanding-oriented [explanation](https://diataxis.fr/explanation/). #### https://github.com/canonical/open-documentation-academy/labels/good%20first%20issue An ideal task to start with. Marking issues with this label is a widely adopted [GitHub convention](https://github.com/topics/good-first-issue). #### https://github.com/canonical/open-documentation-academy/labels/help%20wanted Another [GitHub convention](https://github.com/topics/help-wanted) to indicate that a project welcomes community help with an issue. #### https://github.com/canonical/open-documentation-academy/labels/how-to Create or revise a document to better reflect a [how-to guide](https://diataxis.fr/how-to-guides/) to achieve a specific goal. #### https://github.com/canonical/open-documentation-academy/labels/new Adding new or missing documentation for a specific tool, feature, or function. #### https://github.com/canonical/open-documentation-academy/labels/oda-admin Tasks relating to the admin of the Open Documentation Academy (ODA) project. #### https://github.com/canonical/open-documentation-academy/labels/reference Create or revise a document to better reflect a technical description to use as [reference](https://diataxis.fr/reference/) material. #### https://github.com/canonical/open-documentation-academy/labels/review Review pre-existing documentation for quality, accuracy and consistency. This work may require small updates to the original documentation and/or the creation of sub-tasks to address any detected and substantial shortcomings. #### https://github.com/canonical/open-documentation-academy/labels/size%201 https://github.com/canonical/open-documentation-academy/labels/size%202 https://github.com/canonical/open-documentation-academy/labels/size%203 https://github.com/canonical/open-documentation-academy/labels/size%205 https://github.com/canonical/open-documentation-academy/labels/size%208 This is our estimation of effort and complexity. Size values range from 1 to 8, representing _least effort_ to _most effort_ respectively. These numbers follow the [Fibonacci ### sequence](https://en.wikipedia.org/wiki/Fibonacci_sequence) sequence of 1, 2, 3, 5, 8, with size 8 likely to be a significant undertaking. #### https://github.com/canonical/open-documentation-academy/labels/ta%20wanted The technical author (TA) team at Canonical wants to help projects without access to documentation experts. This label is used for such projects to mark tasks any technical author can help with. #### https://github.com/canonical/open-documentation-academy/labels/tutorial Develop, write, edit or update a [tutorial](https://diataxis.fr/tutorials/). Tutorials are often the hardest kinds of documentation to write or update because they primarily require good teaching skills and perception, before you even start writing. #### https://github.com/canonical/open-documentation-academy/labels/update Update potentially outdated instructions, commands, or version numbers. These tasks might include release notes, version numbers, new command line arguments and features, and even complete overhauls when a major release occurs. ## Further resources If you're new to GitHub and working on the command line, you may want to start off with our [getting started guide](getting-started/get_started.md). Even if you are running a Windows machine, you can start contributing using this guide. ### Community forum Our community forum is the hub for all things Open Documentation Academy. It includes our _Getting started_ guide and links to our weekly _Documentation office hours_, alongside meeting notes, updates, external links and discussions. https://discourse.ubuntu.com/c/community/open-documentation-academy/166 ### Synchronous chat For more interactive chat, the documentation team can be found on [Matrix](https://matrix.org/). ### Social media You can find us on [Fosstodon](https://fosstodon.org/explore), where we post frequent updates related to the _Academy_ and our other documentation initiatives. ### Calendar Subscribe to our [Documentation event calendar](https://calendar.google.com/calendar/u/0?cid=Y19mYTY4YzE5YWEwY2Y4YWE1ZWNkNzMyNjZmNmM0ZDllOTRhNTIwNTNjODc1ZjM2ZmQ3Y2MwNTQ0MzliOTIzZjMzQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20). Not only does this include our _Documentation office hours_, it will also include any other discussion or training events we organise. --- ## File: snapcraft/how-to/qt-applications/github/README.md # kcalc-example This repository is the home of the *kcalc-example* *snapcraft.yaml* files and related shell script used by the [*Qt 5 and KDE Frameworks Applications* how-to guide](https://snapcraft.io/docs/qt5-kde-applications) on snapcraft.io. Please post any questions, suggestions for improvement, or other constructive feedback and comments to the [Discourse forum post](https://forum.snapcraft.io/t/qt5-and-kde-frameworks-applications/13753) for the how-to guide, as this repository is unlikely to be actively monitored. Thank you! --- ## File: ubuntu-desktop/README.md For over 20 years, the Ubuntu Linux desktop has been one of the most popular Linux distributions, and the gateway to Linux and open source for millions of users. Its success has always been due to a tight collaboration between the Ubuntu community and Canonical, and the documentation that accompanies each and every release. The Ubuntu Desktop documentation, however, is showing signs of its age. Many users find that it's spread across too many different locations. Topics can be difficult to find, difficult to follow, and sometimes out-of-date. To help solve these problems, Canonical is in the very early stages of prototyping a new platform that we hope will be the foundation for the Ubuntu Desktop documentation for the next 20 years, and beyond. This represents a wonderful and exciting opportunity for the Open Documentation Academy, both in supporting and following what should become a trailblazing documentation platform, and also in seeding a set of open source community documentation for the next generation of Ubuntu users. To start with, several issues related to Desktop will be added to CODA. You can think of them all as top-level guides, suitable for a beginner who is curious to know more, but also pointing at more technical content that an advanced user might pursue further (perhaps these are future CODA issues too). They're broad because we want to invoke the more creative side of technical writing. Many of your readers will be ordinary users, and their skill levels (and patience) will vary hugely. This is an excellent opportunity to get involved at the beginning of what we hope will be a major project to improve Desktop documentation in the coming years. The initial topics that we have selected will give you opportunities to stretch your writing muscles in new ways, often requiring you to connect ideas and explain them for the general user To get started, just take a look for tasks with the 'desktop' label in our task tracker. --- ## File: website/docs/howto/get-started/index.md # Get started as a contributor This set of guides is intended for anyone who wants to contribute more substantial changes to documentation (or on a more regular basis) using the Ubuntu command line. For quick corrections to a page, it's perfectly fine to use the GitHub web interface instead! ## Prerequisites Before you start using this guide, you will need to set up [a GitHub account](https://github.com/), if you don't already have one. The GitHub documentation is rather good, if you get stuck or need any explanation of particular topics. ### Command-line basics Working on the command line takes a little getting used to, but doesn't need too much practice to get comfortable with it. Knowing the following commands is enough to get started: ||| | -- | -- | | `cd ` | Change directory down to `` | | `cd ..` | Go back up one directory level | | `ls` (or `ls -all`) | Lists all files (including hidden files) | | `touch ` | Create an empty file called `` | | `rm ` | Remove the file called `` | | `code ` | Open the named file in VS Code | Although you can use the sequence: ```bash touch code ``` To create and then open an empty file, if you use `code ` directly without creating the file first, VS code will create the file for you. ## Setting up your environment If you're using a Windows machine, start by following these instructions: - [Set up WSL on Windows](using_wsl.md). If you are working on a project that uses Sphinx to render the documentation, continue with: - [Set up Sphinx](setup_sphinx) ## Using git on the command line Git is central to the way many developers and technical writers work. It enables us to work on the same project in parallel, and carefully manage and monitor open source contributions. - [Work with git](using_git) ```{toctree} :hidden: :titlesonly: :maxdepth: 2 Set up WSL on Windows Set up Sphinx Work with git Troubleshooting ``` --- ## File: website/docs/howto/get-started/setup_sphinx.md # Get started with Sphinx If your repository uses Sphinx to create nicely rendered documentation, you will need to set up Sphinx on your machine. This requires a small chain of steps that are needed to install other things, so you'll need to run through these steps in this order. ## Install system requirements Sphinx is a Python based documentation framework. To setup an environment, Sphinx needs: * Python 3 * `pip`, a Python package manager * `venv`, a Python package that manages [Python virtual enviornments](https://docs.python.org/3/library/venv.html). Most projects use `make` as a way to automate and abstract operations. Further steps in this guide assume `make` is installed. On Ubuntu, ensure all dependencies are installed and your system is up to date: ```bash sudo apt update sudo apt upgrade sudo apt install python3 python3-pip python3-venv make ``` ## Make a local build of your documentation As you're working on your documentation, you'll want to check that your edits are having the desired effect. ### Navigate to the open-documentation-academy source If you've been following along on the previous pages, you should be within a folder/directory (possibly called `src`) that contains a sub-directory called `open-documentation-academy`. Let's check where we are first. Type `ls` on the command line to "list show" all the files and directories you have inside your current directory. If this is a fresh Ubuntu virtual machine, you may not have anything yet, except for the `open-documentation-academy` directory that we created when we cloned the repository. To move into the `open-documentation-academy` directory use `cd` ("change directory"). ```bash cd open-documentation-academy ``` This will put you into the `open-documentation-academy` directory that contains the current contents of the git repository from GitHub. If you're not sure where you are, you can run `ls` again and navigate. Below is an example if you wanted to contribute to the documentation on this website: ```console user@machine:~/open-documentation-academy$ ls adsys charmcraft charmed-ceph landscape LICENSE multipass README.md snapcraft ubuntu-desktop website wsl user@machine:~/open-documentation-academy$ cd website ``` ## Build the documentation At this point, you can build the documentation (as it currently exists) on your local machine, with the command `make run`. `make run` will execute multiple steps, starting with running `install`, and then building. If `make run` doesn't work initially, then try running this sequence of commands to start with a clean environment: `make clean` : deletes previously locally built documentation files and Python virtual environments. It's safe to run as it does not delete any of the source changes you may have made. `make install` : creates a Python virtual environment and install all dependencies. This is the recommended way of dealing installing the Python dependencies. `make run` : build the documentation and run a local web server hosting the built HTML pages. If it manages to complete the run successfully, you will see a big rush of commands and output flying past on your terminal window, and eventually, it will stop here: This means the documentation was successfully built, and now you can view it in your web browser by right clicking on that `http://127.0.0.1@8000` link and either selecting "open link" or "copy link" (which you can then paste into your browser of choice). It's really convenient to have this running while you're working on your changes, because every time you save a file, it will update the build and show you a live preview of what your changes look like. You can close the running server at any time by pressing `Ctrl` + `C` in the window where it's running. It's a good idea to open a second Ubuntu tab in your Terminal Window so that you can work in one tab while the documentation can be served in the other. You can do this by clicking on the down arrow next to the currently open tab, and clicking "Ubuntu" (if you're using WSL). ### On Make commands Each project may implement different `make` commands. To see available commands run ```bash make help ``` `clean` is safe to run as it does not delete any changes you've made to the source code. It only deletes the rendered documentation, so that outdated files are not shown on the next build and a new Python virtual environment with updated dependencies can be created. You can use the `make` commands for more checks depending on the project, such as `make linkcheck` to ensure links are correct and `make spellcheck` for checking spelling on built documentation. An example from the `website` makefile ```console user@machine:~/open-documentation-academy/website$ make help ------------------------------------------------------------- * watch, build and serve the documentation: make run * only build: make html * only serve: make serve * clean built doc files: make clean-doc * clean full environment: make clean * check links: make linkcheck * check spelling: make spelling * check spelling (without building again): make spellcheck * check inclusive language: make woke * check accessibility: make pa11y * check style guide compliance: make vale * check style guide compliance on target: make vale TARGET=* * check metrics for documentation: make allmetrics * other possible targets: make ------------------------------------------------------------- ``` --- ## File: website/docs/howto/get-started/troubleshooting.md # Troubleshooting This document aims to help you fix issues you may encounter when getting started. ## Troubleshoot a failed WSL installation This section provides a possible way to troubleshoot a failed installation of Windows Subsystem for Linux (WSL). You can also refer to [Microsoft's official WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting) for more information on troubleshooting WSL. If the `wsl --install` command returns the message "This operation timed out", you can debug the issue by following these steps: 1. Using your search bar, search for "Turn Windows features on or off" and select it. It'll open a window with some options for you. In this window, you should select the following options: * Virtual Machine Platform * Windows Subsystem for Linux 2. After you select these options, open your system's task manager and navigate to the performance tab. You should look for an option that says "virtualisation" to make sure it's enabled. If it isn't enabled, follow this [Microsoft guide](https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-11-pcs-c5578302-6e43-4b4b-a449-8ced115f58e1) to enable it for your system. 3. Restart your machine and try the `wsl --install` command again. It should work now. 4. If you retry the command and it doesn't work as expected, you might see an error that says, "Windows Subsystem for Linux is already installed. The operation timed out". In this case, you should update your WSL version with this command: ```shell wsl.exe --update ``` Then set the default WSL version to version 2: ```shell wsl --set-default-version 2 ``` 5. Once you have completed the above steps, open your Microsoft Store and search for "Ubuntu". It's advisable to install the latest version. After the installation, you should launch the app. It'll automatically connect to your WSL and you should be able to follow the [next steps](using_wsl.md) without errors. --- ## File: website/docs/howto/get-started/using_git.md # Get started with git To work with GitHub via the command line, we want to install `git` and set it up. Type the following command into your Ubuntu terminal window, and press enter to run it: ```bash sudo apt install git ``` If you ever need to check what version of git you have (or if it's already installed) you can use the following command: ```bash git --version ``` ## Configure git Now `git` is installed, we need to configure it so that GitHub can link up with your account. Add your GitHub username (the one you use to log in to your GitHub account) by running the following command. Remember to substitute `your_username` for your actual GitHub username. ```bash git config --global user.name your_username ``` Now let's do the same with your email (substitute for your GitHub email): ```bash git config --global user.email your.email@canonical.com ``` This next command isn't strictly required, but is recommended to replace "master" (the default branch name) with "main" which is the more inclusive standard that many organisations are moving to. You don't need to change anything about this command, you can copy and paste it directly into your terminal window and press enter to run it: ```bash git config --global init.defaultBranch main ``` If you want to double check the options you've configured so far, you can type: ```bash git config --list ``` Which will show all of the configuration options that have been set. ### Install the GitHub Command Line Interface (CLI) This will make your life much easier! On the GitHub website you'll often see commands that start with `gh`. These commands can usually be run as-is without you needing to know the corresponding sequence of `git` commands if you have the GitHub CLI. Let's install it and authorise it to access GitHub. To install, use the following command in your Ubuntu terminal window: ```bash sudo apt install gh ``` ### Authorise GitHub CLI to access your GitHub account We now want to log into the authorisation helper with the following command: ``` gh auth login gh auth setup-git ``` This will give you a series of options directly in the terminal that you can choose from, and once we go through them, it will connect your GitHub account to your Ubuntu terminal. ### Configure the GitHub CLI You can refer to the following screenshot for help. When prompted with each of these questions, choose the option highlighted in blue. These are the simplest settings for authenticating your account. You can choose different options if you know how to set up SSH, for example, but for the easiest possible setup, these are the best options. At the end of this step, `gh` will give you an alpha-numeric code in the format `XXXX-XXXX` directly in your terminal window. Copy this code, because you'll need it for the next step. `gh` will then try to authenticate using your browser. It will open up a new tab or window in your internet browser and ask you to copy and paste "the code" into the spaces provided. This step will connect `gh` in your Ubuntu terminal to GitHub on the web. ### Authenticate your GitHub login GitHub will then, in your browser, ask you to re-log in and authenticate using 2-factor authentication to confirm that it's actually you who requested the `gh` authentication above. You will usually be sent a second code (this time via your phone or other 2FA device), and it will then complete the login and connect everything up. You'll get a confirmation in your Ubuntu terminal windows and lots of green ticks everywhere if everything went to plan! ## Clone the repository onto your machine Now we can clone repositories directly to your machine using the HTTPS option. If you intend to do work on multiple repositories, it's a good idea to first make a folder to put them all in. I have called my folder `src` - you can call it something else if you'd like, or if you're happy with `src` you can copy and paste this command directly into your terminal: ```bash mkdir src cd src ``` After making the folder (with `mkdir`), we have then navigated to it using `cd` (change directory). Now that we are inside the new folder, we need to find the "address" for the repository we want to clone. In our browser window, let's go to the GitHub website and navigate to the repository we're interested in cloning. In this case, I'm using the [Open Documentation Academy](https://github.com/canonical/open-documentation-academy) repository, but you can use another repository if you like. Now, we can click on the green button that says `< > Code`, click on the "Local" tab, and then on the HTTPS sub-tab. Copy the URL that's shown in the box below that. We can then return to our terminal window and clone the repository - the command always looks something like this: ```bash git clone ``` In this case, we want to use the HTTPS link, so run this command to clone the Open Documentation Academy repository: ```bash git clone https://github.com/canonical/open-documentation-academy.git ``` This will download everything into a new folder *inside your `src` folder*, called "open-documentation-academy". This will be important later! ## The main branch So far, we've downloaded the main repository onto our machine. The "address" of this repository is usually `origin/main`. We can see this if we type the following command: ```bash git remote -v ``` The repository is called "origin" by default (on the left) and the address on GitHub is on the right. By default, we are working on the "main" branch, and when we want to push or pull content, or to submit pull requests, we specify the **address** for where to push/pull from in the format: ```bash git push origin main ``` This means we want to push to the **origin** repository, and the **main branch** of that repository. ## Setting up your own fork and main branch It's normal to make a copy of the repository for yourself to work on. We call this a **fork**. You can make a fork on the GitHub website by navigating to the repository you want to fork, and clicking on the "fork" button. If you have already made a fork, you'll see it if you click on the little drop-down arrow beside the fork button. You can click on your existing fork to navigate to it. You're now on the main branch of your own fork, instead of the main branch of the origin repository. As you can see with the example of my fork, in the top left you will be shown which repository your fork comes from. If your fork is out of date with the main repository you'll see a warning that the branch is some number of commits behind the original repository. You can click on the "sync fork" button to fetch those changes and apply them to your own fork. This will bring it up to date. ### Add your fork as a remote One thing we definitely want to do is to add our own fork as a "remote" repository on the command line. This will allow us to push the changes we want to make from our machine back to the origin repository. While you're on your fork, click on the green code button, and select the "HTTPS" tab. Copy the URL that's shown there, as in the screenshot below. Now return to your Ubuntu terminal and type the following: ```bash git remote add ``` Make sure you change `` to match your GitHub username, and then paste the URL we just copied, before you run the command. So as an example, for me to add my own fork as a remote repository on my local machine, I would type: ``` git remote add s-makin https://github.com/s-makin/ubuntu-pro-docs.git ``` And then if I retype the `git remote -v` command, I will see the following output: If I then wanted to push some changes I made on my local machine to my own fork, I'd use the command `git push s-makin main`. ## How branches work At this point, I've mentioned branches quite a bit, but let's delve a bit into what they are and why we use them. Although we can just use our fork to push our changes to, sometimes we might be working on more than one set of changes at a time -- it can get very messy if we try to make different sets of changes in one pull request. For reviewers especially, it can be very confusing if we just keep piling all our changes onto the main branch. So, we create additional branches to keep all our changes self-contained and tidy. Let's say we start off with the original repository (which we know has the address `origin/main`). We make a direct copy of it (our fork, which is called `your fork/main`). At this point, we have some changes we want to work on, so we make a copy of the `your fork/main` branch, which we can call `branch #1`. The "address" of that branch will be `your fork/branch #1`. We can make a bunch of changes to that branch without affecting the contents of the main branch, or the original repository. Then, let's say we want to start working on some different changes, that are completely unrelated to our work on `branch #1`. We then go back to `your fork/main` and make another, separate copy of it. This we'll call `branch #2`, which has the address `your fork/branch #2`. Both `branch #1` and `branch #2` started off as copies of the `your fork/main` branch, but as you work on them separate, will come to contain completely different sets of changes. ### Working with branches Branches can be a bit confusing at first, but after you start working with them, they soon make sense! So, now that you have set up your fork, you've added your remote address locally, and you're on the `main` branch of your fork. Now, we can create a new branch. ```bash git checkout -b test-branch ``` `checkout` is the command we use to switch between branches, but when we include the `-b` option, we are telling git to also create the `test-branch` branch at the same time. Usually, we will use separate branches for every pull request we intend to submit, so we can keep things tidy and can work on multiple things at once. At any time we can check which branch we are working on using: ```bash git branch ``` This will show us a list of all our active branches, including the one we're on. If we ever want to delete a branch (which we usually do after the associated pull request has been merged), we can do: ```bash git branch -d name-of-the-branch ``` ### Committing changes Once you're happy with the changes you've made, you can use: ```bash git status ``` Which will give you a summary of all the files that have been changed. It's a good idea to use this command as a double-check every time you do any actions around committing, to be sure that everything is going as you expect! Any files that show in green are on the list of changes to be committed, while files in red are not yet, and must be added. First we need to add the changes we want by adding them to the list of **staged** files: ```bash git add filename1.rst filename2.rst ``` Then we commit the files that have been staged (the ones that show up in green): ```bash git commit ``` This will bring up a new screen where you can write your commit message. We try to be as descriptive but as concise as possible in the first line, so that anyone else who looks at the commit history can understand what changes you've made, and we can use the lines after that to explain the context if necessary. When you're happy with the commit message, press "Ctrl + S" together to save the message, and then "Ctrl + X" together to exit the message window. ### Push your changes Once all your changes have been committed, you can push them to your remote fork by doing the following command: ```bash git push ``` So in this example, I would push to: ```bash git push s-makin test-branch ``` The next time I go to the main repository on the website, I should have a yellow banner at the top of the page informing me that there are changes, and inviting me to create a pull request. ## Create a pull request Now you have pushed your changes to your remote fork, you can go back to the GitHub website. Navigate to the Open Documentation Academy repository page, and you should see a banner like this: You can click on the "Compare and pull request" button to review what you've submitted, and to create a pull request. The pull request is used to **pull** the changes from your remote fork into the original repository. In the line at the top, we can see that we are proposing to bring changes from my test branch, on my fork into the origin repository's main branch. When we open a pull request, we usually include a description as well, to say what changes we've made (and why), and sometimes a repository will have other information they want you to include with your pull request. In those cases, they might have a template that you should fill out. Not following the template (if one is provided) can slow down the process of getting your PR approved and merged. When you're happy with your message, click the "Create pull request" button. At this point, the maintainers of the repository will be notified of your new pull request, and it will undergo a review process. As part of that process you might be asked to... ## Edit a pull request As long as you pay attention to the branch you're working on, editing PRs is straightforward even if you have multiple branches active (e.g. if you're working on multiple pull requests at once). Let's say you have two branches, `branch-1` and `branch-2`, each of which has a single pull request against it (`PR-1` and `PR-2` respectively). If we're currently working on `branch-1` and we want to make some edits to `PR-2`, we'll first need to switch to `branch-2`. ```bash git checkout branch-2 ``` It's always a good idea to double check what your active branch is using `git branch` before you make any changes to your branch. You can then make your changes, add and commit them as you have done before, and then all you have to do is push them to the same branch: ```bash git push ``` This will take the changes you have made, and update your pull request automatically! You can make as many changes as you like using this method, until the pull request is ready to be accepted and merged. ## Updating, rebasing and merge conflicts Sometimes you'll have a pull request "in flight" (not yet merged), and someone will make some changes to the repository that you need to incorporate into your branch. This can often lead to "merge conflicts", where you'll need to resolve the conflict before you can proceed. ```bash git fetch origin main git rebase -i origin/main ``` We need to install a tool (`meld`) that will help us to resolve merge conflicts. You should be able to copy/paste all of this into your Ubuntu terminal in one block. This will install Meld and configure it to automatically open up any conflicting files (with both versions) so you can manually review and accept the correct versions of each change. ```bash sudo apt install meld git config merge.tool git config --global merge.tool meld git config --list #should see merge.tool=meld in the list git config --global mergetool.meld.cmd 'meld $LOCAL $MERGED $REMOTE --output $MERGED' git config --list #should see mergetool.meld.cmd=meld $LOCAL $MERGED $REMOTE --output $MERGED ``` Now when you do a rebase, if there is a conflict, you can resolve it, and then type: ```bash git rebase –continue ``` Then you should be able to push your changes to your own PR without any further issues. ## After your PR is merged Once you have finished making your changes, and the PR has been accepted and merged, you will not need the branch anymore. At this point, you can use the command: ```bash git pull ``` To make sure your branch is up to date with the remote branch, then switch to the main branch on your fork with: ```bash git checkout main ``` Then, you can use `git branch` to double check the name of the branch (and to confirm that you're on the main branch!), then delete the branch for your PR with: ```bash git branch -d ``` So using my previous branch `test-branch` as our example, the command I would use is: ```bash git branch -d test-branch ``` --- ## File: website/docs/howto/get-started/using_wsl.md # Set up WSL on Windows This page is intended for Windows users who want to contribute more substantial changes to documentation (or on a more regular basis) using the Ubuntu command line. For quick corrections to a page, it's perfectly fine to use the GitHub web interface instead. ## Why are we using WSL? WSL is the Windows Subsystem for Linux. It sets aside some space on your computer and creates a virtual Ubuntu machine in that space. This will allow you to work as if you're using an Ubuntu computer, but without having to change anything on your Windows system. Even if you somehow break your Ubuntu virtual machine (VM), the Windows machine won't be harmed, so WSL provides a safe way to become more familiar with using Linux! ## Install VS Code on your Windows machine It might seem strange to install VS Code before we install WSL, but by doing things this way round, we'll save ourselves several fiddly steps later! You will need a text editor to be able to make changes to the content you're working with, and the best editor is VS Code. It can be installed on your Windows machine, and then WSL can use it – even from inside your Ubuntu virtual machine. Go to the [Visual Studio code website](https://code.visualstudio.com/) and scroll down until you see the download button for Windows. It may automatically detect your operating system and download VS Code if you're on Windows. If it doesn't start automatically, click on the Windows download button and run the installer when it's done. The installation should be straightforward, and the default options should work just fine. ## Install WSL on your Windows machine We can install WSL using the Windows command line. To do this, open the Windows Terminal by clicking on the Windows start menu and scrolling down to Terminal (or searching for "Terminal" in the search bar). Once you have opened the Terminal window, type the following, then press enter to run it: ``` wsl --install ``` When asked if you want to allow WSL to make changes to your device, click "yes". After WSL has finished installing, you'll need to restart your computer (your physical machine, not just the Terminal window) before you can continue. **NOTE**: If you have issues with installing WSL on your Windows machine, you can refer to our [troubleshooting section](./troubleshooting.md) or [Microsoft's official WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting) ## Your new Ubuntu VM After you've restarted your physical machine, WSL will automatically launch Ubuntu in a new Terminal window. You won't need the Windows Terminal anymore, so you can close that one, and leave only the Ubuntu window open. The Ubuntu window will ask you to set up a username and password. This is separate from the credentials you use to log into your Windows machine, although you can choose the same. The password you type will be completely "hidden", so you won't be able to see it or see how many characters you've typed. It will ask you to confirm the password anyway, so if you think you made a mistake, you'll still have to type it correctly twice. After this is done, your Ubuntu VM will be ready to use! ## Update the virtual Ubuntu machine It's always a good idea when you start up a new virtual machine to update and upgrade it, which you can do with the following command typed into the Ubuntu terminal: ``` sudo apt update && sudo apt upgrade ``` Using `sudo` will prompt you for a password. This is the same password you entered when you set up your Ubuntu machine in the previous step. When asked if you want to continue, type `y` (not case sensitive). You're now ready to move on to the next stage! [Install and configure git](using_git.md). --- ## File: website/docs/howto/index.md # How to ```{toctree} :maxdepth: 1 Get started Work on a task Become a mentor ```