new wanna-build specification

ToDo

We should log what buildds and scripts really call.

We should handle epochs sanely and try to fit that into the compatibility layer. They used to need --override anyway so there wouldn't be a regression.

States

The states as defined by the old wanna-build are as follows:

Needs-Build: The package needs to be built. Set by the wanna-build maintainance run or by giving back packages which failed to build.
Building: The package is currently being taken for building. Set by the buildd through take.
Built: The package built successfully on a buildd and awaits signing by its owner. Set by the buildd.
Build-Attempted: The package was tried on a buildd but possibly failed to build. It is pending investigation by the buildd admin. Set by the buildd.
Uploaded: The package got built and signed and was uploaded to the archive. The confirmation that it reached the archive successfully is pending, however. Set by the buildd.
Installed: Package got built successfully by someone and is in the archive now. Set by the wanna-build maintainance run.
Dep-Wait: Waiting for additional source dependencies. Will return into Needs-Build as soon as those are available. Set by the buildd admin or other caring persons.
Failed: Failed to build in a way that it will require a new upload in order for the bug to be fixed. Set by the buildd admin.
Not-For-Us: Do not build on this architecture. Mostly needed because the source architectures are not known to wanna-build (yet?). Another solution for this state was Packages-arch-specific, which removed the entry of a package from many architecture databases at once. Set by the buildd admin.
Failed-Removed: This state was used to denote that a package failed to build before it was removed from the database. Set by the wanna-build maintainance run.

Notes

quinn-diff generates two kinds of hints about how important it is to compile a given package that is currently missing on an architecture.

out-of-date: This state specifies that the package built on the architecture previously and that the old binary is still around.
uncompiled: This state signals that the package is not currently present on the architecture at all.

Build Priorities

The old wanna-build used some sort of priority system to determine the order in which the packages in Needs-Build were returned to the buildds to allow them to take the first n packages.

The order used was (in order of importance, most important listed first): build priority, prefer packages with source priority less or equal standard, impose a penalty for uncompiled packages, source priority, source section and last but not least alphanumerical order over the source package name.

These basic build priorities for every priority and section were hardcoded in the old wanna-build.

Source Priority	Value
required	-5
important	-4
standard	-3
optional	-2
extra	1
unknown	-1

Source Section	Value
libs	-200
debian-installer	-199
base	-198
devel	-197
shells	-196
perl	-195
python	-194
graphics	-193
admin	-192
utils	-191
x11	-190
editors	-189
net	-188
mail	-187
news	-186
tex	-185
text	-184
web	-183
doc	-182
interpreters	-181
gnome	-180
kde	-179
games	-178
misc	-177
otherosfs	-176
oldlibs	-175
libdevel	-174
sound	-173
math	-172
science	-171
comm	-170
electronics	-169
hamradio	-168
embedded	-166
unknown	-165

Sections prepended by contrib/ get 40 added to their base section value, non-free/ get 80 added.

Compatibility Helper

The compatibility helper will be named wanna-build to be used as a drop-in replacement for the old binary. It must pretend to be the old wanna-build in command-line options, input and output formats. It must be compatible with the buildds in any way they call it and it should be compatible with other tools used to administrate the build database.

Dropped Features

We will not implement the previous maintainance operations through the helper. Furthermore there will be no category system for builds in failed. This feature was rarely used if at all.

Command-line options

Usage: wanna-build <options...> <package_version...>

`--take`	Take package for building (buildd operation, default!)
`--built`	Record a (maybe-)successful build.
`--attempted`	Record a (maybe-)failed build.
`--uploaded`	Record that a given package has been built and got uploaded.
`--give-back`	Returns the source package in question into the state `Needs-Build`.
`--dep-wait`	Puts the source package into state `Dep-Wait` with the given set of dependencies to be fulfilled. New ones are merged with older ones if already in state `Dep-Wait` unless -o is specified. Reads one line from stdin as its input or takes it from the message parameter.
`--binNMU <ver>`	Schedules a binary NMU with the given version `+b(ver)`. The message will be copied into the changes file generated by sbuild. Reads one line from stdin as its input or takes it from the message parameter.
`--failed`	Sets build to `Failed` and reads a rationale from stdin until a single dot alone on its line. Will also take its text from the message parameter.
`--no-build`	Sets the source package's entry to `Not-For-Us`, preventing further building on the named architecture.
`--build-priority <prio>`
	Sets a new build priority for a specific build.
