NOME¶

tag2upload - protocolo para enviar para Debian via etiqueta git assinada

INTRODUÇÃO¶

tag2upload é u esquema que permite a um maintainer de pacote Debian atualizar um pacote no arquivo Debian, ao empurrar uma etiqueta git apropriada assinada.

Tipicamente estas etiquetas são criadas com git-debpush, e interpretadas por "dgit-repos-server --tag2upload".

No entanto, as etiquetas são etiquetas git simples, com pequenas quantidades de metadados adicionais, assim podem ser feitas por outras ferramentas.

Este documento define a sintaxe e semânticas da etiqueta.

BÁSICOS¶

Uma etiqueta git assinada é uma instrução para o serviço tag2upload se a mensagem da etiqueta conter uma linha parecida com isto:

 [dgit ... please-upload ...]

A etiqueta tem de ser assinada por alguém com autorização de envio, para o pacote relevante. O objeto etiquetado tem de ser um cometido git. Os metadados acerca da operação pretendida são obtidos a partir de ambos a mensagem da etiqueta e o objeto da árvore git referenciada.

METADADOS DO GIT¶

O nome da etiqueta git tem de ser "DISTRO/VERSION", onde VERSION é o número de versão do pacote Debian transformado para ser válido para git como especificado em DEP-14, e DISTRO é o nome da distribuição (o "fornecedor" DEP-14, "debian" para Debian).

O endereço de email do campo "tagger" do git (isto é, o autor da etiqueta, do ponto de vista do git) para onde serão enviados por email quaisquer relatórios e erro.

METADADOS EM-ETIQUETA DO TAG2UPLOAD¶

O tag2upload reutiliza u formato de metadados de etiqueta, e algumas semânticas de metadados, do dgit.

As linhas de metadados estão no formato "[dgit ...]". Os parênteses retos têm de estar no inicio e fim da linha. Dentro dos parênteses, após "dgit", estão itens de metadados separados por espaços.

