Package maintenance guide/pt-br

In other languages: English (en) 中文（中国大陆） (zh-cn) 日本語 (ja) português do Brasil (pt-br) [edit]

Esta página fornece algumas instruções básicas para o uso diário do sistema de manutenção de pacotes baseado em git para o Fedora. Destina-se principalmente a mantenedores de pacotes Fedora novos e atuais, mas cobre brevemente o uso anônimo somente leitura do sistema. Não é um guia para o pacote RPM em si. Algum conhecimento pré-existente sobre git pode ser útil, mas não é um pré-requisito (na verdade, o pacote do Fedora pode ser uma introdução relativamente fácil).

Você pode estar procurando ou também estar interessado em:

• Aprendendo a criar pacotes
• Se tornando um mantenedor de pacote
• Enviando atualizações de pacote
• Adicionando um novo pacote ao repositório como um mantenedor existente
• Adicionando um novo brancho de lançamento a um pacote existente
• As diretrizes de empacotamento

Instalando fedpkg e fazendo a configuração inicial

Comece instalando fedpkg com dnf install fedpkg. Esta será sua interface principal para o sistema de empacotamento.

Você também deve ter uma chave ssh configurada no Fedora Accounts System para poder fazer alterações em qualquer pacote (incluindo os seus). O fedpkg espera que a chave ssh correta esteja disponível em seu chaveiro.

Antes de fazer o upload dos fontes com new-sources e upload e compilar pacotes no Koji (com build por exemplo), você tem primeiro que obter suas credenciais Kerberos com kinit. Por exemplo:

 kinit [nome_de_usuário_FAS]@FEDORAPROJECT.ORG

(Mantenha FEDORAPROJECT.ORG em caixa alta)

Defina seu nome de usuário do Fedora Account System em ~/.fedora.upn. Você pode fazer isso por meio de echo "nome_de_usuário_FAS" > ~/.fedora.upn.

Comandos comuns do fedpkg

Esta seção lista os comandos típicos do fedpkg em um fluxo de trabalho normal, com breves descrições. Neste fluxo de trabalho, estaremos operando no branch do Rawhide do pacote.

• Faça o checkout de um pacote:

fedpkg co <nome_pacote_fontes>
cd <nome_pacote_fontes>

Detalhes

Isso obtém uma cópia os fontes do pacote do servidor. É conhecido como sua "cópia de trabalho".

• Atualize sua cópia em local do servidor Fedora:

fedpkg pull

• Obtenha os fontes do pacote:

fedpkg sources

Detalhes

Isso faz um pull de todas as fontes armazenadas no "cache lookaside" (veja mais abaixo). Passos como fedpkg prep e fedpkg srpm farão isso se necessário, mas você pode querer uma cópia imediatamente.

• Faça suas alterações no pacote

Detalhes

Este não é um guia de empacotamento RPM, portanto, presumiremos que você sabe o que está fazendo aqui. Novas fontes e patches vão para o diretório da cópia de trabalho por enquanto.

• Execute o estágio "prep" (extrai fontes, aplica patches etc) dentro do diretório de checkout:

fedpkg prep

Detalhes

Isso é útil para garantir que seus patches sejam aplicados de forma limpa e para inspecionar a árvore de fontes, se necessário.

• Faça uma compilação local do estado atual:

fedpkg local

Detalhes

Este é o tipo mais simples de compilação de teste, mas geralmente é mais limpo e um teste melhor para fazer uma compilação scratch Mock ou Koji (veja abaixo).

• Faça uma compilação com mock do estado atual:

fedpkg mockbuild

Detalhes

Isso aciona uma compilação do Mock, se você tiver o Mock configurado corretamente. Using_Mock_to_test_package_builds pode ajudar nisso.

• Generate a .src.rpm from the current state:

fedpkg srpm

Detalhes

Você pode solicitar uma "scratch build" ao Koji (uma compilação de teste, que não irá para nenhum repositório) do .src.rpm gerado com o comando koji build --scratch (consulte man koji).

• Faça uma compilação scratch usando koji: veja sobre compilações scratch com Koji
• Verifique a alterações que você fez:

fedpkg diff

Detalhes

Isso é útil para garantir que você não tocou em algo por engano, se esqueceu de alterar o lançamento ou se esqueceu de incluir um changelog...

• Execute algumas verificações (rpmlint) em seu pacote:

fedpkg lint

Detalhes

Se você quiser colocar alguns erros rpmlint na lista de permissões e evitar que eles apareçam, você pode criar um arquivo de configuração rpmlint chamado <nome_pacote_fontes>.rpmlintrc e será aplicado.

