dak/docs/README.commands

COMMAND FILE SYNTAX                                  -*- mode: Org -*-

* General
Command files allow Debian Developers to handle various archive
related tasks without the help of a FTPMaster. This is done by
creating and uploading a signed file named

$login-EPOCH.dak-commands

using the general header described below - and as many individual
command action sections as wanted. See the "Action" part for more
information on the various available actions.
** General Header
#+BEGIN_EXAMPLE
Archive: ftp.debian.org
Uploader: A Developer <adeveloper@example.com>
#+END_EXAMPLE

The general header is followed by an empty line and then at least one
action section.

** Signature
The file needs to be signed by a valid key from the Debian uploader
keyrings.

** Upload
This file has to be uploaded to ftp.upload.debian.org. Don't use any
of the queues we provide elsewhere, they are not handling the files.

** Break the archive
There may be bugs in this interface. If you find any, please tell us,
and please DO NOT use it to break-the-archive.

* Actions
Note: Options are listed as (R)equired or (O)ptional.
** dm
Options: Fingerprint (R)
         Deny (O)
         Allow (O)

dm changes Debian Maintainer ACL, allowing or forbidding DMs to upload
packages on their own. The Fingerprint listed needs to correspond to a
key in the DM keyring. It can be followed by one ore more Allow or
Deny options.The Deny option has precedence, so allowing and then
denying a package in the same run (even in different action parts of
type dm) will forbid the DM to upload said package.

Both the DD and DM will get a mail notification about any changes
taken.
#+BEGIN_EXAMPLE
Action: dm
Fingerprint: 1234567890ABCDEF1234567890ABCDEF
Allow: one-package another-package
Deny: yet-another-package
#+END_EXAMPLE
*** DM data

To check the archives knowledge about DMs you can look at the export[DMURL]
updated during dinstall. This file is machine-readable in the usual 822
format we here at Debian love so much, with stanzas like

[DMURL] https://ftp-master.debian.org/dm.txt
** bikeshed-create
Options: Bikeshed (R)
         Base-Suite (R)
         Description (R)
         Package (O)
         Owner (O)
         Uploader (O)
         Auto-Update (O)
         Breaks (O)
         Depends (O)
         Architecture (O)

Create a new bikeshed, based on given base-suite. It can initially
import one or more packages given by the Package option from the base
suite.

Bikeshed: The name of the bikeshed, must start with bs- and otherwise
be unique.

Base-Suite: The name of the base suite. Can be the codename or alias
of a suite, but aliases (like unstable/testing) will be resolved at
creation time and the codename be used, bikesheds will not
automatically change during release time.

Description: A one-line description of the bikeshed.

Package: A name of a source package to import from the base-suite.
Repeat as often as needed.

Owner: The bikeshed will default to one Owner user (the uploader of
the commands file), this option adds as many more as wanted. Owner
takes fingerprints as value. Note that any Owner can do everything,
including demolishing a bikeshed.

Uploader: The bikeshed can allow uploads from a limited set of
people - or from everyone. If this option is not listed, then every DD
and DM can upload to this bikeshed, same rules as in main archive
apply. (eg., DMs need an ACL set for their package).
To limit uploads to the bikeshed, include a list of fingerprints using
this option.

Auto-Update: True or False. Automatically update packages imported
from the base suite, whenever they get updated in the base suite. This
may possibly break packages uploaded directly to the bikeshed.

Breaks: Name of another bikeshed which is broken by this, that is,
both together should not ever be used on one system.

Depends: Name of another bikeshed which this one depends on, that is,
both should be used together.

Breaks and Depends are (currently) only advisory and only used to
output that information on a webpage. Tools may implement better
support for them in the future.

Architecture: If this is unset the bikeshed will have the same
architectures as the base suite. Otherwise list each architecture
needed in the bikeshed. (source and all are automatically added).

