dgit-maint-merge(7)

NOME
dgit - tutorial para maintainers de pacote, usando o fluxo de trabalho centrado em redor do git-merge(1)

INTRODUÇÃO
Este documento descreve elementos dum fluxo de trabalho para manter um pacote Debian não-nativo usando o dgit e git-debpush. O fluxo de trabalho faz as seguintes suposições opinadas.

•   Histórias git devem ser as histórias não-lineares produzidas pelo git-merge(1), preservando toda a informação acerca de desenvolvimento divergente que foi mais tarde juntado.

•   Manter fluxos de trabalho convenientes e poderosos tem prioridade sobre a utilidade do pacote fonte Debian cru. O arquivo Debian é pensado como um formato de saída.

    Por exemplo, nós não passamos tempo a curar uma série de patches quilt. No entanto, e casos diretos, a informação de tais séries iriam conter a sua prontidão disponível a partir de dgit-repos.

•   é mais importante ter o histórico git do pacote Debian 's git a ser um descendente do histórico git do autor do que usar exatamente o orig.tar que o autor torna disponível para descarregar.

Este fluxo de trabalho é menos apropriado para alguns pacotes. Quando o delta Debian contém múltiplas peças que interagem, ou quando você não vai poder ir ao autor em breve, pode ser preferível manter o delta como uma série de patches re-baseadas. Para tal fluxo de trabalho veja por exemplo dgit-maint-debrebase(7) e dgit-maint-gbp(7).

A DEBIANIZAÇÃO INICIAL
Esta secção explica como começar a usar este fluxo de trabalho com um novo pacote. Deve ser saltada quando se converte um pacote existente para este fluxo de trabalho.

  Quando etiquetas de autor são lançadas em git
Supondo que o lançamento de autor estável mais recente é 1.2.2, e isto foi etiquetado '1.2.2' pelo autor.

    % git clone -oupstream https://some.upstream/foo.git
    % cd foo
    % git verify-tag 1.2.2
    % git reset --hard 1.2.2
    % git remote add -f origin salsa.debian.org:debian/foo.git
    % git push --follow-tags -u origin master

O comando final também tem o efeito de desanexar o seu ramo mestre do remoto do autor, assim esse git não tenta enviar nada para lá, ou fundir cometidos do autor não lançados.

Agora siga e Debianize o seu pacote. Faça cometidos no ramo mestre, adicionando coisas no directório debian/. Se você precisa de aplicar patches na fonte do autor, faça cometidos que alteram ficheiros fora do directório debian/. É melhor separar os cometidos que mexem em debian/ dos cometidos que mexem na fonte do autor, para que mais tarde possam ser escolhidos pelo autor.

Note que não é preciso manter um ramo 'upstream' separado, a menos que você também esteja envolvido no desenvolvimento do autor. Nós trabalhamos com etiquetas de autor em vez de quaisquer ramos, excepto quando se encaminha patches (veja ENCAMINHAR PATCHES AO AUTOR, em baixo).

Finalmente, você precisa dum tarball original:

    % git deborig

Veja git-deborig(1) se isto falhar.

Este tarball é efémero e facilmente regenerado, assim não o cometemos para lado nenhum (ex. com ferramentas como o pristine-tar(1)).

Verificar lançamentos de tarball do autor

    Pode ser boa ideia comparar os tarballs de lançamento do autor com as etiquetas de lançamento, pelo menos para o primeiro envio do pacote. Se forem diferentes, você pode precisar de adicionar alguns passos adicionais ao seu debian/rules, tais como correr ferramentas automáticas.

    Uma maneira conveniente de efetuar este teste é importar o tarball como descrito na secção seguinte, usando um valor diferente para 'upstream-tag', e depois usar git-diff(1) para comparar o tarball importado com a etiqueta de lançamento. Se forem iguais, você pode usar o tarball do autor em vez de correr git-deborig(1).

Usando cometidos de autor não etiquetados

    Por vezes o autor não etiqueta os seus lançamentos, ou você quer empacotar um instantâneo de git não lançado. Em tais casos você pode criar a sua própria etiqueta de lançamento de autor, no formato upstream/ver, onde ver é a versão de autor que você planeia colocar em debian/changelog. O prefixo upstream/ assegura que a sua etiqueta não vai colidir com nenhumas etiquetas que o autor crie mais tarde.

    Por exemplo, suponha que o lançamento mais recente do autor é 1.2.2 e você quer empacotar o cometido git ab34c21 que foi feito em 2013-12-11. Uma convenção comum é usar a versão de autor número 1.2.2+git20131211.ab34c21 e assim você podia usar

        % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21

    para obter a etiqueta de lançamento, e depois proceder como em cima.

    Pode-se gerar tal etiqueta versionada usando a opção --pretty do git show. exemplo:

        % git tag -s upstream/$(git show --date=format:%Y%m%d --pretty=format:"1.2.2+git%cd.%h" --quiet upstream/main) upstream/main

  Quando o autor lança apenas tarballs
