This small tutorial shows steps I would take to prepare packaging for most of the source packages. For the example hypothetical source package hello of version 1.2.3 is used.

Prerequisites

sudo apt install devscripts debhelper dh-make git git-buildpackage lintian

Steps

  1. Ensure the source package is DFSG-compatible (free software). Non-free source and binary packages will not enter Debian main.

  2. Create a packaging Git repository named after the source package:
     git init hello
     cd hello
  3. Import the source package from URL:
     gbp import-orig --pristine-tar https://example.org/hello.tar.gz

    gbp import-orig will ask some questions, but these are trivial to answer.

  4. Prepare packaging scaffold under debian/ directory using dh_make (general case) or build system-specific tools (mh_make for Maven, dh-make-node for Node and so on; these may need installing additional packages). Source package name and its version has to be provided for dh_make via --packagename option:

     dh_make --packagename hello_1.2.3
  5. Remove unneeded files from under debian/. Most of the files ending in .ex are not mandatory and could be added later if needed. Add debian/ and commit:

     git add debian
     git commit
  6. Build the package:
     gbp buildpackage -uc -us
  7. If the build fails, inspect the reasons of failure. Sometimes turning on the verbose mode in debian/rules helps. Repeat the build-fix-build cycle until successful build is achieved.
  8. Inspect the built binary packages. Check the contents, ensure everything is installed into the expected locations:
     dpkg --contents ../hello_1.2.3-1_all.deb
    Check the dependencies and other relationships with other packages:
     dpkg --info ../hello_1.2.3-1_all.deb
    Install the package and try using it:
     sudo debi
    (debi installs current version of generated Debian package - equivalent manual command would be sudo apt install ../hello_1.2.3-1_all.deb)
  9. Inspect lintian messages. gbp buildpackage runs lintian after successful builds (if lintian is installed). Make sure the package is clean of both errors and warnings, although some warnings may be justified.

  10. To make sure the package will build on buildds, build it for clean Debian Unstable with only the essential packages, possibly by using sbuild.

  11. (Optional) Add autopkgtest.

  12. Upload/ask for sponsorship.

Troubleshooting

  1. Some dependencies are not in Debian yet: Package them or ask someone to do so. All build dependencies have to be packaged.

  2. Non-essential files in the source package are not DFSG-compatible: Repack the source to exclude them.

  3. Package build downloads files from the network: This must not be done.