"apt install bbl" needs to be default installation method in Ubuntu/Debian

[nehemiaharchives]

Following is Debian Package Submission Guide Created with 2.5 Flash July 9, 2025 at 05:45 PM
Published July 9, 2025 at 05:47 PM

That's an ambitious and commendable goal! Getting a package into the official Debian repositories means it will be widely available to millions of users, is subject to high-quality standards, and benefits from the robust Debian infrastructure. It's a significant undertaking, but definitely achievable.

Here's a step-by-step guide to get "bbl" into the official Debian repositories:

Phase 1: Preparation and Learning

1. Understand Debian Policy: This is the most crucial step. Debian has a strict set of guidelines that all packages must adhere to. Read the entire [Debian Policy Manual](https://www.debian.org/doc/debian-policy/) thoroughly. Pay special attention to:

   • Filesystem Hierarchy Standard (FHS): Where files should be placed (e.g., binaries in /usr/bin, man pages in /usr/share/man, documentation in /usr/share/doc).
   • Licensing: Your software (bbl) must be Free Software according to the [Debian Free Software Guidelines (DFSG)](https://www.google.com/search?q=https://www.debian.org/social_contract/%23guidelines). This is non-negotiable. If bbl isn't DFSG-compliant, it cannot be in the main archive.
   • Dependencies: How to declare dependencies correctly.
   • Maintainer Scripts: (preinst, postinst, prerm, postrm) if your package needs special actions during installation/removal.
   • Package Naming Conventions.
   • Documentation Requirements: Man pages, copyright files, changelogs.

2. Learn Debian Packaging Tools: You'll need to become proficient with the tools used for Debian packaging. Key tools include:

   • dpkg-buildpackage: The primary tool for building Debian packages.
   • dh_make: To create initial Debian packaging files from your upstream source.
   • debhelper: A suite of programs that automate common packaging tasks (highly recommended and widely used).
   • lintian: A tool to check your package against Debian Policy and common packaging errors. Run this constantly!
   • dch/dpkg-buildpackage -S: For managing the debian/changelog file.
   • debsign: For signing your packages with your GPG key.
   • dput: For uploading packages to Debian archives (once you have a sponsor).
   • pbuilder/sbuild/cowbuilder: Tools to build packages in a clean, chrooted environment. This is essential to ensure your package builds correctly without relying on extraneous files on your system.

3. Study Existing Packages: Look at how similar, well-maintained packages are structured in Debian.

   • Find a package in Debian that has similar functionality or uses similar build systems as bbl.
   • Download its source package: apt-get source <package-name>
   • Examine the debian/ directory within the extracted source. This directory contains all the Debian-specific packaging files.

4. Join Debian Mailing Lists/Community:

   • Subscribe to debian-mentors@lists.debian.org and debian-devel@lists.debian.org. These lists are vital for getting help, asking questions, and finding a sponsor.
   • Familiarize yourself with the [Debian New Maintainers' Guide](https://www.debian.org/doc/manuals/maint-guide/index.en.html) (though it's somewhat outdated, the "Guide for Debian Maintainers" is more current) and the [Debian Developer's Reference](https://www.debian.org/doc/manuals/developers-reference/index.en.html).

Phase 2: Packaging Your Software (bbl)

1. Get Your Upstream Source Ready:

   • Ensure your bbl project has a clear versioning scheme.
   • Make sure it builds cleanly from source without manual intervention (e.g., a standard make, make install process).
   • Include a README and COPYING (or LICENSE) file with the full license text.
   • Have a CHANGELOG for your project's upstream changes.
   • Ensure your upstream source can be built in a standard way (e.g., using autotools, cmake, a Makefile).

2. Create the Debian Source Package Structure:

   • Start with a clean copy of your bbl source code.
   • Navigate into the bbl source directory.
   • Run dh_make to create the initial debian/ directory. It will ask you a few questions (type of package, license, etc.).
     • For a simple application like a command-line reader, single (single binary package) is likely appropriate.
     • Choose the correct license type.
   • This will populate the debian/ directory with template files like control, changelog, copyright, rules, compat, etc.

3. Edit Debian Packaging Files: This is the core of the packaging process.

   • debian/changelog:

     • This file tracks changes specific to the Debian package, not the upstream code.
     • Use dch -i (or dch --create) to add your initial entry.
     • The first entry usually starts with "Initial release" or "New upstream release".
     • Follow the format: package-name (version) distribution; urgency=urgency
     • Example: bbl (1.0-1) unstable; urgency=medium
     • Subsequent entries will automatically be added with dch -i.

   • debian/control:

     • Source: Your source package name.
     • Maintainer: Your name and email address. This is your responsibility.
     • Build-Depends: List all packages required to build bbl. Use apt-get build-dep <package-name> on a clean system to help identify these, but confirm them manually. Examples: debhelper-compat (= 13), build-essential.
     • Standards-Version: The Debian Policy version your package conforms to.
     • Homepage: Your project's website.
     • Vcs-* (optional but recommended): Links to your version control system (Git, etc.) for the Debian packaging. Many Debian maintainers use Salsa (Debian's GitLab instance) for this.
     • Package: The name of the binary package(s) your source package produces. (e.g., bbl).
     • Architecture: any if it compiles on all architectures, all if it's architecture-independent (e.g., shell script, Python script without native modules). For bbl, it's likely any.
     • Depends: Runtime dependencies for the binary package.
     • Description: Short and long descriptions of bbl. Write this carefully, explaining what bbl does and why a user would want it. Avoid jargon where possible.

   • debian/copyright:

     • This file details the license of the upstream source and the Debian packaging files.
     • Be very precise. Include the full text of bbl's license.
     • Specify the copyright holders for the original work and the Debian packaging.

   • debian/rules:

     • This is an executable Makefile that controls the build process.
     • dh_make generates a debian/rules file that uses dh (debhelper) for automation. This is the recommended approach.
     • You'll likely need to customize this to ensure bbl is built and installed correctly. For example, if your Makefile isn't standard, you might need to override dh_auto_configure or dh_auto_build.
     • Make sure bbl binaries are installed into the correct FHS-compliant paths (e.g., /usr/bin).
     • Ensure man pages (if you have them) are installed into /usr/share/man/man1/.

   • debian/*.install (or debian/*.links, etc.):

     • These files tell debhelper where to install specific files from your build directory into the final binary package.
     • Example: usr/bin/bbl in debian/bbl.install.

   • debian/manpages (if applicable): List of man pages to install.

4. Build and Test Locally (Crucial!):

   • Install build dependencies: sudo apt-get build-dep . (run from the root of your bbl source directory with the debian/ folder).
   • Build the package: dpkg-buildpackage -us -uc (unsigned source and binary).
     • Alternatively, use debuild -us -uc (which wraps dpkg-buildpackage and runs lintian afterwards).
   • Build in a clean chroot: This is highly recommended to catch missing build dependencies.
     • Install pbuilder or sbuild.
     • Set up your pbuilder/sbuild environment.
     • Run pdebuild or sbuild.
   • Check with Lintian: lintian <your-package-name>_<version>_<architecture>.deb
     • lintian will flag any policy violations or common errors. Fix all errors and warnings if possible. Justifications can be made for some warnings, but errors must be addressed.
   • Install and test: sudo dpkg -i <your-package-name>_<version>_<architecture>.deb
     • Test bbl thoroughly after installation.
     • Check that all files are in the right place.
     • Test removal: sudo apt-get remove --purge bbl

Phase 3: Seeking a Sponsor and Uploading

1. Find a Debian Developer (DD) Sponsor:

   • You, as a new maintainer, cannot directly upload to the Debian archives. You need a Debian Developer (DD) to sponsor your package.
   • Where to find a sponsor:
     • debian-mentors@lists.debian.org: This is the primary mailing list for prospective maintainers to find sponsors and get help with packaging. Post a clear request, providing a link to your package's source and binary files (e.g., on a personal website, GitHub, or Debian's Salsa instance if you've pushed your work there).
     • mentors.debian.net: This platform helps connect prospective maintainers with sponsors. Upload your source package (.dsc, .orig.tar.gz, .debian.tar.xz) here.
     • Reach out to DDs you might know or whose work you admire, especially if they maintain similar packages.
   • Be prepared for review: The sponsor will review your package for policy compliance, quality, and correctness. They might ask you to make several revisions. Be patient and willing to learn.

2. Package Review and Iteration:

   • Your sponsor will guide you through any necessary changes. This iterative process can take time.
   • They might ask you to improve your debian/rules, fix lintian warnings, or clarify your debian/copyright.

3. GPG Signing:

   • Once your package is deemed ready by the sponsor, you will need a GPG key to sign the .dsc and .changes files.
   • Your sponsor will typically guide you on this, or sign it themselves if they are making the final upload. For official uploads, your key needs to be in the Debian keyring.

4. Upload to the Debian New Queue:

   • Your sponsor will use dput or dupload to upload your package to the Debian NEW queue (ftp://ftp.upload.debian.org/pub/UploadQueue/).
   • The NEW queue is a holding area where packages are reviewed by the Debian FTP Masters and the Debian Release Team.

5. FTP Master Review:

   • The FTP Masters will perform a final review of your package, checking for critical issues, license compliance, and policy violations.
   • This process can take anywhere from a few days to several weeks, depending on the queue size and complexity of your package.
   • If issues are found, your package will be rejected, and you'll receive feedback to fix them and re-upload (via your sponsor).

6. Package Acceptance and Migration:

   • Once the FTP Masters approve your package, it moves into the unstable distribution.
   • From unstable, it will eventually migrate to testing (after a period of no critical bugs and all its dependencies are also in testing).
   • Finally, testing becomes the next stable release after a release freeze and extensive testing.

Important Considerations and Tips:

• Patience: This process takes time. From initial packaging to appearing in a stable release, it can easily be many months, even a year or more. Don't rush it.
• Communication: Be responsive and polite in your interactions with the Debian community and your potential sponsor.
• Documentation: Read, read, read! The Debian Wiki, Developer's Reference, and Policy Manual are your bibles.
• Start Simple: If bbl is your first package, congratulations! If you have other smaller, simpler projects, packaging one of those first might be a good way to learn the ropes.
• Version Control: Use Git (or similar) for your Debian packaging work. It helps track changes and makes collaboration easier. Salsa is an excellent platform for this.
• Maintainership: Once your package is in Debian, you become its maintainer. This means you're responsible for keeping it updated, fixing bugs, and responding to user reports.

This journey is demanding but incredibly rewarding. Good luck with getting bbl into the official Debian repositories!