Provided by: dgit_13.15_all 
NOME
dgit-downstream-dsc - definir o dgit push para uma nova distribuição
INTRODUÇÃO
Este documento destina-se a fluxos abaixo de Debian. Explica como você pode publicar o código fonte dos
seus pacotes ambos como pacotes fonte tradicionais Debian, e como ramos git, usando dgit push. Os seus
utilizadores serão capazes de obter a fonte com dgit clone, ou com ferramentas tradicionais como apt-get
source.
Note que geralmente é desnecessário publicar pacotes fonte tradicionais. Os pacotes fonte de formato
Debian conseguem ser complexos, idiossincráticos e difíceis de trabalhar com eles. Você deve evita-los
de puder. Se você não precisar publicar pacotes fonte, você pode trabalhar num fluxo abaixo de Debian
usando puramente ramos git, (usando o dgit para obter a fonte de Debian em formato git). Você pode
compilar binários diretamente de git, e enviar o código fonte do pacote como um ramo git para um servidor
git normal. Veja dgit-user(7).
Nem todas as opções são cobertas aqui. dgit(1) tem uma lista muito completa de opções de configuração,
apesar de nem sempre com descrições úteis.
NOMES
Você precisa de escolher alguns nomes.
distro nome
O dgit compreende tudo o que interage como uma distribuição. Assim em termos do dgit, você está a
configurar uma distribuição.
Você precisa dum nome para si (isto é, para a sua distribuição). O nome irá aparecer nas etiquetas
git feitas pelas suas ferramentas, e nas definições de configuração. Tem de ser único globalmente
entre todas as pessoas e instituições que usem o dgit,
Você pode escolher o nome de domínio da sua organização, ou parte dele se achar que vai ser muito
único.
O nome da distribuição pode conter alfanuméricos ascii e . + -, apesar de - poder criar confusão e
provavelmente o melhor é evita-lo. Tente evitar letras maiúsculas (e underscore): você vai teclar
este nome muitas vezes.
Por exemplo, se você for a Free Software Foundation Europe (fsfe.org) você poderá chamar a sua
distribuição fsfe ou fsfe.org. No resto deste documento nós vamos só escrever distro para o seu nome
de distribuição.
suite nomes
Em dgit e terminologia de arquivo Debian, uma suite é uma linha de desenvolvimento e/ou um lançamento
Debian. Por exemplo, à data desta escrita, Debian tem suites como sid aka unstable, trixie aka
testing, e bookworm aka stable. Existem também suites auxiliares como a bookworm-security.
Se os seus lançamentos alinharem com lançamentos de Debian, então as suas suites devem conter os
nomes de suites Debian. Não use apenas os nomes de Debian. Isso vai criar confusão. Em vez disso,
anteceda com o nome da sua organização e um hífen. Por exemplo, FSFE poderia ficar com suites como
fsfe-trixie.
Os nomes de suite acabam em referências git e nomes de ramo, e nas linhas de comando do dgit. Os
nomes de suite pode conter alfanuméricos e "-". Outros caracteres podem funcionar mas não são
recomendados.
SERVIÇOS
Você vai precisar de correr dois serviços paralelos:
servidor git
Isto vai manter os ramos git acedidos pelo dgit.
Qualquer pessoa que irá usar dgit push precisa de ser capaz de atualizar refs/dgit/suite (nota, não
refs/heads/dgit/suite) nesse servidor, e para criar etiquetas distro/version e
archive/distro/version. Normalmente isto deve ser feito sobre ssh.
O servidor também pode hospedar outros ramos e etiquetas. Assim este pode ser o seu servidor git
normal, ou uma instância de um sistema de hospedagem git.
Qualquer pessoa que obtenha um dos seus pacotes fonte, ou quem irá correr dgit clone e dgit fetch,
precisa de ter pelo menos acesso de leitura ao servidor git. Idealmente tudo seria publicado via
protocolo https inteligente do git.
O nome do servidor git, e a estrutura de url de git público, devem ser escolhidos de modo que não
precisem ser alterados no futuro. O melhor é dar ao servidor git um nome DNS dele próprio.
O servidor git dgit de Debian tem regras de controlo de acesso especiais, implementadas em dgit-
repos-server e dgit-repos-policy-debian no pacote dgit-infrastructure. Mas na maioria das
instalações isto não é necessário. Se não existir distinção, ou for pequena, entre (i)
desenvolvedores que têm direito a enviar (push) e (ii) administradores do repositório, então é
suficiente fornecer um servidor git com uma conta unix para cada utilizador que irá enviar, talvez
usando comandos restritos de ssh.
Arquivo de formato Debian (repositório)
Isto detém os pacotes fonte. Você irá provavelmente usar o mesmo arquivo para hospedar os seus
binários, e apontar o seu apt a ele.
O dgit usa o termo arquivo para isto.
Existe uma variedade de ferramentas para criar e gerir um arquivo de formato Debian. Neste documento
vamos assumir que você está a usar o reprepro.
Configurar o reprepro não está coberto por este tutorial. Em vez disso, assumimos que você já tem o
reprepro a funcionar.
Você deve também escrever uma configuração apropriada do dput, pois o dgit usa o dput para enviar
pacotes para o arquivo. Isto irá envolver escolher um nome de máquina do dput. Isso será
provavelmente o seu nome de distribuição, distro.
CONFIGURAÇÃO
Quando você tiver tudo que foi dito em cima configurado, está pronto para explicar ao dgit como aceder
aos seus sistemas.
O dgit é configurado via sistema de configuração do git, assim isto é feito com a configuração do git.
Veja git-config(1).
Em baixo, cada título é uma ou mais chaves de configuração do git. negrito é texto literal e itálico são
coisas que variam. Nas descrições dos efeitos das definições de configuração, nós referimos os valores
de configuração "assim".
dgit-distro.distro.git-url, .git-url-suffix
Especifica os URLs git de acesso público para o seu servidor git dgit. Os urls gerados são
"git-url"/pacote"git-url-sufixo"
O url deve ser estável, e acessível publicamente, porque o seu nome é publicado em ficheiros .dsc.
(Note que você fez versões modificadas dos pacotes a partir de Debian, as licenças de cópia usadas
para Software Livre geralmente requerem que você permita aos seus utilizadores, empregados, e outros
fluxos abaixo do seu, que continuem a distribuir o seu código fonte modificado.)
dgit-distro.distro/push.git-host
O nome de domínio da sua interface ssh do servidor git.
dgit-distro.distro/push.git-user-force dgit-distro.distro/push.username
Alguns sistemas de hospedagem git esperam que todos se liguem por ssh como o mesmo utilizador,
geralmente git. Se este for o caso, defina "git-user-force" para esse utilizador.
Se você tiver um acordo de git sobre ssh normal, onde as pessoas usam ssh como elas próprias, deixe
"git-user-force" por definir. Se um utilizador desejar sobrepor o nome de utilizador (por exemplo,
se o seu nome de utilizador local não for o mesmo que no servidor) ele pode definir "username".
dgit-distro.distro/push.git-url
Defina isto para string vazia. Isto vai fazer com que os acessos de envio (push) ao servidor ssh
irão usar "/push.git-host", etc.
dgit-distro.distro/push.git-proto git+ssh://
"dgit-distro."distro/push.git-path
O caminho para os seus repositórios. O dgit push irá tentar enviar para
"git-proto"["git-user-force"|"nome-utilizador"@]"caminho-git"/pacote.git
dgit-distro.distro.git-check, .git-check-suffix
O dgit clone precisa de ser capaz de perceber se ainda existe um repositório git para um pacote
particular.
Se você tiver sempre um repositório git para cada pacote no seu arquivo, talvez porque nunca usou o
dput/dupload, e sempre o dgit push, defina "git-check" para true.
Caso contrário, defina "git-check" para um prefixo de url - idealmente, https. O dgit clone irá
tentar obter "git-check"/pacote"git-check-suffix" e esperar obter ou algum sucesso na obtenção (não
interessa qual) ou um erro de ficheiro não encontrado (código de estado 404 do http). Os outros
resultados são erros fatais.
Se o seu servidor git correr cgit, então você pode definir "git-check" para o mesmo que "git-url", e
"git-check-suffix" para /info/refs.
dgit-distro.distro/push.git-check, /push.git-create
O dgit push também precisa de ser capaz de verificar se o repositório existe.
Você pode definir ambos estes para ssh-cmd, o que irá usar um comando shell ssh para testar a
existência do repositório. Ou deixa-los por definir, e o dgit push irá usar os detalhes de apenas-
leitura. Se os repositórios forem, de alguma forma, criados automaticamente no envio, você pode
definir "git-create" para true.
dgit-distro.distro.upload-host
Que valor de host passar ao dput, para o envio.
Isto é um nome alcunha, não o nome de máquina real. Você precisa de fornecer a todos os que vão
enviar uma configuração dput apropriada. Veja dput.cf(5).
Um bom nome alcunha para a sua máquina de envio é o seu nome de distribuição distro.
dgit-distro.distro.espelho
Defina isto para o url do seu arquivo de pacote fonte. Esta é a mesma string como aparece no 2º
campo de cada entrada do sources.list.
dgit-distro.distro.archive-query, .archive-query-url
Se você tem uma distribuição pequenina, defina "archive-query" para aptget: (com os dois-pontos).
Se a sua distribuição é grande (ex, se conter uma fração substancial de Debian) então isto não vai
ser muito eficiente: com esta definição, o dgit precisa muitas vezes de descarregar e atualizar os
ficheiros Sources.
Para distribuições grandes, é melhor implementar a API ftpmaster do arquivo Debian. Veja
<https://api.ftp-master.debian.org/>, e defina "archive-query" para ftpmasterapi: (com o :) e
"archive-query-url" para o seu URL base da API. O dgit usa estas consultas: suites,
dsc_in_suite/isuite/pacote e file_in_archive/pat (assim não precisa de implementar mais nada).
Em alternativa, se o seu sistema suportar o protocolo rmadison, você pode definir "archive-query"
para madison:[madison-distro]. O dgit irá invocar rmadison -umadison-distro.
dgit-suite.suite.distro distro
Defina isto para cada uma das suas suites. Você terá de atualizar isto quando forem criadas novas
suites. Se você se esquecer, os seus utilizadores podem especificar explicitamente -d distro ao
dgit.
REPOSITÓRIO GIT DE MODELOS
Quando o dgit push é usado para pacote na primeira vez, tem de criar um repositório git no servidor git.
Se "git-create" for definido para ssh-cmd, o dgit irá usar o acesso de shell do utilizador ao servidor
para cp -a _template.git pacote.git. Assim você deve criar _template.git com conteúdo apropriado.
Note que a runa ssh invocada pelo dgit não faz nenhuma tranca. Assim se duas pessoas usarem dgit push no
mesmo pacote ao mesmo tempo, vai haver perdas. Ou nunca façam isso, ou configure dgit-repos-server.
COMANDOS SSH
Quando um utilizador que pode enviar usa o dgit, o dgit usa ssh para aceder ao servidor git.
Para facilitar o uso de comandos restritos do ssh, e para o beneficio de dgit-repos-server, cada comando
ssh do dgit começa com uma runa de comentários analisáveis.
Os comandos ssh usados pelo dgit são estes:
: dgit distro git-check pacote ;...
Testa se o pacote já tem um repositório git no servidor. Deve escrever 0 ou 1 e uma nova linha, e
termina com estado zero em qualquer caso. O resto do comando, após ;, é uma implementação de shell
para este teste. Usado quando "git-check" é definido para ssh-cmd.
: dgit distro git-create pacote ;...
Cria o repositório git para o pacote no servidor. Veja "REPOSITÓRIO GIT DE MODELOS", em cima. O
resto do comando é uma invocação apropriada de cd e cp. Usado quando "git-create" é definido para
ssh-cmd.
git-receive-pack..., git-upload-pack...
O dgit invoca git para aceder ao repositório; o git depois corre estes comandos. Note que o dgit
push irá primeiro fazer uma busca git sobre ssh, assim você tem de fornecer upload-pack assim como
receive-pack.
(Existem também outros comandos ssh que são históricos ou obscuros.)
VEJA TAMBÉM
dgit(1)
Debian Project dgit+tag2upload team dgit-downstream-dsc(7)