`--perm-build-priority <prio>`
	Sets a new permanent build priority for a source package.
`--info SRCPKG, -i SRCPKG`
	Retrieves a source package's record out of the database, no version needs to be supplied.
`--list=STATE, -l STATE`
	Lists all packages in state STATE or all. Can be restricted with -U. Format as documented below.
`-b <db>`	Specifies which database to use. This has been `<arch>/build-db` in the past and we will not support any other string.
`--dist=DIST, -d DIST`
	Specifies which distribution the changes apply to. Might also be something like `testing-security` to specify the security wanna-build.
`-U <user>`	Set the user you want to make changes under / whose builds you want to list.
`-o`	Override other users' locks. Meaning might be different depending of the mode of operation.
`-m <message>`	Some commands need additional text to be supplied.
`--min-age, --max-age`
	Only one of both might be specified. Holds the age in days that should have passed since the last state change and selects the set before or after it.
`--no-propagation, --no-down-propagation`
	Both options should be accepted but do nothing. They were compatibility options in the old wanna-build.
`--pretend-avail`
	Marks packages as being available now, causing dep-waits set on them to be cleared.

Actions

Please note: warn means that a warning is printed but that the request is processed anyway. skip means that the request will not be processed at all, and processing will continue with the next package specified. All actions listed here need the sanity check that a given package or package, version tuple exists in the database.

take:

# Attention: might need epoch handling for installed
skip if state in [not-for-us, dep-wait, uploaded, installed]
if state = needs-build
  if version < current-version
    skip unless overridden
if state in [building, built, build-attempted]
  if current-version < version
    notify buildd admin about takeover (for build abort)
  else
    if buildd = requestee
      ok
    else
      skip unless overridden
if state = failed
  skip unless overridden
pass binNMU data if applicable
set state to building
record buildd

built:

skip if state != building
skip if builder != requestee
skip if version mismatch
record successful attempt

attempted:

skip if state != building
skip if builder != requestee
skip if version mismatch
record failed attempt

uploaded:

skip if state not in [building, built, build-attempted]
skip if builder != requestee
# Attention: compatibility code in w-b to strip epoch
skip if version mismatch # also check for binNMU
set state to uploaded

give-back:

skip if state = dep-wait unless overridden
skip if state in [building, built, build-attempted] unless overridden
skip if builder != requestee # should be waived!
skip if version mismatch
set state to needs-build

dep-wait:

merge deps if state = dep-wait
warn if state in [needs-build, failed]
skip if state in [not-for-us, failed-removed, installed, uploaded]
skip if builder != requestee # should be waived!
skip if version mismatch
skip if bad dep list
set state to dep-wait
set dep list

binNMU:

skip if version mismatch
if binNMU-ver == 0
  cancel pending binNMU
  end
skip if state != installed
skip if binNMU version already present or lower than current
skip if binNMU <= installed-version
set note to out-of-date
set binNMU version and changelog
set state to needs-build

failed:

skip if state in [not-for-us, failed-removed, installed]
skip if builder != requestee # should be waived!
skip if version mismatch
warn if state in [needs-build, uploaded, dep-wait]
if state in failed
  warn
  append message
set state to failed
record message

no-build:

if state != not-for-us
  set state to not-for-us
  clear unused fields
else
  # revert not-for-us
  set state to failed
  set failed reason to "Was Not-For-Us previously"

New Table Layout

Table: source

Column	Type	Constraints
source_id	bigserial	primary key
source_name	varchar	unique, not null
source_build_priority	int	null

Table: maintainers

Column	Type	Constraints
maintainer_id	bigserial	primary key
maintainer_name	varchar
maintainer_email	varchar
maintainer_type	bigint	references maintainer_types, not null

Table: maintainer_types

This table will be used to save maintainer types like Maintainer, Uploaders, NMUer and global. We should be able to deduce granular rights to specific builds by allowing for example the maintainer and uploaders of a package give-backs and dep-waits for all builds in all suites, while we only grant this to the NMUer for a specific build in a distribution.

Column	Type	Constraints
maintainer_type_id	bigserial	primary key
maintainer_type_title	varchar	not null