diff --git a/docs/packaging/_git_commit_cleanup.md b/docs/packaging/_git_commit_cleanup.md new file mode 100644 index 000000000..ce7014d6c --- /dev/null +++ b/docs/packaging/_git_commit_cleanup.md @@ -0,0 +1,18 @@ +:::note + +The ` --cleanup=scissors` flag is necessary. By default, git treats lines starting with # as a comment, and removes them. + +If you would like to always use this flag without having to type it manually you can do so in one of two ways. + +1. Set an alias in [`~/.gitconfig`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-alias) such as + ```bash + cs = commit --cleanup=scissors + ``` + You can then use `git cs` which will do the same thing as `git commit --cleanup=scissors`. + +2. Set your git global config to always use the flag. To do so run +```bash +git config --global commit.cleanup scissors +``` + +::: \ No newline at end of file diff --git a/docs/packaging/_markdown-migration-warning.md b/docs/packaging/_markdown-migration-warning.md new file mode 100644 index 000000000..5cd155e27 --- /dev/null +++ b/docs/packaging/_markdown-migration-warning.md @@ -0,0 +1,8 @@ +:::danger + +We are currently in the process of migrating our source repositories from Phabricator to GitHub. If you have any repos checked out from Phabricator, [migrate them](docs/packaging/procedures/migrate-repos-to-github.md) before proceeding. + +Updating all facets of the documentation will take some time. +If you notice any issues feel free to [file an issue](https://github.com/getsolus/help-center-docs/issues/new) on our docs tracker, or get in contact with us on our [Matrix](/docs/user/contributing/getting-involved#matrix-chat) channels. + +::: \ No newline at end of file diff --git a/docs/packaging/advanced-config/_category_.json b/docs/packaging/advanced-config/_category_.json new file mode 100644 index 000000000..ee8f74208 --- /dev/null +++ b/docs/packaging/advanced-config/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Advanced Configuration", + "link": { + "type": "generated-index" + } +} diff --git a/docs/packaging/eopkg-configuration.md b/docs/packaging/advanced-config/eopkg-configuration.md similarity index 100% rename from docs/packaging/eopkg-configuration.md rename to docs/packaging/advanced-config/eopkg-configuration.md diff --git a/docs/packaging/local-repository.md b/docs/packaging/advanced-config/local-repository.md similarity index 95% rename from docs/packaging/local-repository.md rename to docs/packaging/advanced-config/local-repository.md index 731162c35..93630c455 100644 --- a/docs/packaging/local-repository.md +++ b/docs/packaging/advanced-config/local-repository.md @@ -7,6 +7,10 @@ summary: Packaging Using a Local Repository This guide walks you through the steps necessary to tell solbuild how to utilise locally built `.eopkg's` that are not yet in the Solus repository. +:::note +It is not necessary to use a local repository to test most package submissions. The easier and recommended way is to install the eopkg files provided when a package is built. This is intended for use with stack upgrades, rebuilds, or new packages that need new dependencies that are not yet in the repo. +::: + We assume you have worked through the [packaging](/docs/packaging) material for creating a package with solbuild. ## Install the local profile diff --git a/docs/packaging/creating-a-new-package.md b/docs/packaging/creating-a-new-package.md index 9169be000..686fcaca9 100644 --- a/docs/packaging/creating-a-new-package.md +++ b/docs/packaging/creating-a-new-package.md @@ -1,37 +1,97 @@ --- title: Creating a New Package -summary: Creating a New Package +summary: Creating a Package For Inclusion in the Repositories +sidebar_position: 3 --- # Creating a New Package -This page will take you through the steps required to build a new package on Solus. For this example, we will use the command line utility [tree](https://gitlab.com/OldManProgrammer/unix-tree), which is already packaged for Solus, but we will pretend like it's not. +This page will take you through the steps required to build a new package for the Solus package repositories. For this example, we will use the command line utility [tree](https://gitlab.com/OldManProgrammer/unix-tree), which is already packaged for Solus, but we will pretend like it's not. -## Create a new Package Directory +:::note -From within your build directory, create a new directory for the new package with the package name, and create the required Makefile within that directory: +**Please [look to see if an issue has been filed](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) for the software or library you intend to package**. If there is an existing request, please add a link to it in your pull request. Ex: + +``` +This PR resolves software request https://github.com/getsolus/packages/issues/123 +``` + +::: + +## Fork the getsolus/packages Repository / Update Your Fork + +### Create a Fork + +If you had not yet done so already, fork the repo [getsolus/packages](https://github.com/getsolus/packages) using the GitHub web UI or [`gh` cli tool](https://cli.github.com/manual/gh_repo_fork) from the `github-cli` package. It will be forked to `github.com/yourgithubaccount/packages`. + +### Update a Fork + +If you already have a fork of [getsolus/packages](https://github.com/getsolus/packages) in GitHub, log into GitHub. Make sure you're looking at the master branch. Check to see that your fork is up to date with the main repo it was forked from. If your fork indicates it is behind, use the "Sync fork" button to bring it up to date. + +## Clone the packages repo / update your clone + +### Clone the repo + +From within your packaging directory, clone the fork. Then, change to this directory. + +```bash +cd ~/solus-builds +gh repo clone yourgithubaccount/packages +cd ~/solus-builds/packages +``` + +### Update an existing clone + +If you already have a local clone, you need to bring it up to date. To do this run: + +```bash +cd ~/solus-builds/packages +git switch master +git pull +``` + +## Create a New Package Directory + +Create a new subdirectory for the new package. Use the package name as the directory name. Now, create a new branch. This will allow you to more easily separate your work from any new changes made to the package repository, which will allow you to more easily rebase any changes if needed. To do so run: ```bash mkdir tree cd tree +git switch -c your-branch +``` + +## Link to the `Makefile` + +Every package directory needs a `Makefile`. To create it with the proper contents, run this: + +```bash echo "include ../Makefile.common" > Makefile ``` +## Create The `MAINTAINERS.md` File + +You must add a file called `MAINTAINERS.md` using the template in [Maintainership](procedures/maintainership.md). Solus uses this to track the primary maintainer(s) for each package. + ## Create the `package.yml` File -Create a skeleton `package.yml` file using the `yauto.py` script from `common` You will need a link to the source tarball. -You can, of course, create your `package.yml` file entirely from scratch, but the script will give you a better starting point. +You will need a link to the most recent source tarball for this from the software's website. + +Create a skeleton `package.yml` file using the script `common/Scripts/yauto.py` and the link for the tarball. For example: ```bash ../common/Scripts/yauto.py https://gitlab.com/OldManProgrammer/unix-tree/-/archive/2.1.1/unix-tree-2.1.1.tar.gz ``` -Consider creating an alias for this script in your `.bashrc` file. +Consider creating an alias for this script in your `.bashrc` file (or equivalent for your preferred shell). ```bash alias fetchYml="$HOME/solus-builds/common/Scripts/yauto.py" ``` +:::note +You can, of course, create your `package.yml` file entirely from scratch, but the script will give you a better starting point. We recommend using the script. +::: + Now you should have a `package.yml` file that looks something like this: ```yaml @@ -40,6 +100,7 @@ version : 2.1.1 release : 1 source : - https://gitlab.com/OldManProgrammer/unix-tree/-/archive/2.1.1/unix-tree-2.1.1.tar.gz : bcd2a0327ad40592a9c43e09a4d2ef834e6f17aa9a59012a5fb1007950b5eced +homepage : PLEASE FILL ME IN license : GPL-2.0-or-later # CHECK ME component : PLEASE FILL ME IN summary : PLEASE FILL ME IN @@ -54,15 +115,18 @@ install : | %make_install ``` -The `yauto.py` script has filled many fields for us, but not all of them will be right, and some of them are blank. Refer to the [package.yml page](docs/packaging/package.yml.md) to see how each field should be used. +The `yauto.py` script has filled many fields for us, but not all of them will be right, and some of them need to be filled in. Refer to the [package.yml page](docs/packaging/package.yml.md) to see how each field should be used. For this example, we need to fix the following: +- The name needs to be `tree`, so update it. - The `license` is correct, so we remove the comment. -- Fill in `component`, `summary`, and `description`. -- Remove `builddeps`. This package has no builddeps beyond the ones already available for every package (the `system.devel` packages). -- The `setup` step is not required. -- We can't use the `%make_install` macro for this package, so the files are installed in there correct locations individually. +- Fill in `homepage`, `component`, `summary`, and `description`. +- Remove `builddeps`. This package has no build dependencies beyond the ones already available for every package (the `system.devel` packages). +- The `setup` step is not required, remove it. +- In the `install` key, we can't use the `%make_install` macro for this package. The files are installed in their correct locations individually. + +After updating the file, it will now look like: ```yaml name : tree @@ -83,16 +147,13 @@ install : | install -Dm00755 $workdir/tree $installdir/usr/bin/tree ``` -Understanding how to translate source code into a good `package.yml` file is the heart of packaging. If you are stumped, or have questions, **ask for help on [Matrix](/docs/user/contributing/getting-involved#matrix-chat).** - -## Build the Package +To read more about finding and including dependencies and other parts of `package.yml` please see [Packaging Practices](packaging-practices.md). -Build the package: +Understanding how to translate source code into a good `package.yml` file is the heart of packaging. If you are stumped, or have questions, **ask for help in our Solus Packaging room on [Matrix](/docs/user/contributing/getting-involved#matrix-chat).** -```bash -make -``` +## Build the Package +Build the package with `make` Once the build completes, your directory should now include the following files: ```text @@ -104,4 +165,52 @@ Once the build completes, your directory should now include the following files: └── tree-2.1.1-1-1-x86_64.eopkg ``` -All these files _except_ the `*eopkg` file should be included when you submit the package for review. +All these files _except_ the `*eopkg` file(s) should be included in your pull request. You will remove the `.eopkg` files after testing the package. + +Once your package has built successfully, you will need to [test it](testing-a-package). + +## Commit your Changes + +Check the [changes in your files](git-basics). + +[Add / remove files as necessary to the commit](git-basics.md). Then, **check your branch**. + +Run `git status`. Make sure all the files you changed are staged, and that there are no untracked files. When all is well, run `git commit --cleanup=scissors`. + +import GitCommitCleanup from './_git_commit_cleanup.md'; + + + +### Commit message format for new packages + +There should be a summary line (with the package name), a blank line, and then the rest of the commit message. + +- There should at the minimum be a summary and Test Plan. +- Bullet point lists should start with a dash. + +Here is an example in our standard format (make sure to check the box in the checklist): + +``` +tree: initial inclusion in the repository + +## Summary + +Add the tree package, which recursively lists directories in a tree like manner. + +## Test Plan + +- Launched the application +- Exercised the UI +- Exercised some feature + +## Checklist + +- [] Package was built and tested against unstable +``` + +For more information on suitable commit messages, please check the [tooling central documentation](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git). + +- If you want to link this pull request to an existing package request, simply mention it in your commit message (use the full URL): `The inclusion of resolves https://github.com/getsolus/packages/issues/123` +- If you need a change to depend on another change, mention it in the commit message too (use the full URL): `Depends on https://github.com/getsolus/packages/issues/234` + +Next, you'll [submit a pull request for review](submitting-a-pull-request.md). diff --git a/docs/packaging/git-basics.md b/docs/packaging/git-basics.md new file mode 100644 index 000000000..4800f3952 --- /dev/null +++ b/docs/packaging/git-basics.md @@ -0,0 +1,57 @@ +--- +title: Git Basics +summary: Basic git commands for packaging +--- + +# Git Basics + +## Working with branches + +The recommended way to switch branches is `git switch`. +To create a new branch use `git switch -c`. + +## Keeping your branch up to date with the master branch + +If there any new changes to the repository whilst you are still working on your branch you need to [sync your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). +Run `git fetch`, and `git rebase origin/master` to pull the changes in. +You will need to fix any conflicts manually. +You can check your branch against master with `git diff origin/master..my-branch`. + +## Adding files + +For every file you change or add, you must let git know about it: `git add someFile` + +## Removing files + +For files that need to be removed, you must do so using git: `git rm someFile` + +## Renaming files + +Likewise, for renaming a file, you must do so via git: `git mv someFile someFileName2` + +## Check the changes in your files + +It's a good idea to review the changes you have made to each file. This is to make sure you're committing what you intend and to make sure it looks good. Do this before adding changed files. + +To diff them all at once, useful for small changes, use `git diff`. +To diff each file one at a time run `git diff filename` on each one. + +## Commit your changes + +**Check your branch** + +Get the status of the branch with `git status`. Make sure all the files you changed are staged, and that there are no untracked files. The git status should say your branch is clean. + +Now that you've tested and reviewed your change, when you're happy with it, it's time to commit your changes with `git commit`. + +## Deleting your branch after a pull request is merged + +Once your pull request has been accepted you can delete your working branches. +First, change to the package directory, switch to the master branch, then delete your local and the remote branches. + +```bash +cd ~/solus-builds/package +git switch master +git branch -D my-branch +git push -d origin my-branch +``` \ No newline at end of file diff --git a/docs/packaging/index.md b/docs/packaging/index.md deleted file mode 100644 index f1bd50b3a..000000000 --- a/docs/packaging/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Prepare for Packaging -summary: Quick guide on getting your system set up for packaging on Solus -sidebar_position: 0 ---- - -:::danger -We are currently in the process of migrating our source repositories from Phabricator to GitHub. Updating all facets of the documentation will take some time. -If you notice any issues feel free to file an issue or get in contact with us on our Matrix channels. -::: - -# Prepare for Packaging - -## Setting up Packager file - -In order to utilise the build system, you must first set up a configuration file that has your packager details. - -This file lives in the `.config/solus` folder of your home directory. You will need to create the `.config/solus` folder as well as the inner `packager` file. Inside the packager file, you need two keys, `Name` and `Email`. This is used when generating the machine file so that the packager details are stored within the resulting binary package. - -```ini -[Packager] -Name=Your Name Here -Email=your.email@address -``` - -## Installing Development Tools - -We need to install a few things in order to get started with packaging. -The main packages we need are provided by the `system.devel` component. - -Namely: - -- `ypkg` the program that actually builds packages -- `make` used by our build tools for scripting - -```bash -sudo eopkg it -c system.devel -``` - -Additionally, we need a few more tools to carry out the packaging process: - -- `git` is used for version control of the solus sources -- `solbuild` is a lightweight container environment for building packages repeatably -- `solbuild-config-unstable` sets up solbuild for working with the `unstable` repository - -```bash -sudo eopkg it git solbuild solbuild-config-unstable -``` - -## Setting up a GitHub account - -The solus source repositories for the package repository currently reside on [github.com/solus-packages](https://github.com/solus-packages). You will need a GitHub account to submit patches and file issues. You can create a GitHub account [here](https://github.com/signup). - -## Setting Up solbuild - -The `solbuild` tool must first be initialized with a base image. All builds thereafter will use this as a base, and construct a temporary overlay root to save on time and disk space in builds. - -### Initializing solbuild - -Next, you need to initialize solbuild via: - -```bash -sudo solbuild init -``` - -This will take some time as it downloads and prepares the image. - -### Updating solbuild - -It is a good idea to keep the base image updated. It will help reduce build times by not having to repeatedly download updates to packages in the base image, and will strictly need to pull down the packages your build needs. - -To update solbuild, run: - -```bash -sudo solbuild update -``` - -## Setting up a Build Directory - -Create a build directory to hold sub-directories with packaging files. Here we are using the name `solus-builds` and placing it in our home directory, but you can use whatever you prefer. - -```bash -mkdir ~/solus-builds -cd solus-builds -``` - -### Setting up `common` - -Next you need to set up `common`, a set of scripts that enables you to manage, build, check, and publish packages. - -Run the following commands to clone the `common` repository and create the required symlinks. Do this inside `solus-builds`: - -```bash -git clone https://github.com/getsolus/common.git -ln -sv common/Makefile.common . -ln -sv common/Makefile.toplevel Makefile -ln -sv common/Makefile.iso . -``` - -Your folder should look something similar to this: - -``` -└── solus-builds - ├── common - │ ├── *lots of stuff, not shown here* - ├── Makefile -> common/Makefile.toplevel - ├── Makefile.common -> common/Makefile.common - └── Makefile.iso -> common/Makefile.iso -``` - -## Building Packages - -With your new build environment set up, you can now build packages. - -- [Your First Package](docs/packaging/your-first-package.md) -- [Updating an Existing Package](docs/packaging/updating-an-existing-package.md) -- [Creating a New Package](docs/packaging/creating-a-new-package.md) diff --git a/docs/packaging/index.mdx b/docs/packaging/index.mdx new file mode 100644 index 000000000..b60d7e568 --- /dev/null +++ b/docs/packaging/index.mdx @@ -0,0 +1,35 @@ +--- +title: Packaging Overview +summary: Steps for setting up a packaging environment and submitting packages +sidebar_position: 0 +--- + +import MigrationWarning from './_markdown-migration-warning.md'; + + + +# Packaging Overview + +This is the overall workflow for creating or updating a package. + +## Development Environment Preparation + +1. [Prepare for Packaging](prepare-for-packaging.mdx) +2. Review the [requirements for the package.yml file](docs/packaging/package.yml.md). +3. Also review our [Packaging Practices](docs/packaging/packaging-practices.md). + +## Prior to Building a Package + +Please check the following: + +- Search [open package requests](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) to see if there is one for the package. If there isn't an existing issue, go ahead and submit your pull request. If there is already a pull request, please check its status to avoid duplicating work. +- If you are submitting a pull request for the inclusion of software in the repo, the package has a corresponding package request that is **accepted for inclusion** or is a dependency of a package that has been accepted into the repository. + +## Building Packages + +1. [Update your development environment](update-dev-environment.md) +2. Prepare the package directory and build the package + * For a new package that does not yet exist in the repos see [Creating a New Package](creating-a-new-package.md) + * For updating a package that already is in the repos see [Updating an Existing Package](updating-an-existing-package.md) +3. [Test the Package](testing-a-package.md) +4. [Submit a Pull Request for Review](submitting-a-pull-request.md) \ No newline at end of file diff --git a/docs/packaging/package.yml.md b/docs/packaging/package.yml.md index c3978cd77..4cc863341 100644 --- a/docs/packaging/package.yml.md +++ b/docs/packaging/package.yml.md @@ -3,15 +3,15 @@ title: Package YAML summary: Learning the package.yml packaging format --- -# Package.yml +# `package.yml` -All packages are generated from a single build file, which provides all of the required metadata for the package manager, plus the packaging steps involved to produce a package. This follows the YAML specification. +Each package is generated from a single build file named `package.yml`. This file is sometimes also called a "recipe" since it provides steps for building a package. It provides all of the required metadata for the package manager, plus the packaging steps involved to produce a package. This file follows the YAML specification. ## Format All `package.yml` files **must** be valid YAML. -The file is organised into a key→value hierarchy. The `ypkg` tool parses a `package.yml` file to build the corresponding package in a declarative manner, so most of the keys are simple strings, lists or nested key→value pairs. A special case consists in the packaging steps, which are scripts. +The file is organised into a key→value hierarchy. The `ypkg` tool parses a `package.yml` file to build the corresponding package in a declarative manner. As such, most of the keys are simple strings, lists or nested key→value pairs. A special case consists in the packaging steps, which are scripts. An example file follows: @@ -54,6 +54,7 @@ Not all fields in `package.yml` are mandatory, but a small selection are. Below | **version** | `string` | The version of the currently packaged software. This is taken from the tarball in most cases. | | **release** | `integer` | Specifies the current release number. Updates in the package number are based on this `release` number, _not_ the `version` number. As such, to release an update to users, this number must be incremented by one. | | **license** | `string(s)` | Valid upstream license(s). Try to ensure these use [SPDX identifiers](https://spdx.org/licenses/). | +| **homepage** | `string` | Provides a link to the package's homepage, used in the Software Center. | | **source** | `dict(s)` | Upstream source URL (i.e. tarball), with the valid `sha256sum` as a value. Alternatively, the git repository URL prefixed with "git|" and a git tag or commit hash as a value. | | **component** | `string` | Component / group of packages this package belongs to. Check available components via `eopkg lc` | | **summary** | `string` | Brief package summary, or display name. | @@ -76,7 +77,6 @@ Not all fields in `package.yml` are mandatory, but a small selection are. Below | **patterns** | `dict(s)` | Allows fine grained control over file placement within the package or sub-packages. Useful for packages that are development only (i.e. `/usr/bin` files). | | **environment** | `unicode` | Specify code that will be exported to all packaging steps of the build (i.e. exporting variables for the entire build). | | **networking** | `bool` | Set to `yes` to enable networking within solbuild. | -| **homepage** | `string` | Provides a link to the package's homepage in the Software Center. | ### Packaging Step Keys, optional diff --git a/docs/packaging/packaging-practices.md b/docs/packaging/packaging-practices.md index 209653a51..2f743a7ff 100644 --- a/docs/packaging/packaging-practices.md +++ b/docs/packaging/packaging-practices.md @@ -78,99 +78,92 @@ This is not an automatic subpackage, you must use `patterns` to utilise it. It i ## Maintenance -When submitting a change `package.yml`, it must be accompanied by its corresponding `pspec_*.xml` file, which was generated at build time. This machine file allows the repository maintainers to evaluate the package condition. +When submitting a changed `package.yml`, it must be accompanied by its corresponding `pspec_*.xml` file, which was generated at build time. This machine file allows the repository maintainers to evaluate the package condition. When providing a new version of a package, or a fix, always ensure you increment the `release` number by 1. This ensures that users of your package are correctly updated to the latest version. Never submit a package without having first tested it, and ensuring it builds within `solbuild`, a clean chroot environment. -## Generating a Package.yml - -Making a package.yml file is not necessarily a manual process. In fact, [once you have common setup](/docs/packaging), you already have a script capable of generating a package.yml file based -on the source archive URL. - -You can generate a package.yml by using `common/Scripts/yauto.py URL_TO_ARCHIVE`. We recommend creation an alias in your `.bashrc` or `.zshrc`, so you can access it wherever you are. For example: - -```bash -alias fetchYml="$HOME/repository/common/Scripts/yauto.py" -``` - ## Licenses All new packages or updates to packages should abide by the [SPDX 3.x](https://spdx.org/licenses/) definitions, with the following policy: - `-only` licenses, such as `GPL-2.0-only`, should **only be declared** as such when the upstream explicitly states "only", otherwise it should always be `-or-later`. -## Patching / extra files +## Build dependencies -Files that may be required during the build can be accessed via the `$pkgfiles` variable. Note that you must store your files in the `./files` directory relative to your `package.yml` +:::note +Build dependencies should be listed in the following order in `package.yml` +pkgconfig dependencies in alphabetical order +explicitly named dependencies in alphabetical order -Both patches and extra files (such as systemd units) are stored in this directory. Note that if your patch is to address a **CVE**, you must use the following naming scheme: `./files/security/cve-xxxx-xxxx.patch` +Example: +```yaml +builddeps : + - pkgconfig(ayatana-appindicator-0.1) + - pkgconfig(dri) + - pkgconfig(gtk+-3.0) + - pkgconfig(libnotify) + - pkgconfig(libpcsclite) + - pkgconfig(pango) + - pkgconfig(python3) + - git + - python-poetry + - swig +``` +::: -Where `xxxx-xxxx` is replaced with the full CVE ID. Complying with this simple rule ensures that we can know at any time the security status of packages when using tools such as `cve-check-tool` +### Background -Solus tooling allows the use of `./files/security/cve-xxxx-xxxx.nopatch` (which isn't applied in the build) to indicate that a CVE has been validated as not applicable to the Solus package. This can be because another patch resolves this CVE, or there is a false positive via `cve-check-tool`. The contents of the file can describe why it doesn't apply without requiring a patch (i.e. Resolved by cve-xxxx-xxxx.patch). +Most software packages that you build will, in one way or another, depend on another software package to provide specific functionality. This is usually achieved by using a library. -### Applying a patch +Any package that is submitted to our repositories is always built in a clean chroot environment. Therefore, any dependencies required to build that package in a reproducible and sane fashion must be listed. -It is common practice to apply the patch within the `setup` section of your build staging. We can achieve this using the `%patch` macro, and the `$pkgfiles` variable. In this example, the required file is located -at `./files/0002-Sample-commit-2.patch` - -```bash -%patch -p1 -i $pkgfiles/0002-Sample-commit-2.patch -``` +This is achieved by populating the `builddeps` key with a list of build dependencies. We support two kinds of build dependencies: explicitly named, or `pkgconfig` dependencies. -Note you use the macro as you would normally use the patch command, however use of the macro ensures it performs a clean batch-mode patch. +We prefer the use of `pkgconfig` dependencies. Most modern software will use the `pkg-config` tool (package configuration) to determine which files are required to build the current software. This may include compiler flags, library to link against and where the package headers are located. -If you are using compressed patches, i.e. for the `bash` or `readline` packages, you can pipe the call through `zcat` or similar: +An obvious advantage to supporting `pkgconfig` dependencies is that there is a 1:1 mapping between the name requested by the build and the name used within the `package.yml`. Instead of trying to hunt down the package providing that dependency, you simply list the same name. Any package in the repository will export information about the `.pc` files (for `pkg-config`) it contains, enabling you to use those as a build dependency. -```bash -zcat $pkgfiles/bash43-032.gz | %patch -p0 -``` +A secondary advantage is that this allows for easily switching or replacing a providing package. When no `pkgconfig` name is available (some packages do not provide these, or it doesn’t make sense for them to), you +may use the explicit package name. Always ensure you select the correct package, i.e. the `-devel` subpackage. This provides the necessary symlinks and headers to build packages. -#### Handling multiple patches +### Finding what package provides a dependency (if any) -In the event you need to apply multiple patches, such as a multitude of CVE patches, it may be sensible to use our `%apply_patches` macro, which will apply all the patches listed in a `series` file in your package's `./files` folder. Example below: +The script `common/Scripts/epcsearch.py` is used to find packages that satisfy build dependencies. We recommend making an alias for your shell for this. ```bash -security/cve-xxxx-xxxx.patch -fix-silliness.patch +alias epcsearch='~/packaging/common/Scripts/epcsearch.py' ``` -Both of the files above will be applied using `-p1`. If you need to use stripping num, like `-p4`, you can do something like: +As an example, if you know a package has a build dependency of `gtk+-3.0` you would run: ```bash -security/cve-xxxx-xxxx.patch -p4 -fix-silliness.patch +epcsearch gtk+-3.0 ``` -## Installing extra files - -We recommend using patches where possible first, as they ensure correct maintenance and will be updated across package versions. If you must install extra files into the directory, please use the `install` -command, ensuring you set the correct permissions. Again, files are accessible from the `./files/` directory, relative to `package.yml`. - -This is an example of installing a custom profile file, seen in the `bash` package: +This will output: ```bash -install -m 0644 $pkgfiles/profile $installdir/etc/profile +epcsearch gtk+-3.0 +pkgconfig(gtk+-3.0) found in: libgtk-3-devel +pkgconfig32(gtk+-3.0) found in: libgtk-3-32bit-devel ``` -## Build dependencies - -Most software packages that you build will in one way or another, depend on another software package to provide specific functionality. This is usually achieved by using a library. - -Any package that is submitted to our repositories is always built in a clean chroot environment, therefore any dependencies required to build that package in a reproducible and sane fashion, must be listed. +You can also determine if there are pkgconfigs available from a -devel package by doing `eopkg info (name)` and looking for the `Provides` key. -This is achieved by populating the `builddeps` key with a list of build dependencies. We support two kinds of build dependencies: explicitly named, or `pkgconfig` dependencies. +Example: -We prefer the use of `pkgconfig` dependencies. Most modern software will use the `pkg-config` tool (package configuration) to determine which files are required to build the current software. This may include -compiler flags, library to link against and where the package headers are located. +```bash +eopkg info libgtk-3-devel +``` -An obvious advantage to supporting `pkgconfig` dependencies is that there is a 1:1 mapping between the name requested by the build and the name used within the `package.yml`. Instead of trying to hunt down -the package providing that dependency, you simply list the same name. Any package in the repository will export information about the `.pc` files (for `pkg-config`) it contains, enabling you to use those as a build dependency. +In output: -A secondary advantage is that this allows for easily switching or replacing a providing package. When no `pkgconfig` name is available (some packages do not provide these, or it doesn’t make sense for them to), you -may use the explicit package name. Always ensure you select the correct package, i.e. the `-devel` subpackage. This provides the necessary symlinks and headers to build packages. +```bash +Provides: pkgconfig(gtk+-3.0) pkgconfig(gdk-3.0) pkgconfig(gdk-wayland-3.0) pkgconfig(gail-3.0) pkgconfig(gdk-x11-3.0) pkgconfig(gtk+-unix-print-3.0) +pkgconfig(gtk+-wayland-3.0) pkgconfig(gtk+-x11-3.0) +``` ### Using pkgconfig dependencies @@ -183,30 +176,14 @@ builddeps: At build time the appropriate provider package is selected, in this instance `libgtk-3-devel` -You can determine if there are pkgconfigs available from a -devel package by doing `eopkg info (name)` and looking for the `Provides` key. - -Example: - -```bash -$ eopkg info libgtk-3-devel -``` - -In output: - -```bash -Provides: pkgconfig(gtk+-3.0) pkgconfig(gdk-3.0) pkgconfig(gdk-wayland-3.0) pkgconfig(gail-3.0) pkgconfig(gdk-x11-3.0) pkgconfig(gtk+-unix-print-3.0) -pkgconfig(gtk+-wayland-3.0) pkgconfig(gtk+-x11-3.0) -``` - -If you want to do a reverse process and figure out what package is part of pkgconfig you can use: +### Using explicitly named dependencies -``` -common/Scripts/epcsearch.py NAME -``` - -### Using explicit named dependencies +When there is not a `pkgconfig` dependency available, use an explicitly named dependency. +Simply list the package name. -As may be obvious, simply list the package name. Note we discourage this when a `pkgconfig` dependency is available. +:::note +When a `pkgconfig` dependency is available you will be asked to use that instead. +::: ```yaml builddeps: @@ -229,14 +206,14 @@ This key uses the `dict(s)` type, and the default key is the current package `na This would add the “python-gobject” runtime dependency to the main package: -``` +```yaml rundeps: - python-gobject ``` This would add the same dependency, as well as adding it to the `devel` subpackage: -``` +```yaml rundeps: - python-gobject - devel: python-gobject @@ -244,7 +221,7 @@ rundeps: Remember this uses the `dict(s)` type, which is very flexible. You can equally express this as follows (adding more deps as an example): -``` +```yaml rundeps: - python-gobject - devel: @@ -252,6 +229,60 @@ rundeps: - someotherpackage ``` +## Patching / extra files + +Files that may be required during the build can be accessed via the `$pkgfiles` variable. Note that you must store your files in the `./files` directory relative to your `package.yml` + +Both patches and extra files (such as systemd units) are stored in this directory. Note that if your patch is to address a **CVE**, you must use the following naming scheme: `./files/security/cve-xxxx-xxxx.patch` + +Where `xxxx-xxxx` is replaced with the full CVE ID. Complying with this simple rule ensures that we can know at any time the security status of packages when using tools such as `cve-check-tool` + +Solus tooling allows the use of `./files/security/cve-xxxx-xxxx.nopatch` (which isn't applied in the build) to indicate that a CVE has been validated as not applicable to the Solus package. This can be because another patch resolves this CVE, or there is a false positive via `cve-check-tool`. The contents of the file can describe why it doesn't apply without requiring a patch (i.e. Resolved by cve-xxxx-xxxx.patch). + +### Applying a patch + +It is common practice to apply the patch file(s) within the `setup` section of your build staging. We can achieve this using the `%patch` macro, and the `$pkgfiles` variable. In this example, the required file is located +at `./files/0002-Sample-commit-2.patch` + +```bash +%patch -p1 -i $pkgfiles/0002-Sample-commit-2.patch +``` + +Note you use the macro as you would normally use the patch command, however use of the macro ensures it performs a clean batch-mode patch. + +If you are using compressed patches, i.e. for the `bash` or `readline` packages, you can pipe the call through `zcat` or similar: + +```bash +zcat $pkgfiles/bash43-032.gz | %patch -p0 +``` + +#### Handling multiple patches + +In the event you need to apply multiple patches, such as a multitude of CVE patches, it may be sensible to use our `%apply_patches` macro, which will apply all the patches listed in a `series` file in your package's `./files` folder. Example below: + +```bash +security/cve-xxxx-xxxx.patch +fix-silliness.patch +``` + +Both of the files above will be applied using `-p1`. If you need to use stripping num, like `-p4`, you can do something like: + +```bash +security/cve-xxxx-xxxx.patch -p4 +fix-silliness.patch +``` + +## Installing extra files + +We recommend using patches where possible first, as they ensure correct maintenance and will be updated across package versions. If you must install extra files into the directory, please use the `install` +command, ensuring you set the correct permissions. Again, files are accessible from the `./files/` directory, relative to `package.yml`. + +This is an example of installing a custom profile file, seen in the `bash` package: + +```bash +install -m 0644 $pkgfiles/profile $installdir/etc/profile +``` + ## Patterns In most instances, `ypkg` will assign the correct location for files, whether it be in the main `name` package, or a subpackage. However there may be instances where the default does not match the intended behaviour. diff --git a/docs/packaging/prepare-for-packaging.mdx b/docs/packaging/prepare-for-packaging.mdx new file mode 100644 index 000000000..079586949 --- /dev/null +++ b/docs/packaging/prepare-for-packaging.mdx @@ -0,0 +1,152 @@ +--- +title: Prepare for Packaging +summary: Quick guide on getting your system set up for packaging on Solus +sidebar_position: 1 +--- + +import MigrationWarning from './_markdown-migration-warning.md'; + + + +# Prepare for Packaging + +## Switch to the Unstable Repository + +Packages need to be built and tested against the "unstable" repository. If you don't want to switch your primary system to unstable, you can do your packaging work in a VM. We have Virtual Machine Manager in the repos. + +Refer to [Repository Management](docs/user/package-management/repo-management) to see how to add and switch to unstable. + +## Setting up the Packager file + +In order to utilize the build system, you must first set up a configuration file that has your packager details. + +This file lives in the `.config/solus` folder of your home directory. You will need to create the `.config/solus` folder as well as the inner `packager` file. Inside the packager file, you need two keys, `Name` and `Email`. This is used when generating the machine file so that the packager details are stored within the resulting binary package. + +Name and email address are mandatory. You must use your real first and last name(s) for accountability purposes. +A [Matrix](/docs/user/contributing/getting-involved#matrix-chat) contact is optional but recommended. + +```ini +[Packager] +Name=Your Name Here +Email=your.email@address +Matrix=@username.matrix.org +``` + +## Installing Development Tools + +We need to install a few things in order to get started with packaging. +The main packages we need are provided by the `system.devel` component. + +Namely: + +- `ypkg` the program that actually builds packages +- `make` used by our build tools for scripting + +```bash +sudo eopkg it -c system.devel +``` + +Additionally, we need a few more tools to carry out the packaging process: + +- `git` is used for version control of the solus sources +- `github-cli` is used to make working with GitHub easier +- `solbuild` is a lightweight container environment for building packages repeatably +- `solbuild-config-unstable` sets up solbuild for working with the `unstable` repository + +```bash +sudo eopkg it git github-cli solbuild solbuild-config-unstable +``` + +## Setting up a GitHub account + +The Solus source repositories for the package repository currently reside on [github.com/solus-packages](https://github.com/solus-packages). You will need a GitHub account to submit patches and file issues. You can create a GitHub account [here](https://github.com/signup). Note that you will also need to set up [2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)(two factor authentication) for your account. + +### Configure `github-cli`. + +Once you have a GitHub account, you need to configure `github-cli` to work with it. At minimum, you need to run `gh auth login`. Have your GitHub credentials and 2FA (two factor authentication) mechanism at hand. + +See the [GitHub CLI quickstart](https://docs.github.com/en/github-cli/github-cli/quickstart) for some common uses of the tool. + +## Setting up solbuild + +The `solbuild` tool must first be initialized with a base image. All builds thereafter will use this as a base, and construct a temporary overlay root to save on time and disk space in builds. + +Initialize solbuild via: + +```bash +sudo solbuild init +``` + +This will take some time as it downloads and prepares the image. + +### Updating solbuild + +It is a good idea to keep the base image updated. It will help reduce build times by not having to repeatedly download updates to packages in the base image, and will strictly need to pull down the packages your build needs. + +To update solbuild, run: + +```bash +sudo solbuild update +``` + +## Setting up a Build Directory + +Create a packaging directory to hold sub-directories with packaging files. Here we are using the name `solus-builds` and placing it in our home directory, but you can use whatever you prefer. + +```bash +mkdir ~/solus-builds +cd solus-builds +``` + +Next you need to set up `common`. This is a repository with a set of make scripts which enable you to more easily manage, build, check, and publish packages. + +Change into the directory you will keep the folders for the packages you will be building and clone the common repository with git. For instance if you have a package directory `/home/user/solus-builds` you would run: + +```bash +git clone https://github.com/getsolus/common.git +``` + +Next you need to set up a few symlinks. Do this from the same directory you executed the `git` command: + +```bash +ln -sv common/Makefile.common . +ln -sv common/Makefile.toplevel Makefile +ln -sv common/Makefile.iso . +``` + +Your packaging folder should look something similar to this: + +``` +└── solus-builds + ├── common + │ ├── *lots of stuff, not shown here* + ├── Makefile -> common/Makefile.toplevel + ├── Makefile.common -> common/Makefile.common + └── Makefile.iso -> common/Makefile.iso +``` + +## Recommended aliases +Consider creating these aliases in your `.bashrc` file (or equivalent for the zsh or fish shell). + +The script `common/Scripts/yauto.py` is used to create an initial `package.yml` file for packages that aren't yet in the repository. + +```bash +alias fetchYml="$HOME/solus-builds/common/Scripts/yauto.py" +``` + +The script `common/Scripts/epcsearch.py` is used to find packages that satisfy build dependencies. + +```bash +alias epcsearch='~/packaging/common/Scripts/epcsearch.py' +``` + +The `yupdate` tool is used when updating packages. + +```bash +alias updatePackage='/usr/share/ypkg/yupdate.py' +``` + +## Building Packages + +Your system is now set up for package work. +If you are new to packaging, see [Your First Package Update](your-first-package-update.md). \ No newline at end of file diff --git a/docs/packaging/procedures/diff-to-pull-request.md b/docs/packaging/procedures/diff-to-pull-request.md index a962b72cf..347a97535 100644 --- a/docs/packaging/procedures/diff-to-pull-request.md +++ b/docs/packaging/procedures/diff-to-pull-request.md @@ -16,7 +16,7 @@ To make the process even easier, we recommend installing `github-cli` (`sudo eop It would be a good idea to change the name of the directory to avoid a naming conflict when you fork and clone the new repository. ```bash -cd ~/solus-builds # Change this to wherever your package build directory is +cd ~/solus-builds # Change this to wherever your package packaging directory is mv bottom bottom-old ``` diff --git a/docs/packaging/procedures/maintainership.md b/docs/packaging/procedures/maintainership.md index 15ba32a39..371e9651f 100644 --- a/docs/packaging/procedures/maintainership.md +++ b/docs/packaging/procedures/maintainership.md @@ -19,11 +19,11 @@ On the Solus side however, the community must not forget that maintainers are vo The Solus Staff have the right to enforce certain practices, even when in contrast with maintainers' vision. It also has the right to ultimately accept or reject a patch. -## Stepping in +## Stepping In To officially step in as the maintainer of a package, a `MAINTAINERS.md` file must be provided for accepted packages that are not yet included in the repository, or if the package predates the policy of requiring one. Instead, if a previously maintained package is marked by Solus Staff as needing a new maintainer, the `MAINTAINERS.md` file must be updated. -## Updating a maintained package +## Updating a Maintained Package The procedure varies depending on whether or not the individual is the maintainer. @@ -33,11 +33,11 @@ Maintainers are free to [update a package](/docs/packaging/updating-an-existing- ### Non-maintainers -If a package is actively maintained, modifications should not occur and the individual should exercise patience when it comes to the updating of software. In some cases, a maintainer may intentionally be holding back a package, or has simply not updated yet. If pertinent, the individual should file a [package update request](/docs/packaging/procedures/request-a-package-update). Alternatively, the individual can reach the maintainers or Solus Staff on Matrix and ask permission to update the package. It is also possible to submit a patch and attach a message to it clarifying the intention of updating the package, although this is a special case reserved to e.g. security updates. +If a package is actively maintained, modifications should not occur and the individual should exercise patience when it comes to updates. In some cases, a maintainer may intentionally be holding back a package, or has simply not updated yet. If pertinent, the individual should file a [package update request](/docs/packaging/procedures/request-a-package-update). Alternatively, the individual can reach the maintainers or Solus Staff via the Solus Packaging room on [Matrix](/docs/user/contributing/getting-involved#matrix-chat) and ask permission to update the package. It is also possible to submit an update and attach a message to it clarifying the intention of updating the package, although this is a special case reserved to e.g. security updates. -## Template +## Template for the `MAINTAINERS.md` File -Presented here is the `MAINTAINERS.md` file. This file must be provided verbatim alongside the other patch contents, and filled in with the maintainers' personal information. A Matrix contact is optional but recommended, while an email address is mandatory. Similar to the `.solus/packager` file used for packaging, the maintainers listed in `MAINTAINERS.md` must use their real first and last name(s) for accountability purposes. +Presented here is the `MAINTAINERS.md` file. This file must be provided verbatim alongside the other patch contents, and filled in with the maintainers' personal information. A [Matrix](https://help.getsol.us/docs/user/contributing/getting-involved#matrix-chat) contact is optional but recommended, while an email address is mandatory. Similar to the `.solus/packager` file used for packaging, the maintainers listed in `MAINTAINERS.md` must use their real first and last name(s) for accountability purposes. The contact information section is a YAML list. If needed, more elements may be added, each per maintainer. Do not edit the file in any other way, including spacing, except _Name_, _Surname_ and _REPLACEME_ placeholders. @@ -47,4 +47,4 @@ This file is used to indicate primary maintainership for this package. A package - Name Surname - Matrix: REPLACEME - Email: REPLACEME -``` +``` \ No newline at end of file diff --git a/docs/packaging/procedures/migrate-repos-to-github.md b/docs/packaging/procedures/migrate-repos-to-github.md new file mode 100644 index 000000000..1e6a70574 --- /dev/null +++ b/docs/packaging/procedures/migrate-repos-to-github.md @@ -0,0 +1,42 @@ +--- +title: Migrating Existing Repos to GitHub +summary: Migrate Your Existing Repos From Phab to GitHub +--- + +# How To Migrate Pre-existing Repos and `common` to GitHub + +:::info +This is intended for people who have cloned package repos from Phabricator in the past. The information below will help you migrate your `common` repo and existing repo clones to work with our GitHub. +::: + +This document assumes your packages are stored under the folder `~/solus-builds`, adjust the commands to match the directory name on your system. + +People who have set up repos before the migration to GitHub will have git remote URLs pointing to dev.getsol.us. To see if this is the case, change to the common directory, and run the following to double check: + +``` bash +cd ~/solus-builds/common +❯ git remote -v +origin https://dev.getsol.us/source/common.git (fetch) +origin https://dev.getsol.us/source/common.git (push) + +``` + +You will need to make sure you are on the master branch and update the git remote URLs: + +```bash +cd ~/solus-builds/common +git switch master +git remote set-url origin https://github.com/getsolus/common +git remote set-url --push origin git@github.com:getsolus/common.git +git pull +git status +``` + +The output should indicate you are up to date with origin/master and that your working tree is clean. If not, please reach out to the Solus Packaging team on [Matrix](/docs/user/contributing/getting-involved#matrix-chat). + +Next, run this script to update all repos from Phab to GitHub: + +```bash +cd .. +./common/switch_repo_domains +``` \ No newline at end of file diff --git a/docs/packaging/procedures/release-processes.md b/docs/packaging/procedures/release-processes.md index 339deb58b..ba5afdd93 100644 --- a/docs/packaging/procedures/release-processes.md +++ b/docs/packaging/procedures/release-processes.md @@ -33,18 +33,18 @@ Deprecated packages will remove themselves from the users systems as the first o Follow these steps to submit a package for deprecation: -0. Fork and clone the `solus-sc` repo [on Github](https://github.com/getsolus/solus-sc), and/or create a new branch -1. Edit `repo_data/distribution.xml.in` -2. Add the package you wish to deprecate at the end of the `` section -3. Run the `repo_data/merged_repos.sh` script -4. Commit and push your changes to your repo/branch -5. Open a Pull Request on Github +1. Fork and clone the `solus-sc` repo [on GitHub](https://github.com/getsolus/solus-sc), and/or create a new branch +2. Edit `repo_data/distribution.xml.in` +3. Add the package you wish to deprecate at the end of the `` section +4. Run the `repo_data/merged_repos.sh` script +5. Commit and push your changes to your repo/branch +6. Open a Pull Request on GitHub If a deprecation depends on a packaging change landing before it can be properly deprecated without undesireable side effects on user systems, the GitHub deprecation Pull Request MUST link to the packaging change and declare it as a dependency for deprecation. -### Undeprecating a package +### Un-deprecating a package -The above steps also apply to undeprecating a package, with the following additions: +The above steps also apply to un-deprecating a package, with the following additions: 1. Before making changes, the package repository must be reactivated 2. In Step 2, remove the package from the list instead of adding it diff --git a/docs/packaging/procedures/request-a-package-update.md b/docs/packaging/procedures/request-a-package-update.md index f3036c28f..2c6eb54ec 100644 --- a/docs/packaging/procedures/request-a-package-update.md +++ b/docs/packaging/procedures/request-a-package-update.md @@ -5,19 +5,16 @@ summary: Boohoo, your favorite package is outdated! # Requesting A Package Update -Packages updates are typically provided by community or dedicated package maintainers, however if we are not shipping the latest stable release of a package, you can let us know using our [Issue Tracker](https://issues.getsol.us/) +Packages updates are typically provided by the community or dedicated package maintainers. If we are not shipping the latest stable release of a package, however, you can let us know. -**Please look to see if an update request has already been filed for the software or library you require**. +**First, please [look to see if an update request has already been filed](https://github.com/getsolus/packages/labels/Package%20Request) for the software or library you require**. -If there isn't an existing request, you can use the template below for requesting to update a package. Note that updates solely for a new version number, platform-specific updates (such as to macOS or Windows) which aren't relevant, or solely translation updates, are generally not accepted or not prioritized. +If there isn't an existing request, you can use the link below to request a package update. Note that updates solely for a new version number, platform-specific updates (such as to macOS or Windows) which aren't relevant, or solely translation updates, are generally not accepted or not prioritized. -Please provide the following information: +You will be asked in the form to provide the following information: -- Title of Task: `Update $packagename to $version` -- Example: `Update nano to 2.9.7` +- Title: `Update $packagename to $version` (Example: `Update nano to 2.9.7`) - Description: Explanation as to the value-add of updating this package. -- Link to source tarball/zip file -- master.zip files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz". -- Use the tag **Software** for tagging your update request +- Link to source tarball/zip file. Note: master.zip files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz". -Please put this information into a new [issue](https://github.com/getsolus/packages/issues/new?assignees=&labels=Package+Request&projects=&template=request-package-update.yaml) +Please put this into a new [issue](https://github.com/getsolus/packages/issues/new?assignees=&labels=Package+Request&projects=&template=request-package-update.yaml). \ No newline at end of file diff --git a/docs/packaging/procedures/request-a-package.md b/docs/packaging/procedures/request-a-package.md index e2804d613..67adf7bd0 100644 --- a/docs/packaging/procedures/request-a-package.md +++ b/docs/packaging/procedures/request-a-package.md @@ -7,18 +7,16 @@ summary: Requesting a new package Packages are how users install Software in Solus, however if we are missing one you can let us know using our Task Tracker. -**Please look to see if a bug has been filed for the software or library you require**. If there isn't an existing request, you can use the template below for requesting packages to be added to the Solus Package Repository. The Third Party Repository has been deprecated and will not be accepting any new packages. +**Please [look to see if an issue has been filed](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) for the software or library you require**. If there isn't an existing request, you can use the template below for requesting packages to be added to the Solus Package Repository. The Third Party Repository has been deprecated and will not be accepting any new packages. -Please provide as much of the following information as possible: +You will be asked in the form to provide the following information, please provide as much as possible: - Name - Homepage - Why should this be included in the repository? If we already offer similar software in our repository **or third party**, please provide information on what your proposed software does that our existing offerings don't (_differentiators_). - Is it Open Source (yes/no) - If no: Are we allowed to distribute it? -- Set the Tags to have "Package Requests" - Who and how many users do you anticipate will use this software? -- Link to source tarball/zip file -- master.zip files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz" or "packagename-1.2.3". +- Link to source tarball/zip file. master.zip files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz" or "packagename-1.2.3". -Please put this information into a new [issue](https://github.com/getsolus/packages/issues/new?assignees=&labels=Package+Request%2CPriority%3A+Wishlist&projects=&template=request-new-package.yml&title=What%27s+the+package+name%3F). +Please put this information in a new [issue](https://github.com/getsolus/packages/issues/new?assignees=&labels=Package+Request%2CPriority%3A+Wishlist&projects=&template=request-new-package.yml&title=What%27s+the+package+name%3F). diff --git a/docs/packaging/submitting-a-package.md b/docs/packaging/submitting-a-package.md deleted file mode 100644 index fa9e9e173..000000000 --- a/docs/packaging/submitting-a-package.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Submitting the Package -summary: Submitting the Package ---- - -# Submitting the Package - -This article will walk you through submitting a patch for a package for review and inclusion in the Solus repository. - -When contributing patches to Solus, please note that we do not accept the upload of binary files (i.e. `.eopkg`). -All repository packages are built by a dedicated build server, from the source files provided in your patch upload. - -At minimum, your patch will include changes for the following: - -- `package.yml` -- `pspec_*.xml` - -If any additional files were required for the build, then you must also include the `files/` directory. -If you are creating a new package, you will also need to include a `Makefile` containing the following text: - -``` -include ../Makefile.common -``` - -Lastly, many package builds may result in the generation of an ABI report. These files start with `abi_*` and must also -be included, as they allow simple tracking of changes to symbols and dependencies. - -## Prior to Patch Submission - -Prior to submitting a patch, please ensure you are checking the following: - -- There is not an existing patch already provided by others. -- If you are submitting a patch for the inclusion of software in the repo, that the package your patch pertains to has a corresponding package request that is **accepted for inclusion** or is a dependency of a package that has been accepted into the repository. - -Please refrain from submitting a patch for the following instances: - -- For a package that is yet to be accepted for inclusion by a member of the Solus Staff team. We welcome you to politely reach out via the package request task or [Matrix](/docs/user/contributing/getting-involved#matrix-chat) if you deem the review of the request to be time-sensitive in nature. -- If your patch is a Work In Progress / WIP. Pull requests that are completed or are marked as *request for comments* (RFC) are accepted. For RFC request please ensure your patch title contains `[RFC]` and is marked as 'draft'. WIP patches clutter the issue tracker and make patch review by Solus Staff more time consuming and introduces unnecessary work. - -## Creating the patch - -### Manipulating files with Git - -#### Creating a new branch (optional) - -This is optional but recommended. This will allow you to more easily separate your work from an new changes made to the package repository which will allow you to more easily rebase any changes if needed. Create a new branch and switch to it by running `git checkout -b my-branch` - -:::tip -- You can checkout the master branch by running `git checkout master`, and switch back to your branch by running `git checkout my-branch` -- If there any new changes to the repository whilst you are still working on your branch you can run `git pull origin master --rebase` to pull the changes then manually fixup any conflicts. -- Once your pull request has been accepted you can delete your local branch by running `git branch -D my-branch` and `git push -d origin my-branch` to delete the remote branch. -::: - -#### Adding files - -For every file you change or add, you must let git know about them: `git add someFile` - -#### Removing files - -For files that must be removed, you must do so using git: `git rm someFile` - -#### Renaming - -Likewise, for renaming a file, you must do so via git: `git mv someFile someFileName2` - -### Commit - -Once you're happy with your change, and you have verified locally that it works by having first built and -installed it, it's time to commit your changes with `git commit`. - -Make sure you provide a meaningful summary and a separate body to your commit message. For more information -on suitable commit messages, please check the [tooling central documentation](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git). - -- If you want to link this patch to an issue on the Dev Tracker, simply mention it in your commit message: `The inclusion of fixes #1234` -- If you need a change to depend on another change, mention it in the commit message too: `Depends on #123` - -### Submitting for Review - -Now you have your changed committed, it's time to send it to us for review using by submitting a pull request to the GitHub repository. - -You will first need to fork the repository either from the GitHub web interface. Or by using the `gh` cli tool from the `github-cli` package. - -Next change your push url to the one that matches your fork. For example - -If you forked `github.com/solus-packages/nano`, it would be forked to `github.com/mygithubaccount/nano`. You can then set the push url to - -`git remote set-url --push origin https://github.com/mygithubaccount/nano` - -Finally, you can run `git push`. - -:::note -If you've created your own branch the cli tool with prompt you with a new command to create and push to a remote branch matching the local one. -::: - -Once the commit is successfully pushed. You'll notice that a URL will be provided that'll immediately allow you to create a pull request with your changes. -Open the link, double check everything, then create the pull request! - -## Updating a patch that needs changes - -### Updating files - -That's easy. **Don't make a new commit**, just make any relevant changes to your local tree, adding + removing as before, but this time run: `git commit --amend`. - -This will amend your original changes, and you can submit the updated patch once more with `git push --force`. - -A new editor session will open, where you can provide details about the changes you've made between the last revision and the newly amended one. This comment will help reviewers to see what you've changed, to streamline the process of getting your patch into Solus. - -The web interface will automatically update with the latest patch. Once accepted, your patch will be merged, and a build will be issued. - -:::note -- If you have already created a new commit, run `git rebase -i HEAD~2` to squash the commits, change the commit message to the same commit message as the original, removing any suggested commit message from git itself. -::: - -### Updating Task Information - -If you forgot information such as a test plan, you can run resolve this by: - -1. Edit your commit message with `git commit --amend` as well as editing the pull request on the GitHub web interface. <-- TODO: GitHub PR Templates -2. Next, you will see an editor session for providing a message indicating the change, for example "Added a test plan." - -After this editor session, the updated patch will be automatically uploaded, the web UI will automatically update, and no new tasks will be created. - -## Maintainership - -Submission directly to a repository is only possible for maintainers. As a maintainer you may freely push to your package(s) and initiate builds for them, which will be pushed to the unstable repository. You can watch builds [here](https://build.getsol.us/) - -Pushing changes is not possible unless you have maintainer access. The same is also true of `make publish`. - -To request maintainer rights for a repository, it is expected that some level of contribution/maintenance has already happened by way of testing/patching, and there is reasonable trust demonstrated to "hand the keys" over to a repository. - -Currently, the request mechanism is [contact Solus Staff on Matrix](/docs/user/contributing/getting-involved#matrix-chat) - -Finally, note that the management reserve the right to revoke access at any time, in order to preserve project safety and integrity. diff --git a/docs/packaging/submitting-a-pull-request.md b/docs/packaging/submitting-a-pull-request.md new file mode 100644 index 000000000..bf6d28708 --- /dev/null +++ b/docs/packaging/submitting-a-pull-request.md @@ -0,0 +1,78 @@ +--- +title: Submitting a Pull Request for Review +summary: Submitting a Pull Request for Review +sidebar_position: 6 +--- + +# Submitting a Pull Request for Review + +Please refrain from submitting a pull request for the following instances: + +- For a package that is yet to be accepted for inclusion by a member of the Solus Staff team. Search [open package requests](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) to see if there is an open request for the package. + We welcome you to politely reach out via the package request issue or our Support room on [Matrix](/docs/user/contributing/getting-involved#matrix-chat) if you deem the review of the request to be time-sensitive in nature. +- If your pull request is a Work In Progress / WIP. Pull requests that are completed or are marked as *request for comments* (RFC) are accepted. For RFC request please ensure your patch title contains `[RFC]` and is marked as 'draft'. WIP patches clutter the issue tracker and make patch review by Solus Staff more time consuming and introduces unnecessary work. + +## Final Branch Review + +At minimum, your pull request will include changes for the following files: + +- `package.yml` +- `pspec_*.xml` + +It will also include these files: + +- `Makefile` +- `MAINTAINERS.md` + +Double check the `package.yml` to make sure the builddeps are in the right order, and that it otherwise adheres to the [standards](package.yml.md) Solus has set. + +If any additional files were required for the build, then you must also include the `files/` directory. See [Packaging Practices](packaging-practices.md) for more detail. + +Many package builds may result in the automatic generation of an ABI report. These files start with `abi_*` and must also be included, as they allow simple tracking of changes to symbols and dependencies. + +Take a final look over your commit message to make sure it has all the necessary information, and that the formatting is good. You can use this, which will show the most recent commit: + +```bash +git log -1 +``` + +## Creating the Pull Request + +In the package folder, run `git push`. + +:::note + +If you've created your own branch, as recommended, the cli tool will show you a new command to create and push to a remote branch matching the local one. Run this. + +::: + +Once the commit is successfully pushed, you'll notice that a URL will be provided that will immediately allow you to create a pull request with your changes. + +Run `git status` one last time to make sure your branch is clean. If it is, open the link, double check everything, and create the pull request! + +## Amending a New Pull Request + +There may be times you need to make minor changes after submitting the pull request. For instance, you see something that needs correcting. You may update your pull request with a new commit and push, as with any other change. We recommend keeping this to a minimum after submitting your PR so that reviewers aren't working with old information. + +:::note + +Previously, with Phabricator, we required amending your commit. This is no longer necessary and is not recommended. + +::: + +## Updating a Pull Request That Has Changes Requested + +Your pull request will be reviewed, and changes may be requested. This is normal. It's to ensure the quality of the packages in our repository and to make sure each PR adheres to our standards. + +Make any relevant changes to your local branch. Add or remove files as needed, and commit. In the new commit message, describe the changes you've made between the last revision and the new one. +Ex: "Updated the build order in package.yml as requested". + +This helps reviewers see what you've changed, to streamline the process of getting your work merged. + +Submit the updated commit with `git push`. The web interface will automatically update with the latest changes. + +## After the Pull Request is Accepted + +Once your pull request is accepted and merged, someone on the Solus Team will issue a build. Your new / updated package will be published to the unstable repos. + +At this point you may [delete the local and remote branches](git-basics#deleting-your-branch-after-a-pull-request-is-merged) for this pull request. \ No newline at end of file diff --git a/docs/packaging/testing-a-package.md b/docs/packaging/testing-a-package.md new file mode 100644 index 000000000..444403290 --- /dev/null +++ b/docs/packaging/testing-a-package.md @@ -0,0 +1,41 @@ +--- +title: Testing a Package +summary: Testing a Package +sidebar_position: 5 +--- + +# Testing a Package + +After building a package, it must be tested against the unstable repo before a pull request can be submitted. Each pull request requires you to explain how you tested the package to make sure things work as expected. + +You will use the .eopkg file(s) created by the build process for testing. + +## Install the `.eopkg` Files +To install your new package, run the following command in the directory where you built the package. Include **all** `.eopkg` files that were built. + +```bash +sudo eopkg it *.eopkg +``` + +Testing need not be very complicated. The goal is to ensure the package will reliably work for our users. Testing effort will depend on how complex the software is. At minimum, you want to ensure the application launches, and performs basic functionality as expected. + +For example, if you were updating a text editor, you would want to make sure you can open, create and save files. If you know of issues the package has had in the past, it's a good idea to test that as well to make sure there are no regressions. There are plenty of historical pull requests to review if you want more detail. + +## For Updated Packages: Return to the Repository Version + +It is a good idea to uninstall the package you built, and return to the repository version, once you are done testing. To do this, run the following command on the main application. For example, if you just built `tree`: + +```bash +sudo eopkg it --reinstall tree +``` + +## Remove the `.eopkg` Files + +Before you can submit your pull request, you need to remove the `.eopkg` files. All repository packages are built by a dedicated build server from the source files provided in your pull request. + +To remove these files, run: + +```bash +go-task clean +``` + diff --git a/docs/packaging/update-dev-environment.md b/docs/packaging/update-dev-environment.md new file mode 100644 index 000000000..04cf9acba --- /dev/null +++ b/docs/packaging/update-dev-environment.md @@ -0,0 +1,26 @@ +--- +title: Update Your Development Environment +summary: Update your development environment before working on a package +sidebar_position: 2 +--- + +# Update Your Development Environment + +## Update the development tools and the system + +Always make sure your development environment and system are up to date before beginning work on a package. First, update the development tools and system + +1. Update common +2. Update the solbuild base image `sudo solbuild update` +3. Update the system. + +The below assumes your Solus packaging directories are under `~/solus-builds` + +```bash +cd ~/solus-builds/common +git pull +sudo solbuild update +sudo eopkg up +``` + +Next, you can either [Submit a New Package](creating-a-new-package.md) or [Update an Existing Package](updating-an-existing-package.md) \ No newline at end of file diff --git a/docs/packaging/updating-an-existing-package.md b/docs/packaging/updating-an-existing-package.md index 82fcd31ef..6dd549e9f 100644 --- a/docs/packaging/updating-an-existing-package.md +++ b/docs/packaging/updating-an-existing-package.md @@ -1,23 +1,74 @@ --- title: Updating an Existing Package summary: Updating an Existing Package +sidebar_position: 4 --- # Updating an Existing Package -This article will go over updating a package that is already in the Solus git repository. +This article will go over updating a package that is already in the Solus package repositories. -The instructions below assume you have cloned the package's repository using the https link provided on the respective git page, [for example nano](https://github.com/solus-packages/nano). The process for submitting an updated package is the same as if it is a new package. Follow the steps [here](/docs/packaging/submitting-a-package). +:::note -## Bumping a package +**Please [look to see if an issue has been filed](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) for the software update**. +If there is an existing request, please add a link to it in your pull request. Ex: -Bumping a package is typically done when rebuilding against a changed dependency, such as `imagemagick` needing to be rebuilt if `libwebp` changes. Additionally, it is done if changes are being made to the package, such as additional new dependencies or other modifications. +``` +This PR resolves software update request https://github.com/getsolus/packages/issues/123 +``` + +::: + +## Fork the Package Repository / Update Your Fork + +### Create a Fork + +If you had not yet done so already, fork the repo for the package (nano in this example) using the GitHub web UI or [`gh` cli tool](https://cli.github.com/manual/gh_repo_fork) from the `github-cli` package. It will be forked to `github.com/yourgithubaccount/nano`. + +### Update a Fork + +If you already have a fork of the package in GitHub, from previous updates, log into GitHub. Make sure you're looking at the master branch. Check to see that your fork is up to date with the repo it was forked from. If your fork indicates it is behind, use the "Sync fork" button to bring it up to date. + +## Clone the package repo / update your clone + +### Clone the repo + +If you do not yet have a clone of the package, change to your packaging directory, clone your fork and switch to its directory. For example: + +```bash +cd ~/solus-builds +gh repo clone yourgithubaccount/nano +cd nano +``` + +### Update an existing clone + +If you already have a local clone, you need to bring it up to date. To do so run: + +```bash +cd ~/solus-builds/package-name +git switch master +git pull +``` + +## Switch to a New Git Branch + +It's always a good idea to switch to a new git branch before beginning packaging work. This will allow you to more easily separate your work from any new changes made to the package repository, which will allow you to more easily rebase any changes if needed. +Example: + +```bash +git switch -c update_nano +``` + +## Bumping a Package + +Bumping a package is typically done when rebuilding against a changed dependency, such as `imagemagick` needing to be rebuilt if `libwebp` changes. It is also done if changes are being made to the package, such as adding new dependencies or other modifications which aren't a version update. This can be achieved by doing `make bump`, which increments the release number by 1. -## Updating a package +## Updating a Package -To update the package to a newer version, use the `yupdate` tool. This tool is located at `/usr/share/ypkg/yupdate.py` and while you can use it directly, we generally recommend setting an alias via your `.bashrc`, `.zshrc`, etc. +To update the package to a newer version, use the `yupdate` tool. This is located at `/usr/share/ypkg/yupdate.py`. We recommend setting an alias via your `.bashrc`, `.zshrc`, or method appropropriate to your shell. ```bash alias updatePackage='/usr/share/ypkg/yupdate.py' @@ -36,10 +87,71 @@ Example: /usr/share/ypkg/yupdate.py 1.0 https://example.com/example-1.0.tar.xz ``` -## Building a package +## The `MAINTAINERS.md` File -After bumping or updating the package, build it: +There must be a file called `MAINTAINERS.md` using the template in [Maintainership](procedures/maintainership.md). Add it if it does not already exist. It should name the current maintainer(s) of the package. + +## Build the package + +After bumping or updating the package, build it by running `make`. +Once your package has built successfully, you will need to [test it](testing-a-package). + +## Commit Your Changes + +Check the [changes in your files](git-basics#check-the-changes-in-your-files). + +[Add / remove files as necessary to the commit](git-basics.md). Then, **check your branch**. + +Run `git status`. Make sure all the files you changed are staged, and that there are no untracked files. When all is well, run `git commit --cleanup=scissors`. + +import GitCommitCleanup from './_git_commit_cleanup.md'; + + + +### Commit message format for updated / bumped packages + +There should be a meaningful summary line (which starts with the package name), a blank line, and then the rest of the commit message. + +- Bullet point lists should start with a dash. +- Include a changelog with a brief list of updates from the upstream release notes, with no links. +- There may also be a section for Solus specific work (e.g. rebuild against x / rework to remove dependency). +- Optional: A link to the upstream release notes page. +- Include your Test Plan. + +Here is an example in our standard format (make sure to check the box in the checklist): -```bash -make ``` +foo: Update to 1.2.3 + +## Summary + +Bugfixes: + +- Fixed a crash +- Something else + +Enhancements: + +- Implemented a feature +- Error when encountering a thing + +**Full release notes:** +- [1.2.3](https://github.com/foo/foo/releases/tag/v1.2.3) + +## Test Plan + +- Launched the application +- Exercised the UI +- Exercised some feature + +## Checklist + +- [] Package was built and tested against unstable +``` + +For more information on suitable commit messages, please check the [tooling central documentation](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git). + +- If you want to link this pull request to an existing issue, simply mention it in your commit message (use the full URL): `The inclusion of fixes https://github.com/getsolus/packages/issues/123` +- If you need a change to depend on another change, mention it in the commit message too (use the full URL): `Depends on https://github.com/getsolus/packages/issues/234` + +Next, you'll [submit a pull request for review](submitting-a-pull-request.md). \ No newline at end of file diff --git a/docs/packaging/your-first-package.md b/docs/packaging/your-first-package-update.md similarity index 57% rename from docs/packaging/your-first-package.md rename to docs/packaging/your-first-package-update.md index 43edfce8e..5b44afe07 100644 --- a/docs/packaging/your-first-package.md +++ b/docs/packaging/your-first-package-update.md @@ -1,23 +1,23 @@ --- -title: Your First Package -summary: Your First Package +title: Your First Package Update +summary: An example of how to build a package that exists in the Solus repos for new packagers. --- -# Your First Package +# Your First Package Update -This page will guide you through the steps required to build your first package. This is really a test to make sure that your [build environment is set up correctly](docs/packaging/index.md). You will clone an existing package, build it, then install it, and finally remove it. +This page will guide you through the steps required to build your first package. This is really a test to make sure that your [build environment is set up correctly](docs/packaging/prepare-for-packaging.mdx). You will clone an existing package, build it, then install it, and finally remove it. ## Cloning and building `nano` For this example we will use the text editor `nano`. -Move to your build directory. Your directory may have a different name or location: +Change to your packaging directory. Your directory may have a different name or location: ```bash cd ~/solus-builds ``` -Clone the `nano` repository, then move into it: +Clone the `nano` repository, then change into it: The `make nano.clone` command will clone the `nano` package repository `https://github.com/solus-packages/nano` ```bash @@ -32,7 +32,7 @@ make bump git diff ``` -You should see an output from git: +You should see output from git similar to the following: ```diff diff --git a/package.yml b/package.yml @@ -55,9 +55,8 @@ Next, build the package: make ``` - -You will be prompted to enter your password by sudo and the `solbuild` tool will build the package. -If the build is successful, you will have a `nano` package file with a name like `nano-7.2-161-1-x86_64.eopkg`. Run the `ls` tool to check: +You will be prompted to enter your password by sudo, and the `solbuild` tool will build the package. +If the build is successful, you will have a `nano` package file with a name like `nano-7.2-161-1-x86_64.eopkg`. Run the `ls` tool to check the exact name: ```bash ls @@ -68,17 +67,23 @@ abi_used_symbols Makefile nano-7.2-162-1-x86_64.eopkg pspec_x86_64.xml Congratulations! You have successfully built your first package on Solus. -## Installing Your New nano Package (optional) +## Installing Your New `nano` Package To install your new `nano` package, run the following command. Your filename will probably be slightly different. +This is done so you can test that the package works as expected. Each package submission will require you to describe what testing you did. + ```bash sudo eopkg it nano-7.2-162-1-x86_64.eopkg ``` +Testing `nano` is pretty easy. Testing other packages may be more complicated, depending on what they do. + +To test your newly built `nano` package, simply run it on command line, then make sure you can edit and save a file. + ## Returning to the Repository version (optional) -It is a good idea to remove your new package and return to the repository version once you are done testing your new package. +It is a good idea to remove the package you built, and return to the repository version, once you are done testing. ```bash sudo eopkg it --reinstall nano diff --git a/docs/user/contributing/community-guidelines.md b/docs/user/contributing/community-guidelines.md index 4c7b27b5a..df55bff4e 100644 --- a/docs/user/contributing/community-guidelines.md +++ b/docs/user/contributing/community-guidelines.md @@ -67,10 +67,11 @@ The below mentioned guidelines apply to individual services provided or used by ### Development / Issue Trackers -Solus utilizes a number of development and issue trackers to facilitate the development of various projects, and to address issues raised by our community through tasks / issue reports. These development trackers include, but are not limited to: +Solus utilizes a number of repositories and issue trackers to facilitate the development of various items in our project and to address issues raised by our community through tasks / issue reports. These include, but are not limited to: -- The main Solus Github Issue Tracker at `issues.getsol.us` -- Other GitHub issue trackers found in other Solus repositories under the `getsolus` organization. +- Our [Documentation, Package, Software Center, and various tooling repositories](https://github.com/getsolus/) +- Our package [issue tracker](https://github.com/getsolus/packages/issues) +- All other issue trackers utilized by the project across repositories hosted in our GitHub organizations Members of the community are expected to: diff --git a/docs/user/contributing/getting-involved.md b/docs/user/contributing/getting-involved.md index fc9b16634..c50fdbdd6 100755 --- a/docs/user/contributing/getting-involved.md +++ b/docs/user/contributing/getting-involved.md @@ -17,7 +17,7 @@ The Solus Project enforces a set of community guidelines to maintain respect and With so many new users joining, there are always more people needing help. A great way to help us out, would be to help out our users on the [Solus Project Forums](https://discuss.getsol.us). -### Matrix (chat) +### [Matrix](/docs/user/contributing/getting-involved#matrix-chat) (chat) [Matrix]() is a great way to discuss issues and development with the community, and project developers in real-time. It's also a great place for getting support, but remember due to timezone differences there might not always be people there to answer your question immediately. You can access Matrix using a client like [Element Web](https://app.element.io/), or many [others](https://matrix.org/clients/). You will need a Matrix account. @@ -65,7 +65,7 @@ We're always looking to improve our systems, especially when they're not functio - [Main Solus GitHub Issue Tracker](https://issues.getsol.us) Most bug reports about Solus itself, and its packages, should be filed here. -- [Other Solus Github Repos](https://github.com/getsolus) +- [Other Solus GitHub Repos](https://github.com/getsolus) Certain parts of Solus, such as the Software Center, have repos in the `getsolus` organization on GitHub. Check here to see if the system in question is listed. If so, file the bug in the appropriate repo. - [Budgie Desktop](https://github.com/buddiesofbudgie/budgie-desktop/issues) diff --git a/docs/user/intro.md b/docs/user/intro.md index ce26c0216..cbf29b4b8 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -44,7 +44,7 @@ Our Flarum-powered forums are easy to use from any device and are a great resour **[Matrix](https://matrix.to/#/#solus:matrix.org)** [Matrix]() is a great way to discuss issues and development with the community, and project developers in real-time. It's also a great place for getting support, but remember due -to timezone differences there might not always be people there to answer your question immediately. You can access Matrix using a client like [Element Web](https://app.element.io/), or many [others](https://matrix.org/clients/). You will need a Matrix account. +to timezone differences there might not always be people there to answer your question immediately. You can access [Matrix](/docs/user/contributing/getting-involved.md#matrix-chat) using a client like [Element Web](https://app.element.io/), or many [others](https://matrix.org/clients/). You will need a [Matrix](/docs/user/contributing/getting-involved.md#matrix-chat) account. Read more about Solus on Matrix [here.](/docs/user/contributing/getting-involved.md#matrix-chat)