#+BEGIN_EXAMPLE
Action: bikeshed-create
Bikeshed: bs-theoneandonly
Description: This is all you need, ever
Base-Suite: sid
Package: mailfilter
Auto-Update: True
Breaks: bs-doesnotyetexistbutihateitalready
Depends: bs-ohthisisevenbetter
#+END_EXAMPLE
Create bs-theoneandonly bikeshed based on sid including the mailfilter
package from sid at time of creation. Uploads are allowed by anyone in
the uploading keyrings, whenever mailfilter is updated in sid it will
also be put into theoneandonly bikeshed automatically.

#+BEGIN_EXAMPLE
Action: bikeshed-create
Bikeshed: bs-ohthisisevenbetter
Description: But you may also want this as an addition
Base-Suite: rc-buggy
Package: mailfilter
Package: emacs24
Package: xz-utils
Package: openvpn
Owner: 1234567890ABCDEF1234567890ABCDEF12345678
Owner: 234567890ABCDEF1234567890ABCDEF123456789
Uploader: ABCDEF1234567890ABCDEF123456789012345678
Uploader: BCDEF1234567890ABCDEF1234567890ABCDEF123
Uploader: CDEF1234567890ABCDEF1234567890ABCDEF1234
Uploader: DEF1234567890ABCDEF1234567890ABCDEF12345
#+END_EXAMPLE
Create the bs-ohthisisevenbetter bikeshed, this time based on
experimental (rc-buggy) importing not only mailfiter but also 3 more
packages. Besides the uploader of the command file there are 2 more
Owners allowed to maintain the bikeshed, and besides the Owners
there are 4 additional fingerprints allowed to upload to this
bikeshed. None of the imported packages will be automagically updated
from an upload to the base suite.

** bikeshed-drop
Options: Bikeshed (R)

Drop a bikeshed. This is irreversible, be careful.

Any Owner of a bikeshed can do this.

** bikeshed-demolish
Alias for bikeshed-drop, see there for documentation.

** bikeshed-modify
Options: Bikeshed (R)
         Description (O)
         Breaks (O)
         Depends (O)

Modify the description, breaks and depends settings of a bikeshed, see the
bikeshed-create description for their meanings.

** bikeshed-paint
Alias for bikeshed-modify, see there for documentation.

** bikeshed-acl
Options: Bikeshed (R)
         Owner (O)
         Uploader (O)

Modify the access list of a bikeshed. The list of Owner/Upload, if
given, completely overwrite the current values of the bikeshed, so a
full list has to be given. As a safety precaution to not fully loose
access to a bikeshed, the uploader of the commands file will be
included into the Owner list, even if they are not listed anymore.

** bikeshed-add-pkg
Options: Bikeshed (R)
         Package (R)
         Suite (O)

Add another package to the bikeshed.

The optional suite parameter changes the suite to import the package
from, if not given the base-suite will be used. This may be a suite
in the main archive, or any other bikeshed.

** bikeshed-rm-pkg
Options: Bikeshed (R)
         Package (R)

Remove a package from the bikeshed. This can apply to packages
uploaded to the bikeshed and to packages imported from the base-suite.

** bikeshed-mergeback
Options: Bikeshed (R)
         Package (O)

If the base-suite of a bikeshed supports the "mergeback" option, this
will try to "migrate" packages from the bikeshed into the base-suite.
The packages will have to follow all the usual constraints that apply
to the base suite during normal package uploads (say, version
constraints).

If no Package line is given, all packages are merged back, otherwise
only the packages listed.

** bikeshed-list
Options: None

List all bikesheds and the access level.

** bikeshed-info
Options: Bikeshed (R)

Returns information about the named bikeshed in a format valid for the
bikeshed-create command, so see there for the format/options outputted.

* Full example
#+BEGIN_EXAMPLE
Archive: ftp.debian.org
Uploader: A Developer <adeveloper@example.com> (optional)

Action: dm
Fingerprint: 1234567890ABCDEF1234567890ABCDEF
Allow: one-package another-package
Deny: yet-another-package
#+END_EXAMPLE