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"=COMETIDO

Nomeia um cometido que contem metadados de pristine-tar

O cometido tem de conter exatamente um ficheiro .id e um .delta para o lançamento de autor atual, e os seus nomes têm de corresponder ao nome do tarball original, com ".id" e ".delta" acrescentados, respetivamente. Eles têm de ser ficheiros normais.

A etiqueta também tem de conter um item "upstream", e a árvore nomeada no ficheiro .id tem de ser identica à do cometido "upstream".

O cometido pristine-tar pode conter um ficheiro de assinatura. O nome do ficheiro de assinatura tem de corresponder ao nome do tarball de origem, com ".asc" acrescentado. O ficheiro de assinatura irá depois ser publicado juntamente com o tarball de origem. O ficheiro de assinatura é tratado como dados puros pelo serviço (assim não irá ser verificado nem mesmo para verificação de formato).

Se um tarball original precisar ser (re)gerado, o serviço irá usar pristine-tar, usando precisamente os metadados nos ficheiros mencionados em cima. O conteúdo do tarball resultante tem de ser idêntico à árvore git nomeada, excepto que também pode conter directórios vazios. Especificamente, nesta comparação, marcas temporais, propriedades, permissões 0777 normais para além de executáveis, e ordenação, são descartadas; objectos para além de ficheiros simples com directórios de permissões normais, e links simbólicos, são proibidos. (Assim por exemplo, ficheiros set-id, ACLs de POSIX, e atributos and, são proibidos.)

O cometido pristine-tar nomeado tem de ser alcançável a partir do ramo "pristine-tar" no repositório.

"--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).