Nós precisamos de um ramo de autor virtual com etiquetas de lançamento virtuais. O bp-import-orig(1) pode gerir isto para nós. Para começar

    % mkdir foo
    % cd foo
    % git init

Agora crie debian/gbp.conf:

    [DEFAULT]
    upstream-branch = upstream
    debian-branch = master
    upstream-tag = upstream/%(version)s

    sign-tags = True
    pristine-tar = False
    pristine-tar-commit = False

    [import-orig]
    merge-mode = merge
    merge = False

gbp-import-orig(1) requer um ramo de autor pré-existente:

    % git add debian/gbp.conf && git commit -m "create gbp.conf"
    % git checkout --orphan upstream
    % git rm -rf .
    % git commit --allow-empty -m "initial, empty branch for upstream source"
    % git checkout -f master

Então podemos importar a versão do autor:

    % gbp import-orig --merge --merge-mode=replace ../foo_1.2.2.orig.tar.xz

O nosso ramo de autor não pode ser empurrado para dgit-repos, mas como nós vamos precisar dele sempre que importamos uma nova versão de autor, temos de o empurrar para algum lado. A escolha mais usada é salsa.debian.org:

    % git remote add -f origin salsa.debian.org:debian/foo.git
    % git push --follow-tags -u origin master upstream

Agora você está pronto para prosseguir como em cima, fazendo cometidos para ambos a fonte do autor e o directório debian/.

CONVERTER UM PACOTE EXISTENTE
Esta secção explica como converter um pacote Debian existente para este fluxo de trabalho. Deve ser saltada quando se está a debianizar um pacote novo.

  Nenhum histórico git existente
    % dgit clone foo
    % cd foo
    % git remote add -f upstream https://some.upstream/foo.git

  Histórico git existente usando outro fluxo de trabalho
Em primeiro lugar, se você ainda não tem o histórico git localmente, clone-o, e obtenha o orig.tar correspondente a partir do arquivo:

    % git clone salsa.debian.org:debian/foo
    % cd foo
    % origtargz

Agora despeje qualquer fila de patch existente:

    % git rm -rf debian/patches
    % git commit -m "drop existing quilt patch queue"

Depois torne as novas etiquetas de autor disponíveis:

    % git remote add -f upstream https://some.upstream/foo.git

Agora você simplesmente precisa assegurar que o seu CABEÇALHO git é compatível com o dgit, isto é, é exatamente o que obteria se corresse dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S e depois desempacotasse o pacote fonte resultante.

Para conseguir isto, você pode precisar de apagar debian/source/local-options. Uma maneira de ter o dgit a verificar o seu progresso é correr dgit build-source.

O primeiro dgit push vai requerer --trust-changelog. Se este é o primeiro dgit push do pacote, considere passar --deliberately-not-fast-forward em vez de --trust-changelog. Isto evita introduzir um novo cometer de origem no seu histórico git. (Este cometer de origem iria representar o envio não-dgit mais recente do pacote, mas isto já deve estar representado no seu histórico git.)

PACOTE FONTE E CONFIGURAÇÃO DO GIT

  configuração do dgit
Nós temos de dizer ao dgit para não tentar manter uma fila linear de patches para a fonte do autor:

    git config dgit.default.quilt-mode single

Este comando deve ser executado em cada clone git deste pacote, incluindo os seus co-maintainers. Não o defina mais globalmente, porque não é uma boa predefinição para trabalhar em pacotes fonte Debian em geral.

  debian/source/options
Nós definimos uma opção de pacote fonte para ajudar o dpkg a lidar com as alterações à fonte do autor:

    auto-commit

Nós não precisamos de criar este ficheiro se estiver a usar a versão 1.0 do formato de pacote fonte.

COMPILAR E ENVIAR
Você pode usar o dpkg-buildpackage(1) para compilações de teste. Quando estiver pronto para compilar logo antes dum envio, use dgit sbuild, dgit pbuilder ou dgit cowbuilder, como detalhado em dgit(1). Os envios rotineiros de apenas-fonte podem ser feitos apenas escrevendo

    % git debpush

Na primeira vez passe --quilt=single. Isto é especialmente importante se você converteu o pacote a partir de outro fluxo de trabalho. Veja git-debpush(1).

Se você precisar de enviar para NOVO, você vai precisar de usar dgit push-built. Lembre-se de passar --new se o pacote for novo na suite alvo, e de fazer git push para salsa.debian.org depois disso.

