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.

Please note that the people you will interact with in the Debian community are likely volunteers, so please respect their time. Please be patient if they take a long time to complete tasks you have requested. It may be appropriate to send polite followup requests to complete work, but please wait a reasonable amount of time before sending them. Please follow the Debian code of conduct while interacting with the Debian community.

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 pseudo-header until it exists, once it exists you should start using it. The documentation below uses XCC as an abbreviation of X-Debbugs-CC. 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, but some items incur significant delay, so working on them in parallel often is necessary.

Preparation

These steps are useful to support the work needed on the port throughout the process. Once completed, the work will go more smoothly and quickly.

Upstreaming

These steps are useful for adding support for the port to the core upstream projects that Debian inherits much of our architecture support from. Once completed, they will enable the creation of ports for any distro, including Debian.

Downstreaming

These steps are useful for adding support for the port to the core Debian-specific projects that define our architecture support. Once completed, the port will be well defined and it will be possible to start creating it.

Bootstrap

These steps are useful for creating an initial package set used for building the port. Once completed, it will be possible for people to locally build enough packages to create a chroot of the port and build further packages within the chroot.

Unofficial port

These steps are useful for expanding the initial package set for the port from the previous step up to a full unofficial port that is useful for users of Debian unstable. Once completed, it will be possible for users to install chroots or systems of various kinds for testing the port or using it casually, with updates happening daily.

Official port

These steps are useful for ensuring the port is high quality and useful for users of Debian stable. Once completed, it will be possible for users have more confidence in the port and use it in production with security support.

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. Ensure you CC the port mailing list or when filing bugs, XCC the port mailing list.