Differences between revisions 54 and 60 (spanning 6 versions)
Revision 54 as of 2022-12-04 03:20:58
Size: 15514
Editor: PaulWise
Comment: usertags: add some advice for when the mailing list doesn't exist yet
Revision 60 as of 2022-12-30 12:53:46
Size: 16797
Editor: PaulWise
Comment: mention additional hardware access services
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
When filing bug reports with Debian that are related to your port, please use [[Teams/Debbugs/ArchitectureTags|architecture usertags]] to mark the bugs as relating to your port. Until your port family has a mailing list, you can use the DebianList:debian-devel mailing list as the User for your Usertags and once a mailing list exists, the usertags can be moved to the new mailing list. When filing bug reports with Debian that are related to your port, please use [[Teams/Debbugs/ArchitectureTags|architecture usertags]] to mark the bugs as relating to your port. Until your port family has a mailing list, you can use a likely mailing list name for usertags even while it doesn't exist. If the list name gets changed before it is accepted, then you can move all existing bug usertags to the new list name. You should not use the mailing list name in the [[https://www.debian.org/Bugs/Reporting#xcc|X-Debbugs-CC psuedo-header]] until it exists, once it exists you should start using it. Do not add the usertags and X-Debbugs-CC for your architecture to a bug report if the bug also applies to more commonly used architectures like amd64.
Line 21: Line 21:
  * Decide on the [[ArchitectureSpecificsMemo|architecture ABI details]] and the GNU triplet. A different GNU triplet is required for each ABI, which includes bitness, endianness, soft/hard-float, calling convention, or whether object files can be inter-linked.   * Decide on the [[ArchitectureSpecificsMemo|architecture ABI details]] and the GNU triplet. A different GNU triplet is required for each ABI, which includes bitness, endianness, soft/hard-float, calling convention, or whether object files can be inter-linked. Document the details of the ABI/psABI.
Line 69: Line 69:
  * Add your architecture to the [[Teams/Debbugs/ArchitectureTags|bugs arch usertags page]]. You can use the proposed mailing list name for usertags even while it doesn't exist. If the list name gets changed before it is accepted, then you can move all existing bug usertags to the new list name. Once it exists you can start using it in the [[https://www.debian.org/Bugs/Reporting#xcc|X-Debbugs-CC psuedo-header]] in bug reports.   * Add your architecture to the [[Teams/Debbugs/ArchitectureTags|bugs arch usertags page]].