Como outra alternativa para dgit build e amigos, você pode usar uma ferramenta tipo gitpkg(1). Isto funciona porque como o dgit, o gitpkg(1) força que o CABEÇALHO tenha exatamente o conteúdo do pacote fonte. O gitpkg(1) é altamente configurável, e um utilizador do dgit reportou que o usa para produzir e testar múltiplos pacotes fonte, de ramos diferentes correspondentes a cada uma das suites atuais Debian.

NOVOS LANÇAMENTOS DO AUTOR

  Obtendo o lançamento
Quando etiquetas de autor são lançadas em git

    % git fetch --tags upstream

Se você quer empacotar um cometido de autor não etiquetado (porque o autor não etiqueta os lançamentos ou porque você quer empacotar um instantâneo de desenvolvimento do autor), veja "Usando cometidos de autor não etiquetados" em cima.

Quando o autor lança apenas tarballs

Você vai precisar do debian/gbp.conf de "Quando o autor lança apenas tarballs", em cima. Você vai também precisar do seu ramo de autor. Em cima, nós envia-mos isto para salsa.debian.org. Você vai precisar de clonar ou ir buscar de lá, em vez de confiar apenas em dgit clone/dgit fetch.

Então, ou

    % gbp import-orig ../foo_1.2.3.orig.tar.xz

ou se você tiver um ficheiro watch a funcionar

    % gbp import-orig --uscan

No seguinte, substitua 1.2.3 por upstream/1.2.3.

  Revisar e fundir o lançamento
É boa ideia pre-visualizar a fusão do novo lançamento de autor. Primeiro, verifique por quaisquer ficheiros novos ou apagados que podem precisar ser declarados no seu ficheiro copyright:

    % git diff --name-status --diff-filter=ADR master..1.2.3 -- . ':!debian'

Você pode depois pré-visualizar o diff da fusão completa:

    % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER

Assim que estiver satisfeito com o que vai ser fundido, atualize o seu pacote:

    % git merge 1.2.3
    % dch -v1.2.3-1 New upstream release.
    % git add debian/changelog && git commit -m changelog

Se você obteve um tarball a partir do autor, está pronto para tentar uma compilação. Se você fundiu uma etiqueta git a partir do autor, você vai precisar de primeiro gerar um tarball:

    % git deborig

MANUSEAR MATERIAL DFSG-NÃO-LIVRE

  Quando etiquetas de autor são lançadas em git
Nós criamos uma etiqueta DFSG-limpo para fundir no mestre:

    % git checkout -b pre-dfsg 1.2.3
    % git rm evil.bin
    % git commit -m "upstream version 1.2.3 DFSG-cleaned"
    % git tag -s 1.2.3+dfsg
    % git checkout master
    % git branch -D pre-dfsg

Antes de fundir a nova etiqueta 1.2.3+dfsg para mestre, você deve primeiro determinar se poderá ser perigoso legalmente para o material não-livre ficar acessível publicamente no histórico git em dgit-repos.

Se poderá ser perigoso, existe um grande problema; neste caso por favor consulte os seus administradores do arquivo (para Debian isto é o administrador do dgit dgit-owner@debian.org e os mestres de ftp ftpmaster@ftp-master.debian.org).

  Quando o autor lança apenas tarballs
A maneira mais fácil de lidar com isto é adicionar um campo Files-Excluded a debian/copyright, e uma definição uversionmangle em debian/watch. Veja uscan(1). Em alternativa, veja a opção --filter detalhada em gbp-import-orig(1).

ENCAMINHAR PATCHES AO AUTOR
Os passos básicos são:

1.  Criar um novo ramo baseado no ramo mestre do autor.

2.  Fazer cometidos git-cherry-pick(1) do seu ramo mestre para o seu novo ramo.

3.  Empurre o ramo para algum lado e peça ao autor para o fundir, ou use git-format-patch(1) ou git-request-pull(1).

Por exemplo (e é só mesmo um exemplo):

    % # bifurca foo.git em GitHub
    % git remote add -f fork git@github.com:spwhitton/foo.git
    % git checkout -b fix-error upstream/master
    % git config branch.fix-error.pushRemote fork
    % git cherry-pick master^2
    % git push
    % # submete pedido de puxar no GitHub

Note que quando você funde um lançamento de autor que contém as suas patches encaminhadas, o git e o dgit irão de modo transparente lidar como "largar" as patches que foram encaminhadas, e "reter" as que não foram.

INCORPORAR NMUS
    % dgit pull

Em alternativa, você pode aplicar o diff NMU no seu repositório. O próximo empurrar irá então requerer --trust-changelog.

VEJA TAMBÉM
dgit(1), dgit(7), gitrevisions(7)

AUTOR
Este tutorial foi escrito e é mantido por Sean Whitton <spwhitton@spwhitton.name>. Contém contributos de outros contribuidores do dgit também - veja o ficheiro copyright do dgit.