• Mova para stage quaisquer patches ou novos arquivos fontes para fazer commit:

git add (algum_arquivo)

Detalhes

O git não considera todos os arquivos no diretório de trabalho como parte do repositório git por padrão (útil, para manter outros arquivos relevantes, como a árvore de fontes). Isso diz ao git para começar a considerar esses arquivos como parte do repositório localmente. Quando você faz "commit" e "push" depois, essa mudança é comunicada ao servidor.

• Envie os novos arquivos fontes para o cache lookaside:

fedpkg new-sources

Alerta
Isso substituirá a lista atual de arquivos fontes, e não adicionará a ela. Consulte Detalhes para obter mais detalhes sobre o sistema de cache lookaside.

fedpkg upload

Detalhes

Fontes upstream "intocadas" (como tarballs de lançamento) e outros arquivos fonte maiores são armazenados no sistema de cache lookaside, não comprometidos diretamente com o git. Isso fornece armazenamento e transferência de arquivos mais eficientes. Os arquivos sources e .gitignore no repositório o mantém em sincronia com o cache lookaside. Toda vez que você usar fedpkg new-sources ou fedpkg upload, você deve se lembrar de fazer "commit" das alterações nesses arquivos.

new-sources "começa do zero", substituindo todos os arquivos atualmente no cache lookaside - você normalmente usará este comando para muitos pacotes com apenas um único tarball de fontes, cada vez que você atualizar para uma nova versão upstream. upload apenas adiciona o arquivo fornecido aos que já estão no cache. Lembre-se de não deixar fontes obsoletas por aí.

• Troque para um branch diferente de lançamento:

fedpkg switch-branch <f39, el6, rawhide>

Detalhes

Cada versão do Fedora tem seu próprio branch em cada repositório de pacotes, de forma que diferentes compilações podem ser enviadas para cada versão. Veja abaixo mais detalhes sobre como trabalhar com branches.

• Gere o changelog do git do changelog do pacote:

fedpkg clog

Detalhes

Este comando extrai a entrada do changelog do pacote para o arquivo clog, então você pode usá-lo como o changelog git se quiser. Alguns mantenedores fazem uma distinção entre os dois, outros não.

• Faça commit das alterações:

fedpkg commit (-F clog) (-p) (-c)

Diferença do git
Isso se comporta por padrão como git commit -a - ele organiza arquivos modificados e confirma todos de uma vez, embora não adicione arquivos que o git ainda não esteja rastreando.

Detalhes

Isso cria uma espécie de pacote, um "commit", de suas mudanças no repositório, com uma identidade única e um changelog. Outros mantenedores - e você, mais tarde - podem ver o histórico de mudanças no repositório com o "commit" como o melhor nível de detalhe. É uma boa prática usar muitos commits relativamente pequenos, cada um para um único propósito - não combine um aumento de versão com um monte de correções de espaço em branco e algumas mudanças de scriptlet tudo em um commit, crie commits separados para cada um.

O parâmetro -F clog usará o arquivo clog da etapa anterior como o changelog. -p irá empurrar (veja abaixo) ao mesmo tempo que comete. -c combina os passos clog e commit -F clog em um, se você quiser.

• Faça push das alterações:

fedpkg push

Detalhes

Isso envia todos os novos "commits" em sua cópia de trabalho local para o servidor upstream. Se você ainda está aprendendo o sistema, agora é um bom momento para fedpkg co outra cópia do repositório em outro lugar, compare o que você obteve com sua cópia de trabalho e execute um teste de compilação nela.

• Faça uma compilação "oficial" das alterações nos últimos "pushes":

fedpkg build

• Envia compilações "oficiais" de um branch

fedpkg build

Detalhes

Não há diferença na linha de comando para enviar várias compilações de um fluxo de branch. Mas você precisa criar um arquivo de configuração package.cfg no repositório e definir a opção para as compilações. Por exemplo, o arquivo de configuração é criado em um fluxo de branch 8 do pacote foo, que possui conteúdo,

[koji]
targets = f28 epel7

Este exemplo mostra quando você executa o comando build, o fedpkg é capaz de enviar compilações para lançamentos, f28 e epel7.

Na prática, você pode especificar dois nomes de atalho fedora e epel por conveniência. O fedpkg recupera as versões atuais do Fedora e EPEL automaticamente. Portanto, se você não deseja selecionar um subconjunto de lançamentos, ou simplesmente compilar pacotes para lançamentos ativos sem saber o nome concreto do lançamento, nomes de atalho seriam úteis. Você pode especificar a compilação para rawhide, use o nome master.

