chiko for Debian
================

Layout of this repository
-------------------------

This repository carries the upstream source tree with debian/ added on top.
Outside debian/ it is a verbatim copy of upstream's main branch, currently
commit 8e5d9f9 ("fix: versioning", tagged v0.2.0).

That copy has to stay verbatim.  The source format is 3.0 (quilt), so the
upstream part of the tree is compared against the orig tarball when the
source package is built, and any difference outside debian/ makes
dpkg-source abort with "aborting due to unexpected upstream changes".  A
change to upstream's code therefore belongs in debian/patches, and a new
upstream release is imported by copying the new tree over this one, again
excluding debian/.

Two consequences worth knowing:

  * .gitignore is upstream's file and must not be edited.  Ignore rules for
    the build products live in .git/info/exclude instead, which is local to
    the clone and not part of the tree.

  * upstream's .gitignore contains a bare "chiko" entry, which also matches
    the cmd/chiko/ directory.  Re-adding that directory after a fresh import
    needs "git add -f cmd".

Building
--------

An orig tarball is needed beside the tree, holding the same upstream source
without debian/:

    tar --exclude=./debian --exclude=./.git --exclude=./_build \
        --exclude=./.pc --transform 's|^\./|chiko-0.2.0/|' \
        --sort=name --owner=0 --group=0 --numeric-owner \
        -cJf ../chiko_0.2.0.orig.tar.xz .
    dpkg-buildpackage -us -uc -b      # binary package
    dpkg-buildpackage -us -uc -S      # source package

Submitting to the BlankOn build farm
------------------------------------

irgsh builds the orig tarball itself, from the upstream repository given by
--source.  Upstream's default branch is main, which is not irgsh's default,
so it has to be named explicitly:

    irgsh-cli package --dist sinambung \
        --source https://github.com/felangga/chiko.git --source-branch main \
        --package https://github.com/blankon-packages/chiko.git \
        --package-branch main

Keeping the upstream source in this repository is what lets irgsh's
pre-submit local build work: it builds the packaging tree directly, so a
tree holding debian/ alone has nothing for debian/rules to compile.

This package REQUIRES NETWORK ACCESS AT BUILD TIME
--------------------------------------------------

chiko is a Go program.  Its dependencies are neither vendored in the source
package nor taken from golang-*-dev packages: debian/rules downloads them
from the Go module proxy (https://proxy.golang.org) while the package is
built.

The consequence is that this package cannot be built in a network-isolated
environment.  In particular it will NOT build on a Debian buildd, nor under
sbuild or pbuilder with their default settings, and it is therefore not
suitable for upload to the Debian archive as it stands.  Build it on a
machine with working internet access.  Under sbuild, network access has to be
granted explicitly, for example:

    sbuild --enable-network

Integrity of the downloads is not taken on trust.  debian/rules runs
"go mod download all" followed by "go mod verify", both of which check the
cryptographic hashes recorded in upstream's go.sum, and GOSUMDB is left at
sum.golang.org so that new modules are checked against the public checksum
database as well.  A proxy serving tampered code is detected and fails the
build.

Everything downloaded is placed under _build/gopath inside the build tree,
so the build never writes to the user's ~/go and "debian/rules clean"
removes all of it.

Why not vendor, or use Debian's Go libraries?
---------------------------------------------

Vendoring was deliberately dropped at the maintainer's request.  Using
golang-*-dev build dependencies instead is not currently possible either:
four of chiko's dependencies are absent from Debian, including the ones
chiko is principally built on.

    github.com/fullstorydev/grpcurl
    github.com/jhump/protoreflect
    github.com/bufbuild/protocompile
    github.com/epiclabs-io/winman

Packaging those four for Debian is the prerequisite for a fully offline,
archive-acceptable build.

Licensing of the dependencies
-----------------------------

Because the dependencies are not shipped in the source package, their
licences cannot be documented with per-file stanzas.  They are summarised in
the header of debian/copyright instead, and the licence texts are reproduced
there in full.  When updating to a new upstream release, check whether the
dependency set in go.mod gained a module under a licence not already listed.

 -- Herpiko Dwi Aguno <herpiko@gmail.com>  Sat, 26 Sep 2026 00:00:00 +0700