Capítulo 11. Empacotar com git

# Capítulo 11. Empacotar com git

Até ao “Capítulo 10, Empacotamento avançado”, nós concentrava-nos em operações de empacotamento sem usar Git ou qualquer outro VCS. Estas operações de empacotamento tradicionais eram baseadas no tarball lançado pelo autor como mencionado em “Secção 10.1, “Perspetiva histórica””.

Atualmente, o comando git(1) é a plataforma de-facto par a ferramenta VCS e é a parte essencial para ambos desenvolvimento do autor e atividades de empacotamento Debian. (Veja Debian wiki “Empacotamento git Debian formatos de ramo de maintainer e fluxos de trabalho” para fluxos de trabalho VCS existentes.)

| Nota
Como o pacote fonte Debian não-nativo usa “diff -u” como sua tecnologia backend para a modificação do maintainer, não pode representar modificações que envolvam links simbólicos, permissões de ficheiros, nem dados binários (Março 2022 discussão em debian-devel@l.d.o). Por favor evite fazer tais modificações de maintainer mesmo sabendo que estas podem ser gravadas no repositório Git.

Como os fluxos de trabalho VCS são um tópico complicado e existem muitos estilos práticos, aqui vou apenas tocar nalguns pontos chave com informação mínima.

Salsa é o serviço de repositório Git remoto com as ferramentas associadas. Oferece a plataforma de colaboração para atividades de empacotamento Debian usando uma instância de aplicação GitLab. Veja:

- “Secção 11.1, “Repositório Salsa””
- “Secção 11.2, “Configuração da conta Salsa””
- “Secção 11.3, “Serviço CI de Salsa””

Existem 2 estilos nomes de ramo para o repositório Git usado para o empacotamento. Veja “Secção 11.4, “Nomes de ramos:””.

Existem 2 estilos de utilização principais para o repositório Git para o empacotamento. Veja:

- “Secção 11.5, “Repositório Git de patch não-aplicada””
- “Secção 11.13, “Repositório Git de patch aplicada””

Existem 2 ferramentas notáveis de empacotamento Debian para o repositório Git para o empacotamento.

- gbp(1) e os seus sub-comandos:

  - This is a tool designed to work mainly with “Secção 11.5, “Repositório Git de patch não-aplicada””.
  - Veja “Secção 11.9, “Note sobre gbp””.

- dgit(1) e os seus sub-comandos:

  - This is a tool designed to work mainly with “Secção 11.13, “Repositório Git de patch aplicada””.
  - Isto contém uma ferramenta para enviar pacotes Debian usando o servidor dgit.
  - Veja “Secção 11.14, “Nota sobre dgit””.

## 11.1. Repositório Salsa

É altamente desejável hospedar o pacote de código fonte Debian em Salsa. Mais de 90% de todos os pacotes de código fonte Debian estão hospedados Salsa. [21]

O repositório VCS exacto que hospeda um pacote de código fonte Debian pode ser identificado por um campo de metadados `Vcs-*` que pode ser visualizado com o comando `apt-cache showsrc <nome-pacote>`.

## 11.2. Configuração da conta Salsa

After signing up for an account on Salsa, make sure that the following pages have the same e-mail address and openPGP keys you have configured to be used with Debian, as well as your SSH key:

- https://salsa.debian.org/-/profile/emails
- https://salsa.debian.org/-/user_settings/gpg_keys
- https://salsa.debian.org/-/user_settings/ssh_keys

## 11.3. Serviço CI de Salsa

Salsa corre o serviço Salsa CI como uma instância de GitLab CI para “Secção 10.4, “Integração contínua””.

Para cada instância de “git push”, testa quais testes de mímica podem correr no pacote Debian oficial ao definir o ficheiro de configuração do Salsa CI “Secção 6.13, “Ficheiro debian/salsa-ci.yml”” como:

    ---
    include:
      - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/recipes/debian.yml

    # Customizations here

## 11.4. Nomes de ramos:

O repositório Git para o empacotamento Debian deve ter pelo menos 2 ramos:

- debian-branch para manter a cabeça de empacotamento Debian actual.

  - estilo antigo: master (ou debian, main, …​)
  - DEP-14 estilo: debian/latest

- upstream-branch para manter os lançamentos do autor no formato importado.

  - estilo antigo: upstream
  - DEP-14 estilo: upstream/latest

Neste tutorial, são usados nomes de ramo no estilo antigo nos exemplos para simplicidade.

| Nota
Este upstream-branch pode precisar de ser criado usando tarball lançado pelo autor independente repositório Git do autor pois tende a conter ficheiros gerados automaticamente.