• Na eventualidade de você estar trabalhando com uma compilação de imagem em camada de contêiner do Docker.

fedpkg container-build

Indo para produção
Este é o primeiro ponto em que você pode causar confusão real para um usuário real, portanto, use-o com cuidado. Se você estiver seguindo o exemplo e operando no Rawhide, sua compilação entrará no ar para os usuários do Rawhide algumas horas depois de executar este comando.

Usa estado do push
Ao contrário da maioria dos comandos acima, ele opera no estado que você enviou ao git, não no estado local. Se você tiver problemas, certifique-se de enviar e enviar todos os patches e manipular as fontes corretamente.

Detalhes

Isso aciona uma compilação "real" (não do zero) do seu pacote em Koji. Dependendo da versão para a qual você está compilando, ela pode ir diretamente para o estado estável ou pode ter que ser executada através do processo de atualização. Veja o guia de atualização do pacote para mais detalhes sobre isso. O comando irá gerar uma URL onde você pode monitorar o progresso da compilação no Koji.

• Envie uma atualização de pacote para a compilação mais recente (mas consulte Atualizando pacotes interdependentes se estiver fazendo alterações interdependentes em mais de um pacote):

fedpkg update

Detalhes

Novamente, consulte o guia de atualização do pacote para obter mais detalhes sobre este processo. Esta etapa não é realmente aplicável ao Rawhide, mas ilustrada aqui para integridade.

Sessão típica do fedpkg

A typical session may look like this:

fedpkg clone foo
cd foo
fedpkg sources
fedpkg new-sources foo-0.0.2.tar.bz2
gedit foo.spec       # change the required things in the specfile.
                     # rpmdev-bumpspec is useful for simple version updates
fedpkg mockbuild     # check that the changes you made are correct
fedpkg diff
fedpkg lint
fedpkg commit -p -c  # commit and push in one go

Trabalhando com branches

Each Fedora release is represented by a branch in the git repository. You can switch between them like this:

fedpkg switch-branch f39
fedpkg switch-branch f38
fedpkg switch-branch rawhide

The rawhide branch is for Rawhide. You can maintain each branch entirely separately, if you like, laboriously copying changes between them (so long as you always stay within the Updates Policy requirements). However, git provides us with several handy tools for working with branches. Here's an example:

fedpkg clone bzrtools
# Make some changes in the rawhide branch
fedpkg new-sources bzrtools-2.2.tar.gz
gedit bzrtools.spec
fedpkg commit
fedpkg switch-branch f39
git merge rawhide
# for push into repo
fedpkg push

This will 'merge' the changes from the rawhide (Rawhide) branch to the f39 branch. git aficionados may note this is a somewhat unusual workflow, but it is appropriate to the context of package management. Remember, after pushing to and building for a stable release or a Branched release after Bodhi has been enabled, you will have to submit an update before any other Fedora users will see your build.

Note that merges will only be sure to work cleanly so long as the branches have not previously diverged. That is, if you do this:

fedpkg clone bzrtools
# Make some changes in the rawhide branch
fedpkg commit
fedpkg switch-branch f39
# Make some changes in the f39 branch
fedpkg commit
fedpkg switch-branch rawhide
# Make some more changes in the rawhide branch
fedpkg commit
fedpkg switch-branch f39
git merge rawhide

you may encounter a merge conflict.

Remember that git is a collaborative system, and used as such in Fedora package management. It is often the case that you must consider changes made by others in working on a package, and consider how your changes will affect others.

Resolvendo conflitos de mesclagem

This is a large topic and somewhat beyond the scope of this guide, but we can give basic pointers. There are other good references in the git book and at github.

When you git merge and a conflict occurs you can edit the files that have conflicts. Remove the conflict markers in the files and merge the changes manually. Use git diff or fedpkg diff to inspect the changes against the pre-conflict state and verify you are happy with the resolution. Then you can commit the files with fedpkg commit or git commit -a. git will know if you have resolved the conflict by checking that all the conflict markers have been removed.

Usando git mergetool para resolver conflitos

Git provides a graphical diff program to help resolve conflicts. This can be handy for visualizing what changes have occurred and dealing with them as a set.

git config --global merge.tool meld
fedpkg switch-branch f39
git merge rawhide
# Conflicts occurred
git mergetool            # Opens up a meld showing a three way diff of 
                         # the merge, working tree, and the last commit
# Resolved all the conflicts in the GUI
git add CONFLICTEDFILES
git commit

Solicitando dist tags especiais

When a change to a package affects a large number of dependencies (e.g. all perl, python, ruby or ghc packages), requiring them to be rebuilt, it may be better to initially do the builds in a special repository, so that there is less disruption in Rawhide.