Line 99: Line 99:
  * Grow the hardware ecosystem until it satisfies the [[https://dsa.debian.org/ports/hardware-requirements/|requirements for an official port]].   * Grow the hardware ecosystem until it satisfies the [[https://dsa.debian.org/ports/hardware-requirements/|requirements for an official port]]. Prepare a document describing how the current/planned hardware for the port meets these requirements. If an official port can no longer satisfy these criteria, it may be converted back to an unofficial port.
Line 101: Line 101:
  * Improve the port until it satisfies the [[https://ftp-master.debian.org/archive-criteria.html|criteria for being included in the main archive]].   * Improve the port until it satisfies the [[https://ftp-master.debian.org/archive-criteria.html|criteria for being included in the main archive]]. Document (with a wiki page named after the port below ArchiveQualification) how the port satisfies the criteria, by answering the questions included in the archive criteria. If an official port can no longer satisfy these criteria, it may be converted back to an unofficial port.
Line 103: Line 103:
  * File a request against the [[https://bugs.debian.org/ftp.debian.org|ftp.debian.org]] [[https://www.debian.org/Bugs/pseudo-packages|pseudo-package]] for inclusion of the port amongst the official ports.   * File a request against the [[https://bugs.debian.org/ftp.debian.org|ftp.debian.org]] [[https://www.debian.org/Bugs/pseudo-packages|pseudo-package]] for inclusion of the port amongst the official ports, linking to the ArchiveQualification page for the port.
Line 105: Line 105:
  * Donate hardware for the official buildds and co-ordinate with [[Teams/DSA|the Debian sysadmins]] via the [[Teams/DSA/RTUsage|request-tracker]] to setup the hardware in Debian hosting locations.   * Send to [[Teams/DSA|the Debian sysadmins]] the document about how the port hardware meets the hardware requirements, donate appropriate hardware for the official buildds/porterboxen and co-ordinate with them via the [[Teams/DSA/RTUsage|request-tracker]] to setup the hardware in Debian hosting locations.
Line 123: Line 123:
  * Improve the port until it satisfies the [[https://release.debian.org/testing/arch_policy.html|criteria for being included in a Debian release]], updating the [[https://release.debian.org/testing/arch_qualify.html|qualification status]] as progress is made on each of the criteria.   * Improve the port until it satisfies the [[https://release.debian.org/testing/arch_policy.html|criteria for being included in a Debian release]], updating the [[https://release.debian.org/testing/arch_qualify.html|qualification status]] as progress is made on each of the criteria. These criteria must be satisfied for each new Debian release and are [[ReleaseRecertification|recertified]] each time Debian makes a new release. If an official port can no longer satisfy these criteria, it may be converted back to an unreleased official port, or even an unofficial port.
Line 132: Line 132:

  * Make the port more accessible by donating hardware to the [[https://build.opensuse.org/|openSUSE Build Service]] and or setting up a community and or commercial cloud service. This is recommended so that people outside Debian also have access to hardware for porting.

This is an aspirational document describing the most ideal procedure for creating a new port and getting it included into Debian. Since every port will have different circumstances, the procedure may differ for your port, but the best way to do it should be documented below. It is a work in progress and is based on the port template wiki page.

If you encounter any unfamiliar jargon, please refer to the Debian glossary for more information.

If you require help at any stage, each section below may include specific teams to contact or the debian-devel mailing list may be able to provide fallback assistance.

When filing bug reports with Debian that are related to your port, please use architecture usertags to mark the bugs as relating to your port. Until your port family has a mailing list, you can use a likely mailing list name for usertags even while it doesn't exist. If the list name gets changed before it is accepted, then you can move all existing bug usertags to the new list name. You should not use the mailing list name in the X-Debbugs-CC psuedo-header until it exists, once it exists you should start using it. Do not add the usertags and X-Debbugs-CC for your architecture to a bug report if the bug also applies to more commonly used architectures like amd64.

/!\ It is best to not skip any of the steps.

/!\ It is best to complete each item before moving to later steps.

Preparation

  • Assemble a team of people working on the port and find a financial sponsor to support the team's work.

Upstreaming

  • Decide on the architecture ABI details and the GNU triplet. A different GNU triplet is required for each ABI, which includes bitness, endianness, soft/hard-float, calling convention, or whether object files can be inter-linked. Document the details of the ABI/psABI.

  • Register accounts for each team member on the bug trackers and subscribe to the mailing lists for upstream projects: GNU config, binutils, gcc, gdb, qemu, kernel (such as Linux), and libc (such as glibc)

  • Prepare kernel and toolchain patches supporting the port and get the necessary changes included into these upstream projects: GNU config (instructions), binutils, gcc (instructions), gdb (instructions), the kernel (such as Linux (info)) and the libc (such as glibc (instructions)) (in that order)

  • If hardware supporting your port is not yet available or your hardware or FPGA softcore or software model is quite slow, prepare patches for the appropriate simulator/emulator upstream project (such as qemu (instructions)). If you do not need this, it will still be very useful to complete at some point, so consider completing it later on.

Downstreaming

  • Identify related ports and ISAs, decide that the port is worth creating and detail the reasons why.
  • Register accounts for each team member on the Debian wiki (registration) and Salsa (register).

  • Register and verify accounts for each team member on the OFTC IRC chat network and join the #debian-bootstrap, #debian-ports and other Debian IRC channels.

  • Discuss the port with the community. Please send an email to the debian-devel mailing list. If the port is related to some other architectures, ensure you CC the mailing list for the architecture family. Also join the #debian-bootstrap and #debian-ports IRC channels.

  • Finalise the architecture details, especially including the ABI and CPU baseline requirements.
  • Get any necessary changes included into dpkg (instructions), to get the new Debian architecture name supported (which is the name that end-users will use for the architecture), this requires having the architecture ABI details clear, the Debian multiarch tuple is derived from the Debian architecture tuple.

Bootstrap

  • You can discuss the bootstrap stage on the debian-cross mailing list or the #debian-bootstrap IRC channel.

  • Prepare patches supporting the port in rebootstrap and other Debian-specific packages.

  • Use your modified rebootstrap, the other patches and manual bootstrapping to build all of build-essential.

  • Keep working on the bootstrap process until all of build-essential is installable with debootstrap.
  • Continue building as many packages as you can using the new build-essential packages.
  • Get any remaining changes included into the upstream projects that you have modified.
  • Get any necessary changes included into rebootstrap and other projects involved in the bootstrap process.

Unofficial port

  • You can discuss the unofficial port stage on the specific mailing list and IRC channel for your port or the #debian-ports IRC channel.
  • Register the port on the Debian wiki, replace "example" throughout the page with the chosen architecture details and fill out as many details as you have.

  • Summarise the details of the architecture and ABI on the arch summary wiki page.

  • Setup communication channels for the architecture. Use the architecture family as the name of any communication channels you create, just in case additional related architectures are created later. A mailing list and IRC channel are recommended. These should be named after the architecture family name, not after the Debian port/architecture name.

  • Add your architecture to the bugs arch usertags page.

  • Get the port included amongst the unofficial ports.

  • Setup unofficial buildd servers (automated setup) for the port, either in qemu or hardware.

  • Include the port on the ports list on the Debian website and add the end-user name for the port to the website arches data. If you create a page on the website, create one named after the architecture family, just in case additional related architectures are created later.

  • Monitor build failures (1 2) and continually fix issues.

  • Optionally, donate hardware for the GCC compile farm. It is recommended to do this so that people outside Debian also have access to hardware for testing toolchains or other software on your port.

  • Setup porterboxen for Debian package maintainers to login to and port packages.

  • Optionally, discuss setting up runners for debci with the admins. It is recommended to do this so Debian package maintainers have a way to automatically run as-installed package tests.

  • Optionally, donate hardware for debomatic. It is recommended to do this so Debian package maintainers have a way to automatically trigger custom package builds.

  • Port the Debian installer so that it works on the hardware you have available.

  • Use the Debian installer to install Debian on the hardware you have available.
  • Write some documentation about installing the arch on the hardware you have installed.

  • Submit installation reports for the hardware you have installed.

  • Submit some hardware probes for the hardware you have installed.

Official port

  • Grow the hardware ecosystem until it satisfies the requirements for an official port. Prepare a document describing how the current/planned hardware for the port meets these requirements. If an official port can no longer satisfy these criteria, it may be converted back to an unofficial port.

  • Improve the port until it satisfies the criteria for being included in the main archive. Document (with a wiki page named after the port below ArchiveQualification) how the port satisfies the criteria, by answering the questions included in the archive criteria. If an official port can no longer satisfy these criteria, it may be converted back to an unofficial port.

  • File a request against the ftp.debian.org pseudo-package for inclusion of the port amongst the official ports, linking to the ArchiveQualification page for the port.

  • Send to the Debian sysadmins the document about how the port hardware meets the hardware requirements, donate appropriate hardware for the official buildds/porterboxen and co-ordinate with them via the request-tracker to setup the hardware in Debian hosting locations.

  • The process for switching from an unofficial port to an official port is approximately:
    • The Debian archive admins will import enough binary packages from the unofficial port to be able to setup the official buildds.
    • The Debian hosting providers will connect the hardware to power, network and remote access.
    • The Debian sysadmins will install Debian on the hardware.
    • The Debian buildd admins will setup the hardware as official buildds and connect them to wanna-build and the main archive.
    • The initially imported packages will be rebuilt on the official buildds and imported into the official archive.
    • The official buildds will be updated using the rebuilt packages.
    • The rest of the archive will be rebuilt on the official buildds.
    • The port team will break any build cycles using build profiles and other bootstrap processes (see Ports).

  • Add quality assurance for the port for Reproducible Builds, Debian CI, and piuparts (doesn't yet support non-x86 ports) and other Debian QA efforts.

  • Add support for the port to the live images and cloud images if appropriate hardware exists.

Released port

  • Improve the port until it satisfies the criteria for being included in a Debian release, updating the qualification status as progress is made on each of the criteria. These criteria must be satisfied for each new Debian release and are recertified each time Debian makes a new release. If an official port can no longer satisfy these criteria, it may be converted back to an unreleased official port, or even an unofficial port.

Other work

Unlike the above sections, this one is an unordered wishlist of optional ideas to improve the experience of a port for Debian contributors and users.

  • Improve the port based on reports from users and QA services.
  • Make the port more accessible by adding support for instruction and system emulation to qemu or adding other simulators/emulators to Debian.
  • Make the port more accessible by donating hardware to the openSUSE Build Service and or setting up a community and or commercial cloud service. This is recommended so that people outside Debian also have access to hardware for porting.

  • Make the port support more hardware by upstreaming support to linux-firmware, bootloaders, Linux, udev, mesa, flash-kernel and other projects then updating those projects in Debian.
  • Make the port more complete by porting packages that require porting to every new architecture, including these source packages: lintian linuxinfo
  • Make the port more complete and correct by checking if packages, that are not marked as buildable on the port or not marked as testable on the port, are actually able to be successfully built or tested.
  • Make the port more complete and correct by updating packages that are classified by lintian as needing porting:
    • Ideas for classification tags:
      • debian-control-architecture-blocks-$arch
      • debian-control-build-depends-missing-on-$arch
      • debian-control-depends-missing-on-$arch
      • debian-tests-control-architecture-blocks-$arch
      • debian-rules-checks-architecture-$arch
      • debian-rules-references-architecture-$arch
      • source-code-references-defines-$arch
    • FIXME: this idea is not yet submitted or implemented
  • Make the port more performant by porting or optimising various libraries, language runtimes and signal processing algorithms and cryptography libraries, for example: openssl, gnutls, openjdk, v8, ffmpeg, golang, gccgo, ghc, ocaml, simde
  • Make the port more DFSG compatible by reverse engineering common proprietary firmware, rewriting the firmware, documenting that new open firmware and packaging that firmware for Debian.

  • Make the port available for maintainers and users to cross-build packages to:
    • Add support to the binutils source package

    • Add libc6*-dev-$arch-cross, libc6*-$arch-cross and linux-libc-dev-$arch-cross packages to the cross-toolchain-base (for ftp-master.d.o arches) or cross-toolchain-base-ports (for ports.d.o arches) source packages

    • Add support to the current gcc-N-cross (for ftp-master.d.o arches) or gcc-N-cross-ports (for ports.d.o arches) source package
    • Add metapackages to the gcc-defaults (for ftp-master.d.o arches) source package or gcc-defaults-ports (for ports.d.o arches) source package

    • Add a crossbuild-essential-$arch metapackage to the build-essential source package

  • Make the bootstrap process more trustworthy through Bootstrappable Builds.

  • Make the port used more among Debian contributors by giving away hardware via lottery at DebConf, donating hardware to contributors, providing discounts to Debian contributors for hardware etc.

  • Make the port, the status of it, changes to it and the usage of it more widely known through talks and BoFs at DebConf and other events, DevNews (and other publicity team avenues), by filing bugs from machines running the port, submitting reports to the package popularity contest etc.

  • Make the port more solidly supported through an official partnership with Debian. Support Debian itself through sponsoring DebConf, regular donations or helping Debian more generally.

  • Discuss about gitlab-runners with Teams/SalsaCI. gitlab-runners can be used to run the Salsa CI's pipeline, that provides Debian package maintainers with a way to automatically build and test changes to packages before upload.

  • Discuss with the LTS team about including the port within the releases that have LTS and or eLTS support.