Cada item de metadados é "palavra-chave" or "palavra-chave=valor" (dividindo no primeiro "="). As palavras chave começam com um dos caracteres "! - + . 0-9 a-z". Os itens não podem conter espaços em branco. Qualquer linha de metadados cujo primeiro item comece com aspas """ está reservada para futura expansão, e a linha inteira é ignorada.

A colocação e ordem dos itens de metadados não é relevante, excepto para ordem relativa dos itens com a mesma palavra chave. Uma palavra chave pode ser repetida se tal estiver declarado na sua descrição As palavras chave são ignoradas (e podem ser repetidas).

Assim o modelo de dados abstrato duma etiqueta totalmente analisada mas não interpretada é: mapa, desde palavra chave, até sequência não vazia de valores opcionais. Em sintaxe Rust-ish, "Map<String, Vec<Opção<String>>>".

As palavras chave que começam com "!" contêm informação que é crítica para o processamento correcto pelo serviço tag2upload; o serviço vai rejeitar etiquetas que contenham itens "!" desconhecidos.

"please-upload"

Declara que esta etiqueta é de facto uma instrução para um serviço tag2upload, para produzir e enviar um pacote fonte baseado no cometido para o qual a etiqueta aponta.

Os objetos git relevantes irão também ser empurrados para um servidor canónico que pertence à distribuição visada (no caso de Debian, *.dgit.debian.org).

"source=FONTE" "version=VERSÃO"

Especifica o nome e versão do pacote fonte destinado a ser enviado, como também aparece na primeira linha de debian/changelog. Duplicar esta informação nos metadados da etiqueta é necessário para assegurar certas propriedades de segurança.

O pacote e a versão têm de corresponder a debian/control, ou será um erro.

"distro=DISTRIBUIÇÃO"

Especifica uma distribuição visada, para a qual o pacote vai ser enviado. Pode ser repetido.

Cada instância do tag2upload ignora etiquetas que não mencionam a DISTRIBUIÇÃO dessa instância. Assim para uma etiqueta ser efectiva, pelo menos um distro= tem de estar presente.

(Note que DISTRIBUIÇÃO também aparece no nome da etiqueta, assim enviar para múltiplas distribuições involve necessariamente várias etiquetas, apesar de poderem ter o mesma mensagem de etiqueta.)

"upstream"=COMETIDO "upstream-tag"=ETIQUETA

Identifica o código fonte do autor a ser usado.

Isto corresponde ao "orig" no pacote fonte. O tarball de origem será gerado com "git archive", como invocado por "git deborig".

Ambos ou nenhum destes tem de ser fornecido. ETIQUETA tem de ser obtenível a partir do mesmo repositório que a etiqueta tag2upload, e tem de resolver para COMETIDO, o que tem de ser uma cinza não abreviada.

ETIQUETA e requerido de modo a assegurar que COMETIDO é recuperável. Isto porque a maioria dos servidores de repositório git apenas permitem obter etiquetas e ramos e não cometidos arbitrários.

Se estes forem omitidos, qualquer orig necessário tem de já estar presente no arquivo do pacote fonte visado. Com modos quilt "baredebian", esta opção é obrigatória.

(Este item de metadados pode ser ignorado se a árvore git especificar um formato de pacote nativo, ou se o arquivo visado já conter um orig apropriado.)

"!pristine-tar"=COMMITID

Names a commit containing pristine-tar metadata.

The commit must contain exactly one .id file and one .delta for the current upstream release, and their names must correspond to the name of the orig tarball, with ".id" and ".delta" appended, respectively. They must be regular files.

The tag must also contain an "upstream" item, and the tree named in the .id file must be identical to that of the "upstream" commit.

The pristine-tar commit may contain a signature file. The signature file name must correspond to the name of the orig tarball, with ".asc" appended. The signature file will then be published together with the orig tarball. The signature file is treated as pure data by the service (so will not be verified or even format checked).

If an orig tarball needs to be (re)generated, the service will use pristine-tar, using precisely the metadata in the aforementioned files. The resulting tarball's contents must be identical to the named git tree, except that it may also contain empty directories. Specfically, in this comparison, timestamps, ownerships, ordinary 0777 permissions other than executability, and ordering, are disregarded; objects other than plain files with ordinary permissions directories, and symlinks, are forbidden. (So for example, set-id files, POSIX ACLs, and and attributes, are forbidden.)

The named prstine-tar commit must be reachable from the "pristine-tar" branch in the repository.

"--quilt=MODO-QUILT"

Especifica o formato de árvore git em uso, para um pacote fonte "3.0 (quilt)".

As semânticas são as mesmas que para opção de dgit com nome idêntico.

Se esta opção não for especificada, a predefinição é "quilt=linear" (dependendo da distribuição e configuração).

"--deliberately=..."

As semânticas são as mesmas que para opção de dgit com nome idêntico. As opções não usadas ou desconhecidas deliberadamente são ignoradas.

"split"

Instrui o serviço tag2upload que este envio é para ser feito em modo de vista dividida "split git view":

Quando se converte de git para pacote fonte, e de modo a empurrar e enviar, pode ser necessário fazer alterações -- ambos para o conteúdo da árvore e para o histórico do git. Por exemplo, pode ser necessário aplicar patches quilt, ou fazer o ramo git avançar rápido do histórico anterior na suite visada.

"split" instruí o serviço tag2upload a fazer estas alterações, e a empurrar cometidos git que representam estas alterações para apenas o seu repositório alvo canónico. Isto é, o ramo de suite no repositório alvo canónico pode conter alterações adicionais, mas estas não serão enviadas automaticamente para atrás ao repositório git propriedade do maintainer (ex. salsa.debian.org). O histórico git no repositório alvo canónico é sempre um descendente do formulário fornecido pelo etiquetador; pode ser prontamente obtido usando o dgit.

Sob a implementação atual, este item de metadados é obrigatório, porque o serviço não é capaz de fazer mais nada.

METADADOS NA ÁRVORE¶

As suites alvo, são obtidas a partir de debian/changelog.

CONTEÚDOS DA ÁRVORE¶

A árvore tem de estar no formato de um pacote fonte Debian desempacotado.

Para o formato dum pacote fonte não nativo, os ficheiros do autor têm de corresponder a qualquer cometido de autor especificado, ou ao orig já presente no arquivo -- seja com patch aplicada ou não aplicada, e acordo com o modo quilt.

As incompatibilidades farão o processamento do serviço tag2upload falhar.

SEMÂNTICAS¶

REPRODUZIR¶

O enviar pretende-se que seja um processo idempotente.

Assim, a etiqueta tag2upload é uma instrução para enviar apenas se a versão fornecida é posterior àquela que está na suite visada.

As etiquetas antigas, que especificam versões antigas, serão rejeitadas (apesar de tentativas de repetição poderem gerar alguns mails de erro para o etiquetador).

INVOCAÇÃO E COLOCAÇÃO EM FILA¶

Normalmente, serão feitos acordos para que o serviço tag2upload perceba de novas etiquetas git, em repositórios relevantes; por exemplo, por meio de ganchos de web.

Se este mecanismo falhar, o utilizador que etiqueta pode precisar de provocar manualmente o serviço tag2upload a re-sondar o repositório relevante.

CRÉDITOS¶

tag2upload foi desenhado por Ian Jackson <ijackson@chiark.greenend.org.uk> e Sean Whitton <spwhitton@spwhitton.name>.

VEJA TAMBÉM¶

dgit(1), git-debpush(1).