If you think you have an update that falls under this case you can request a special dist tag by filing a release engineering ticket. Someone from release engineering will likely want to discuss your needs to make sure this is really an appropriate case (it's OK ask if you aren't sure) and that you get what you need.

Dicas e truques

Usando fedpkg anonimamente

You can use fedpkg like this:

fedpkg clone --anonymous <somepackage>

to check out a package without requiring identification. Obviously, you will not be able to push any changes to this repository, but it is useful for non-packagers who simply want to examine a package, make changes for their own use, and perhaps submit changes to a Fedora developer.

Nomes de branches locais

If you use git commands to branch and checkout directly, you can define whatever local branch names you want. If you use fedpkg switch-branch, it will default to creating the names used in the examples above.

branch e estado atual no promtp de shell

It is often helpful to know what branch you are working on at a glance. You can add this information to your bash prompt with the information here.

Importando um .src.rpm para atualizar

The fedpkg import command usually used to initially populate a git package repository from a .src.rpm that has been through the Package Review Process can also be used to update a normal working copy, if you have an old-school packaging process to which you are particularly attached. Just run fedpkg import file.src.rpm and it will upload new tarballs into lookaside cache, update a working copy of the last version found in git, and commit all changes. fedpkg import --help documents some other parameters it can accept.

Caution!
This approach makes it harder to verify that your changes are safe and do not overwrite changes made to the package by others. For this reason, its use is not recommended.

Fazendo alterações em um branch mais antigo sem quebrar o caminho de atualização

Here is the scenario: you've built your package successfully on the 39 branch, but there is a problem keeping your package from building on last.

Solution: make your changes in the branch and then add a digit to the very right of the release tag. There is no need to change the release in the other branches. This allows upgrades to work smoothly if the user upgrades to a newer release of Fedora.

Name:    foo
Version: 1.0
Release: 1%{?dist}

Name:    foo
Version: 1.0
Release: 1%{?dist}.1

Then tag and build as usual. This approach was initially discussed in this mailing list thread.

Removendo uma compilação de pacote pendente para Rawhide ou Branched

From time to time you may want to remove a package build you submitted to Rawhide or to Branched prior to the Alpha freeze (both cases where the build would usually go out to the main repository without further gating). This could happen in a situation where a bug or issue is found in your package that will be resolved upstream in the next release, or you realize you made a significant mistake in the build that cannot easily be corrected.

Use this carefully!
This should only be done on the same day of the build, before it is included in a compose. If your build was already included in a compose you must not untag it! Check the Release Engineering Dashboard to get the starting time of the last compose.

You can remove the package by using Koji: koji untag-pkg f40 foo-1.1.3-1.fc40

where foo-1.1.3-1.fc40 is replaced with the name of your package build. See koji help or using Koji for more information.

Impressão digital de ssh

The recommended option is to include "VerifyHostKeyDNS yes" in your ~/.ssh/config file. This will result in using DNS to check that the key is correct.

But you can also manually check against the list of keys at https://admin.fedoraproject.org . The strings there are what ends up in your ~/.ssh/known_hosts file. So you can accept the fingerprint when prompted and then check that the correct string for src.fedoraproject.org ended up in your ~/.ssh/known_hosts file.

Problemas para se conectar ao repositório

The fedpkg tool clones repositories using the ssh:// protocol, so this should not be a problem normally (as long as you have your ssh key). If you cloned using the git utility itself, check the .git/config file to ensure the remote repository is being accessed via an ssh:// protocol, and not git://.

Ele compila aqui, porque não compila lá?

Is your package building locally - even with Mock, even as a scratch build! - but not when you run fedpkg build? Before you get too frustrated, remember fedpkg build runs on the package as it exists in the upstream repository, not your local working copy. Make sure you have committed and pushed all changes and source files, and handled the lookaside cache correctly. Other issues that have been reported, are issues because of build/make check parallelization and failures because of test suites that depend on operations finish on precise timing (and a busy build system may not be able to perform operations on time).

Referências

• https://src.fedoraproject.org/
• Infrastructure/Kerberos
• Package_Renaming_Process
• PackageMaintainers/PackagingTricks
• Package_update_HOWTO
• PackageMaintainers/BuildSystemClientSetup#Install_the_Client_Tools_.28Koji.29
• PackageMaintainers/MockTricks#How_do_I_use_Mock.3F
• Using_the_Koji_build_system
• Package_Review_Process
• Fedora_Release_Life_Cycle
• PackageMaintainers/Join
• Infrastructure/VersionControl/dist-git