= Prerequisites = To build packages, install the `devscripts` package: `sudo apt install devscripts`, which contains a lot of useful helpers for building Debian packages. Having `gbp` available is also a good idea: `sudo apt install git-buildpackage` = Building packages == All packages have to be built in a pristine PureOS `landing` chroot before being uploaded to PureOS. The preferred method to do that is by using pbuilder. For packages not managed in Git, pbuilder can be invoked via ``` DIST=landing pdebuild --auto-debsign ``` For Git-managed packages, `gbp` provides options to build with pbuilder directly. Alternatively, `pdebuild` can be passed in like `gbp buildpackage --git-builder='DIST=landing pdebuild --auto-debsign'` Don't forget to set your own email address for the Git repository, via `git config user.email your.name@puri.sm`. = Version numbers = Packages which are available on Debian and are changed in PureOS have a `pureosX` version tag attached to the Debian revision, with `X` being the PureOS revision number. So, if the package's upstream version is `2.1`, it's Debian revision is `2` (creating the Debian version string `2.1-2`) and you make a change for PureOS, the resulting package version must be `2.1-2pureos1`. The PureOS revsion is incremented with every change, so the next version would be `2.1-2pureos2`. If the package isn't in Debian, the Debian revision number is assumed to be zero and all other rules from above still apply. So, and upstream package with version `3.4` which is new in PureOS will get the initial version `3.4-0pureos1`. If you do not do any source changes but just rebuild a package, `bX` is appended to the revision. So, a package of version `1.0-3` gets the new version `1.0-3b1` if it is rebuilt. The rebuild version is incremented on every subsequent rebuild. If the archive rejects an upload because a `+bX` version number exists, then this is because of a binary package sync from Debian where the package was binNMUd before. In this particular case, please upload the package again, but append a `+` before the PureOS version, so `1.0-1pureos1` becomes `1.0-1+pureos1`. Paying attention to the version numbers is important, because the PureOS archive tools will use the version number to make decisions about the package's state, which includes overriding it with a version from Debian or even removing it. Using the right version number will make the archive do the right thing. You might be able to use `DEBEMAIL=first.last@puri.sm dch --distribution=landing --force-distribution --no-auto-nmu --local=pureos` as a starting point. = Validating packages = Use `lintian --profile=pureos -IE --pedantic <changes-file>` to check a package for compliance with the Debian policy. Ensure it is warning and error-free. If your Lintian is old and does not support the `pureos` profile, all warnings related to NMUs and invalid suites can be ignored, as those are different or don't exist in PureOS. (See https://bugs.debian.org/884408) = Maintainer address = If you change the maintainer address in a Debian package you modify, please use `PureOS Maintainers <pureos-project@lists.puri.sm>`. You don't actually need to change the maintainer address (it is a bit nicer though). In any case, you don't need to add yourself as uploader, since all packages in PureOS are team maintained - the Lintian error for that is something we might need to change.

= Prerequisites = To build packages, install the `devscripts` package: `sudo apt install devscripts`, which contains a lot of useful helpers for building Debian packages. Many build tools for building software in the package can be found in the package build-essential; ``` apt install build-essential devscripts ``` Having `gbp` available is also a good idea: `sudo apt install git-buildpackage` Note that installing git-buildpackage (gbp) will pull in pbuilder. You can prevent this by using --no-install-recommends when you install, e.g.; ``` apt install --no-install-recommends git-buildpackage ``` This is not necessary but can be helpful if you don't want to install and configure pbuilder. == Building packages with git-buildpackage == PureOS is aiming to standardize around a git based workflow. Please follow this link for [[ building packages with git-buildpackage | building packages with git-buildpackage ]] == Building packages with Debspawn and pbuilder == All packages should be tested and built in a pristine PureOS `landing` chroot before being uploaded to PureOS repositories. The preferred method to do that is by using debspawn. === Debspawn quickstart === Debspawn uses a [[ https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html | systemd-nspawn ]] container to build packages. It is also the build environment used on the PureOS autobuild servers, so if you want to replicate a build as close as possible to what runs on our build servers, use `debspawn`. To install `debspawn`, run `sudo apt install debspawn` first. Then create a new build environment for `landing`: `debspawn create landing`. For packages not managed in git, debspawn can be invoked via ``` debspawn build landing --sign ``` For packages using git as the source code management tool, `gbp` can be instructed to build with Debspawn via `gbp buildpackage --git-builder='debspawn b landing --sign'` Don't forget to set your own email address for the Git repository, via `git config user.email your.name@puri.sm`. === Pbuilder quickstart === There is documentation on setting up a [[ Development/pBuilder Environment Quick Setup| pbuilder environment using PureOS ]]. For packages not managed in git, pbuilder can be invoked via ``` DIST=landing pdebuild --auto-debsign ``` For git-managed packages, `gbp` provides options to build with pbuilder directly. Alternatively, `pdebuild` can be passed in like `gbp buildpackage --git-builder='DIST=landing pdebuild --auto-debsign'` Don't forget to set your own email address for the git repository, via `git config user.email your.name@puri.sm`. = Version numbers = Please check out [[Development/Package version numbers]] for information on how to version PureOS packages properly. Paying attention to the version numbers is important, because the PureOS archive tools will use the version number to make decisions about the package's state, which includes overriding it with a version from Debian or even removing it. You might be able to use `DEBEMAIL=first.last@puri.sm dch --distribution=landing --force-distribution --no-auto-nmu --local=pureos` as a starting point. = Validating packages = Use `lintian --profile=pureos -IE --pedantic <changes-file>` to check a package for compliance with the Debian policy. Ensure it is warning and error-free. If your Lintian is old and does not support the `pureos` profile, all warnings related to NMUs and invalid suites can be ignored, as those are different or don't exist in PureOS. (See https://bugs.debian.org/884408) = Mandatory debian/control file changes for PureOS = == Maintainer address == Please add the team based maintainer address for PureOS packages;`PureOS Maintainers <pureos-project@lists.puri.sm>`. This ensures that more than one person will be able to help maintain the package in PureOS and is required. Example: If the debian/control file had ``` Maintainer: Cool Package Maintainers <team-pkg@example.com> ``` it should be changed to: ``` Maintainer: PureOS Maintainers <pureos-project@lists.puri.sm> XSBC-Original-Maintainer: Cool Package Maintainers <team-pkg@example.com> ``` Note that the `Uploaders:` field remains untouched. == Version Control System fields == In addition to the maintainer address, please make sure to fill in the Vcs-Browser and Vcs-Git fields. This allows one to correlate releases with source code and is also required. The original `Vcs-*` fields should be retained as `XSBC-Original-Vcs-*`: Example: ``` Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center ``` becomes: ``` Vcs-Git: https://source.puri.sm/pureos/packages/gnome-control-center.git Vcs-Browser: https://source.puri.sm/pureos/packages/gnome-control-center XSBC-Original-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git XSBC-Original-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center ``` This help to identify the repository where new Debian versions should be pulled from. = Closing bugs = At the moment, the service that automatically closes reports is not active, due to maintenance (the previous implementation had a few bugs and was very slow), so for now you will need to close bugs manually. However, for some packages the bug information is still used to e.g. determine package migration speed. To close bugs in the PureOS tracker with an upload (once it is re-enabled), please use either the `PB: #<nnn>` or `PureOS: #<nnn>` syntax in `debian/changelog`, with `<nnn>` being replaced with the number of the respective task in Maniphest on tracker.p.n (with the `T` prefix stripped). = Uploading packages = See the document on [[ Development/Uploading Packages | Development/Uploading Packages ]] = Common baseline = In order to ease collaboration *new* packages introcued into PureOS should - be based on Debian's upstream packaging from git when available. Those can usually be found on https://salsa.debian.org - be maintained in a git repository at https://source.puri.sm/pureos/packages or https://source.puri.sm/Librem5/debs - adhere to [Debian policy](https://www.debian.org/doc/debian-policy/) - have a pipeline for gitlab-ci at `debian/pureos-ci.yaml` that builds debs to ease testing ([example](https://source.puri.sm/pureos/packages/gnome-control-center/-/blob/pureos/master/debian/pureos-ci.yml)) - the main development branch should be called `pureos/latest`. It always targets the latest PureOS release and should be the default branch in the gitlab UI. *Existing* packages can continue to use `pureos/byzantium` or `pureos/master` branch naming but should make sure the gitlab UI has the default branch set to the branch that carries most recent development (e.g. `pureos/byzantium` at the time of writing).

= Prerequisites = To build packages, install the `devscripts` package: `sudo apt install devscripts`, which contains a lot of useful helpers for building Debian packages. Many build tools for building software in the package can be found in the package build-essential; ``` apt install build-essential devscripts ``` Having `gbp` available is also a good idea: `sudo apt install git-buildpackage` = Building packages ==Note that installing git-buildpackage (gbp) will pull in pbuilder. You can prevent this by using --no-install-recommends when you install, e.g.; All packages have to be built in a pristine PureOS `landing` chroot before being uploaded to PureOS. The preferred method to do that is by using pbuilder.``` For packages not managed in Git, papt install --no-install-recommends git-builder can be invoked viapackage ``` DIST=landing pdebuild --auto-debsignThis is not necessary but can be helpful if you don't want to install and configure pbuilder. == Building packages with git-buildpackage == ```PureOS is aiming to standardize around a git based workflow. Please follow this link for [[ building packages with git-buildpackage | building packages with git-buildpackage ]] For Git-managed packages, `gbp` provides options to build with pbuilder directly. Alternatively, `pdebuild` can be passed in like `gbp buildpackage --git-builder='DIST=landing pdebuild --auto-debsign'`== Building packages with Debspawn and pbuilder == Don't forget to set your own email address for the GitAll packages should be tested and built in a pristine PureOS `landing` chroot before being uploaded to PureOS repository,ies. via `git config user.email your.name@puri.sm`The preferred method to do that is by using debspawn. = Version numbers === Debspawn quickstart === Debspawn uses a [[ https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html | systemd-nspawn ]] container to build packages. It is also the build environment used on the PureOS autobuild servers, so if you want to replicate a build as close as possible to what runs on our build servers, use `debspawn`. To install `debspawn`, run `sudo apt install debspawn` first. Then create a new build environment for `landing`: `debspawn create landing`. For packages not managed in git, debspawn can be invoked via ``` debspawn build landing --sign ``` Packages which are available on Debian and are changed in PureOS have a `pureosX` version tag attached to the Debian revision, with `X` being the PureOS revision number. So, if the package's upstream version is `2.1`, it's Debian revision is `2` (creating the Debian version string `2.1-2`) and you make a change for PureOS, the resulting package version must be `2.1-2pureos1`. The PureOS revsion is incremented with every changeFor packages using git as the source code management tool, so the next version would be `2.1-2pureos2`.`gbp` can be instructed to build with Debspawn via `gbp buildpackage --git-builder='debspawn b landing --sign'` If the package isn't in DebianDon't forget to set your own email address for the Git repository, the Debian revision number is assumed to be zero and all other rules from above still apply.via `git config user.email your.name@puri.sm`. === Pbuilder quickstart === There is documentation on setting up a [[ Development/pBuilder Environment Quick Setup| pbuilder environment using PureOS ]]. For packages not managed in git, So, and upstream package with version `3.4` which is new in PureOS will get the initial version `3.4-0pureos1`.pbuilder can be invoked via ``` DIST=landing pdebuild --auto-debsign ``` If you do not do any source changes but just rebuild aFor git-managed package, `bX` is appended to the revision.es, So,`gbp` provides options to build with pbuilder directly. a package of version `1.0-3` gets the new version `1.0-3b1` if it is rebuilt.Alternatively, The r`pdebuild version is incremented on every subsequent r` can be passed in like `gbp buildpackage --git-builder='DIST=landing pdebuild.d --auto-debsign'` If the archive rejects an upload because a `+bX` version number exists, then this is because of a binary package sync from Debian where the package was binNMUd before. In this particular caseDon't forget to set your own email address for the git repository, please upload the package again, but append a `+` before the PureOS version, so `1.0-1pureos1` becomes `1.0-1+pureos1`.via `git config user.email your.name@puri.sm`. = Version numbers = Paying attention to the version numbers is important, because the PureOS archive tools will use the version number to make decisions about the package's state, which includes overriding it with a version from Debian or even removing it. Using the right version number will make the archive do the right thinglease check out [[Development/Package version numbers]] for information on how to version PureOS packages properly. Paying attention to the version numbers is important, because the PureOS archive tools will use the version number to make decisions about the package's state, which includes overriding it with a version from Debian or even removing it. You might be able to use `DEBEMAIL=first.last@puri.sm dch --distribution=landing --force-distribution --no-auto-nmu --local=pureos` as a starting point. = Validating packages = Use `lintian --profile=pureos -IE --pedantic <changes-file>` to check a package for compliance with the Debian policy. Ensure it is warning and error-free. If your Lintian is old and does not support the `pureos` profile, all warnings related to NMUs and invalid suites can be ignored, as those are different or don't exist in PureOS. (See https://bugs.debian.org/884408) = Maintainer address == Mandatory debian/control file changes for PureOS = == Maintainer address == Please add the team based maintainer address for PureOS packages;`PureOS Maintainers <pureos-project@lists.puri.sm>`. This ensures that more than one person will be able to help maintain the package in PureOS and is required. Example: If the debian/control file had ``` Maintainer: Cool Package Maintainers <team-pkg@example.com> ``` it should be changed to: ``` Maintainer: PureOS Maintainers <pureos-project@lists.puri.sm> XSBC-Original-Maintainer: Cool Package Maintainers <team-pkg@example.com> ``` Note that the `Uploaders:` field remains untouched. == Version Control System fields == In addition to the maintainer address, please make sure to fill in the Vcs-Browser and Vcs-Git fields. This allows one to correlate releases with source code and is also required. The original `Vcs-*` fields should be retained as `XSBC-Original-Vcs-*`: Example: ``` Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center ``` becomes: ``` Vcs-Git: https://source.puri.sm/pureos/packages/gnome-control-center.git Vcs-Browser: https://source.puri.sm/pureos/packages/gnome-control-center XSBC-Original-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git XSBC-Original-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center ``` This help to identify the repository where new Debian versions should be pulled from. = Closing bugs = At the moment, the service that automatically closes reports is not active, due to maintenance (the previous implementation had a few bugs and was very slow), so for now you will need to close bugs manually. However, for some packages the bug information is still used to e.g. determine package migration speed. To close bugs in the PureOS tracker with an upload (once it is re-enabled), please use either the `PB: #<nnn>` or `PureOS: #<nnn>` syntax in `debian/changelog`, with `<nnn>` being replaced with the number of the respective task in Maniphest on tracker.p.n (with the `T` prefix stripped). = Uploading packages = See the document on [[ Development/Uploading Packages | Development/Uploading Packages ]] = Common baseline = In order to ease collaboration *new* packages introcued into PureOS should - be based on Debian's upstream packaging from git when available. Those can usually be found on https://salsa.debian.org - be maintained in a git repository at https://source.puri.sm/pureos/packages or https://source.puri.sm/Librem5/debs - adhere to [Debian policy](https://www.debian.org/doc/debian-policy/) - have a pipeline for gitlab-ci at `debian/pureos-ci.yaml` that builds debs to ease testing ([example](https://source.puri.sm/pureos/packages/gnome-control-center/-/blob/pureos/master/debian/pureos-ci.yml)) - the main development branch should be called `pureos/latest`. It always targets the latest PureOS release and should be the default branch in the gitlab UI. If you change the maintainer address in a Debian package you modify, please use `PureOS Maintainers <pureos-project@lists.puri.sm>`. You don't actually need to change the maintainer address (it is a bit nicer though). In any case, you don't need to add yourself as uploader,*Existing* packages can continue to use `pureos/byzantium` or `pureos/master` branch naming but should make sure the gitlab UI has the default branch set to the branch that carries most recent development (e.g. since all packages in PureOS are team maintained - the Lintian error for that is something we might need to change`pureos/byzantium` at the time of writing).