O conteúdo do repositório Git do autor pode co-existir no repositório Git local para o empacotamento Debian ao adicionar uma cópia dele. Ex.:

    [debhello] $ git remote add upstreamvcs <url-upstream-git-repo>
    [debhello] $ git fetch upstreamvcs master:upstream-master

Isto permite selecção fácil a partir do repositório Git do autor para correção de bugs.

## 11.5. Repositório Git de patch não-aplicada

O repositório Git de patch não-aplicada pode ser resumido a:

- Esta parece ser a prática tradicional até 2024.

- A árvore fonte corresponde ao conteúdo extraído por “dpkg-source -x --skip-patches” do pacote fonte Debian.

  - A fonte do autor é gravada no repositório Git sem alterações.
  - Os conteúdos modificados pelo maintainer estão confinados dentro do directório debian/*.
  - Modificações do maintainer à fonte do autor são gravadas em ficheiros debian/patches/* para o formato de fonte Debian “3.0 (quilt)”.

- Este estilo de repositório é útil para todas as variantes dos fluxos de trabalho tradicionais e fluxo de trabalho baseado no gbp:

  - “Secção 5.7, “Passo 3: Modificação dos ficheiros modelo”” (nenhum patch)

  - “Secção 5.10, “Patch por abordagem “diff -u”””

    - Os ficheiros debian/patches/* também podem ser gerados usando “git format-patch”, “git diff”, ou “gitk” a partir de commits git no meio do ramo de modificação do maintainer ou a partir de commits do autor ainda não lançados.
  - “Secção 5.11, “Patch por abordagem dquilt”” incluindo o último passo “dquilt pop -a”
  - “Secção 11.6, “Patch por abordagem “gbp-pq”””

- Use scripts de ajuda como o dquilt(1) e gbp-pq(1) para gerir dados nos ficheiros debian/patches/*.

  - Adicione a linha .pc ao ficheiro ~/.gitignore se for usado o dquilt.
- Use “dpkg-source -b” para compilar o pacote fonte Debian.
- Use dput(1) para enviar o pacote fonte Debian.

## 11.6. Patch por abordagem “gbp-pq”

Para “Secção 11.5, “Repositório Git de patch não-aplicada””, você pode gerar ficheiros debian/patches/* usando o comando gbp-pq(1) a partir de commits git feitos para o ramo patch-queue.

Ao contrário do dquilt que oferece funcionalidade semelhante como visto “Secção 5.11, “Patch por abordagem dquilt”” e “Secção 9.5, “Gerir a lista de patch com dquilt””, o gbp-pq não usa ficheiros .pc/* para seguir o estado da patch, mas em vez disso o gbp-pq utiliza ramos temporários no git.

## 11.7. Gerir a lista de patch com gbp-pq

Você pode adicionar, retirar, e refrescar ficheiros debian/patches/* com o gbp-pq para gerir a lista das patch.

Se o pacote for gerido em “Secção 11.5, “Repositório Git de patch não-aplicada”” usando o pacote git-buildpackage, você pode revisar a fonte do autor para corrigir bug como maintainer e lançar uma nova revisão Debian usando gbp pq.

- Adiciona uma nova patch que grava a modificação à fonte do autor no ficheiro buggy_file como:

      [debhello] $ git checkout master
      [debhello] $ gbp pq import
      gbp:info: ... imported on 'patch-queue/master
      [debhello] $ vim buggy_file
        ...
      [debhello] $ git add buggy_file
      [debhello] $ git commit
      [debhello] $ gbp pq export
      gbp:info: On 'patch-queue/master', switching to 'master'
      gbp:info: Generating patches from git (master..patch-queue/master)
      [debhello] $ git add debian/patches/*
      [debhello] $ dch -i
      [debhello] $ git commit -a -m "Closes: #<bug_number>"
      [debhello] $ git tag debian/<version>-<rev>

- Drop (== desactiva) um caminho existente

  - Comenta linha pertinente em debian/patches/series
  - Apagar o próprio caminho (opcional)

- Refresca ficheiros debian/patches/* para fazer o “dpkg-source -b” funcionar como esperado após atualizar um pacote Debian para o novo lançamento do autor.

      [debhello] $ git checkout master
      [debhello] $ gbp pq --force import # ensure patch-queue/master branch
      gbp:info: ... imported on 'patch-queue/master
      [debhello] $ git checkout master
      [debhello] $ gbp import-orig --pristine-tar --uscan
        ...
      gbp:info: Successfully imported version ?.?.? of ../packagename_?.?.?.orig.tar.xz
      [debhello] $ gbp pq rebase
       ... resolve conflicts and commit to patch-queue/master branch
      [debhello] $ gbp pq export
      gbp:info: On 'patch-queue/master', switching to 'master'
      gbp:info: Generating patches from git (master..patch-queue/master)
      [debhello] $ git add debian/patches
      [debhello] $ git commit -m "Update patches"
      [debhello] $ dch -v <newversion>-1
      [debhello] $ git commit -a -m "release <newversion>-1"
      [debhello] $ git tag debian/<newversion>-1

## 11.8. gbp import-dscs --debsnap

Para pacotes fonte Debian chamados “<pacote-fonte>” guardados no arquivo snapshot.debian.org, pode ser gerado um repositório git inicial gerido em “Secção 11.5, “Repositório Git de patch não-aplicada”” com todo o histórico de versão Debian como se segue.

    [debhello] $ gbp import-dscs --debsnap --pristine-tar <source-package>

## 11.9. Note sobre gbp

O comando gbp é fornecido pelo pacote git-buildpackage.

- Este comando é desenhado para gerir os conteúdos de “Secção 11.5, “Repositório Git de patch não-aplicada”” de modo eficiente.

- Use “gbp import-orig” para importar o novo tar de autor para o repositório git.

  - A opção “--pristine-tar” para o comando “git import-orig” permite armazenar o tarball do autor no mesmo repositório git.
  - A opção “--uscan” como último argumento do comando “gbp import-orig” permite descarregar e cometer o novo tarball do autor para o repositório git.
- Use “gbp import-dsc” para importar o pacote fonte Debian anterior para o repositório git.
- Use “gbp dch” para gerar o changelog Debian a partir das mensagens cometidas ao git.

- Use “gbp buildpackage” para compilar o pacote binário Debian a partir do repositório git.

  - O pacote sbuild pode ser usado como seu backend de compilação chroot limpo seja por configuração ou adicionando “--git-builder='sbuild -A -s --source-only-changes -v -d unstable'”
- Use “gbp pull” para actualizar os ramos debian, upstream e pristine-tar em segurança a partir do repositório remoto.
- Use “gbp pq” para gerir patches de quilt sem usar o comando dquilt.
- Use “gbp clone URL_REPOSITÓRIO” para clonar e configurar ramos de acompanhamento para debian, upstream e pristine-tar.

A gestão de histórico do pacote com o pacote git-buildpackage está a tornar-se na prática standard para muitos maintainers Debian. Veja mais em:

- “compilar Pacotes Debian com git-buildpackage”
- “4 tips to maintain a “3.0 (quilt)” Debian source package in a VCS”
- A documentação da prática de empacotamento do systemd em “Compilar a partir da fonte”.
- O fluxo de trabalho mencionado em dgit-maint-gbp(7) o qual permite usar este gbp com dgit

## 11.10. The Git repository browser

The gitk command in the gitk package displays changes in a repository or a selected set of commits. This includes visualizing the commit graph, showing information related to each commit, and the files in the trees of each revision.

This gitk command also provides very intuitive UI to many cumbersome operations of the “git” command such as “git checkout …​”, “git reset* …​”, “git diff …​”, etc..

## 11.11. Git commit history organization

When your local Git commit history becomes intertwined, you need to organize it before pushing it out to the public.

The most simple organization process is to squash all changes to a single commit using “git rebase -i” interactively.

But this may create a huge commit with files such as auto-generated files not intended to be committed. You can drop such files in the commit using “git rm some_file” and “git commit --amend”. This may be quite cumbersome.

This cumbersome drop process can be eased by using the “git-ime” command in the imediff package. It automatically splits a single commit with many files into multiple commits involving only a single file changes. Now you can drop such files using “git rebase -i” interactively.

| Dica
The “git-ime” operating on a single file change commit splits it into multiple commits of line changes using imediff interactively. Invoking this with the --auto option will automate this split commit operation. See git-ime(1) and imediff(1).

## 11.12. Empacotamento Debian Quasi-native

O esquema de empacotamento quase-nativo empacota uma fonte sem o real tarball de autor usando o formato de pacote não-nativo.

| Dica
Algumas pessoas promovem este esquema de empacotamento quase-nativo mesmo para programas escritos apenas para Debian pois ajuda a facilitar a comunicação com as distribuições baseadas como a Ubuntu para correções de bugs e etc.

Este esquema de empacotamento quase-nativo envolve 2 passos de preparação:

- Organiza a sua árvore fonte quase como o pacote Debian nativo (veja “Secção 6.4, “Pacote Debian nativo””) com ficheiros debian/* com algumas excepções:

  - Faz debian/source/format conter “3.0 (quilt)” em vez de “3.0 (native)” .
  - Faz debian/changelog conter versão-revisão em vez de versão .

- Gera o tarball de autor em falta de preferência sem ficheiros debian/*.

  - Para o formato fonte Debian “3.0 (quilt)”, a remoção de ficheiros sob o directório debian/ é uma acção opcional.

O resto é o mesmo como o fluxo de trabalho de empacotamento não-nativo como escrito em “Secção 6.1, “Fluxo de trabalho de empacotamento””.

Although this can be done in many ways, you can use the Git repository and “git deborig” as:

    [~] $ cd /path/to/debhello
    [debhello] $ dch -r
      ... set its <version>-<revision>, e.g., 1.0-1
    [debhello] $ git tag -s debian/1.0-1
    [debhello] $ git rm -rf debian
    [debhello] $ git tag -s upstream/1.0
    [debhello] $ git commit -m upstream/1.0
    [debhello] $ git reset --hard HEAD^
    [debhello] $ git deborig
    [debhello] $ sbuild

## 11.13. Repositório Git de patch aplicada

| Nota
The focus of this introductory tutorial “Guide for Debian Maintainers” isn’t the patch applied Git repository which is rather a new trend initiated by the proponent of the dgit command. So minimal explanation is given here.

O repositório Git de patch aplicada pode ser resumido a:

- A árvore fonte corresponde aos conteúdos extraídos pelo “dpkg-source -x” do pacote fonte Debian.

  - A árvore fonte é compilável e o mesmo que os maintainers NMU veem.
  - A fonte é guardada no repositório Git com as alterações de maintainer incluindo o directório debian/.
  - Modificações do maintainer ao código do autor são também gravados em ficheiros debian/patches/* para o formato fonte Debian “3.0 (quilt)”.

## 11.14. Nota sobre dgit

O comando dgit é fornecido pelo pacote dgit.

- This command enables to access the Debian package repository as if it were a git remote repository.

- This command offers tools to manage Debian packaging activities mainly using “Secção 11.13, “Repositório Git de patch aplicada””.

  - No more convoluted operations to manage patch files in the debian/patches directory.
- Use “dgit build-source” or “dgit sbuild” to build the Debian source-only or source+binary package.
- Use “dgit push-source” or “dgit push-build” for uploading the Debian source-only or source+binary package via the dgit server.
- Use git-deborig(1) to produce Debian package.orig.tar.xz from the upstream version in debian/changelog.

| Dica
The dgit server is browsable at https://browse.dgit.debian.org/ site.

| Nota
In order to keep the working tree dgit-compatible, delete debian/source/local-options and debian/source/local-patch-header if they exist.

Hints for workflow styles:

- Fluxo de trabalho do dgit-maint-merge(7).

  - Use this for the Debian non-native package without granular topic patches recorded in the Debian source package.

    - Suficiente bom para pacotes apenas com modificações triviais para o autor.
    - Only choice for packages with intertwined modification histories to the upstream.

  - Add auto-commit and single-debian-patch lines in the debian/source/options file

    - No granular topic patches recorded inside of the Debian source package.
  - Use “git checkout upstream; git pull” para puxar o novo commit do autor e use “git checkout master ; git merge <nova-versão-tag>” para o fundir com o ramo master.
  - Veja “Secção 5.12, “Patch por abordagem “dpkg-source --auto-commit””” para exemplo.

- Fluxo de trabalho do dgit-maint-debrebase(7).

  - Use this for the Debian non-native package with granular topic patches recorded in the Debian source package.
  - Use the git-debrebase(1) command to maintain series of Debian changes to upstream source.

- dgit-maint-native(7) workflow,

  - Use this for the Debian native package in the Debian Git repository. (No maintainer changes)

- dgit-maint-gbp(7) workflow

  - Use this for the Debian non-native package using source format “3.0 (quilt)” with its Debian Git repository which had been using gbp-buildpackage(1) with “Secção 11.5, “Repositório Git de patch não-aplicada””.

This author likes this new dgit command and just started to use it with dgit-maint-merge(7) and dgit-maint-native(7) workflows. Thus, topics around dgit are beyond this tutorial document to cover in depth. Please start reading the latest relevant manpages and upstream resources:

- “dgit: usar o arquivo Debian como um git remoto (2015)”
- “tag2upload (2023)”

[21] O uso de git.debian.org ou alioth.debian.org está agora descontinuado.

Capítulo 10. Empacotamento avançado |  | Capítulo 12. Dicas