5. Os desafios dos mantenedores de ports

Esta seção lhe dará uma idéia de porque os ports precisam ser mantidos e irá apresentar as responsabilidades de um mantenedor de ports.

5.1. Porque os ports precisam de manutenção

Criar um port é uma tarefa que demanda esforço uma única vez. Garantir que um port está atualizado e que continua a compilar e a executar é um esforço de manutenção permanente. Os mantenedores (maintainers), são pessoas as quais dedicam uma parte do seu tempo para a realização destes objetivos.

A principal razão pela qual o sistema de ports precisa de manutenção é trazer os melhores e mais recentes softwares de terceiros para a comunidade FreeBSD. Um desafio adicional é manter os ports individuais trabalhando com o framework da Coleção de Ports a medida que ele evolui.

Como mantenedor, você vai precisar gerenciar os seguintes desafios:

  • Novas versões de software e atualizações. Novas versões e atualizações de softwares que já pertencem ao ports tornam-se disponíveis o tempo todo, e estes têm de ser incorporados a Coleção de Ports a fim de atualizar os softwares disponibilizados por ela.

  • Alterações em dependências. Se forem feitas mudanças significativas nas dependências de seu port, ele pode precisar ser atualizado para que continue a funcionar corretamente.

  • Alterações que afetam ports que dependem do seu. Se outros ports dependem de um port que você mantém, alterações em seu port podem demandar coordenação com outros mantenedores.

  • Interação com outros usuários, mantenedores e desenvolvedores. Parte do trabalho de um mantenedor é atuar no suporte. Não esperamos que você ofereça suporte generalizado (mas será bem vindo se você optar por isto). O que você deve oferecer é um ponto de coordenação para questões sobre os seus ports que sejam especificos ao FreeBSD.

  • Caça aos bugs. Um port pode ser afetado por erros que são específicos ao FreeBSD. Você vai precisar investigar, encontrar e corrigir estes erros quando eles forem reportados. Testar exaustivamente um port para identificar problemas antes que eles cheguem na Coleção de Ports é ainda melhor.

  • Alterações na política e na infra-estrutura de portsOcasionalmente, os sistemas que são utilizados para compilar os ports e os pacotes são atualizados ou uma nova recomendação que afeta esta infra-estrutura é feita. Você deve estar ciente destas alterações para o caso dos seus ports serem afetados e precisarem de atualização.

  • Alterações no sistema base. O FreeBSD está em constante desenvolvimento. Alterações ao software, as bibliotecas, ao kernel ou mesmo alterações na política podem alterar os requisitos de um port.

5.2. Responsabilidades de um Mantenedor

5.2.1. Mantenha seus ports atualizados

Esta seção descreve o processo que você deve seguir para manter seus ports atualizados.

Esta é uma visão geral. Maiores informações sobre o processo de atualização de um port estão disponíveis no Porter's Handbook.

  1. Fique atentendo para as atualizações

    Monitore o desenvolvedor para tomar conhecimento sobre a liberação de novas versões, atualizações, e correções de segurança para o software do seu port. Listas de discussão destinadas a avisos de lançamentos ou páginas web de notícias são úteis para fazer isso. Algumas vezes os usuários irão entrar em contato com você e perguntar quando o seu port será atualizado. Se você está ocupado com outras coisas ou se por qualquer outra razão não pode fazer a atualização naquele momento, pergunte se eles irão ajudá-lo enviando um PR com a atualização.

    Você também pode receber um email automático do sistema de verificação de ports do FreeBSD informando que uma nova versão do seu port's distfile está disponível. Maiores informações sobre este sistema (incluindo a de como parar emails futuros) serão fornecidas na mensagem.

  2. Incorpore as alterações

    Quando elas se tornarem disponíveis, incorpore as mudanças ao seu port. Você precisa ser capaz de gerar um patch entre o seu port original e o seu port atualizado.

  3. Revisão e teste

    Examine cuidadosamente e teste as suas alterações:

    • Compile, instale e teste o seu port no maior número possível de plataformas e arquiteturas. É comum que um port funcione em um branch ou plataforma e falhe em outra.

    • Certifique-se de que as dependências do seu port estão completas. A melhor forma de fazer isto é instalar a sua própria ports tinderbox. Consulte a seção sobre recursos para maiores informações.

    • Verifique se a lista de empacotamento está atualizada. Isto envolve a adição de novos arquivos e diretórios e a remoção de entradas não utilizadas.

    • Verifique o seu port utilizando o portlint(1) como um guia. Consulte a seção sobre recursos para informações importantes sobre o uso do portlint.

    • Avalie se as alterações no seu port podem levar a quebra de outros ports. Se este for o caso, coordene as alterações com os mantenedores destes ports. Isto é especialmente importante se a sua atualização alterar a versão de uma biblioteca compartilhada; neste caso, no mínimo, os ports que forem dependentes do seu vão precisar atualizar seu PORTREVISION de modo que eles sejam automaticamente atualizados pelas ferramentas de automação tais como o portmaster ou o portupgrade(1).

  4. Envie as alterações

    Envie sua atualização através da submissão de um PR contendo uma explicação sobre as mudanças e um patch com as diferenças entre o port original e a versão atualizada. Por favor, consulte o artigo Escrevendo Relatórios de Problema para o FreeBSD para maiores informações sobre como escrever um bom PR.

    Nota:

    Por favor, não envie um arquivo shar(1) com o port inteiro. Em vez disso, utilize diff(1) -ruN. Desta forma, os committers podem ver com muito mais facilidade e precisão quais são as mudanças que estão sendo feitas. A seção Atualizações do Porter's Handbook tem maiores informações.

  5. Aguarde

    Em algum momento um committer vai cuidar do seu PR. Isto pode demorar alguns minutos, ou pode levar semanas — desta forma, por favor, seja paciente.

  6. Dê feedbacks

    Se um committer encontrar um problema nas suas alterações, ele provavelmente irá encaminhá-lo de volta para você. Uma resposta rápida irá ajudá-lo a ter o seu PR resolvido mais rapidamente, e será melhor para manter o fluxo de conversação quando se está tentando resolver qualquer problema.

  7. E finalmente...

    As suas alterações serão aceitas e o seu port estará atualizado. O PR será fechado pelo committer. E é isso!

5.2.2. Assegure que os seus ports continuem compilando corretamente.

Esta seção é sobre descobrir e corrigir problemas que impeçam os seus ports de compilar corretamente.

O funcionamendo da Coleção de Ports é garantido pelo FreeBSD apenas no ramo -STABLE do sistema. Você deve estar executando o 8-STABLE ou o 9-STABLE, preferencialmente o último. Em teoria, você deve ser capaz de usá-lo com a última release de cada ramo estável (uma vez que as ABIs não deveriam mudar) mas se você puder executar o ramo -STABLE, isto será ainda melhor.

Uma vez que a maioria das instalações do FreeBSD rodam em maquinas PC compatíveis (como é denominada a arquitetura i386), nós esperamos que você mantenha os seus ports funcionando nesta arquitetura. Nós preferimos que os ports também funcionem de forma nativa na arquitetura amd64. É totalmente justo que você peça ajuda se você não possuir uma destas máquinas.

Nota:

As falhas mais usuais na compilação para máquinas não-i386 ocorrem porque o programador original assumiu, por exemplo, que os ponteiros são do tipo int, ou então que uma versão antiga e relativamente mais frouxa do compilador gcc está sendo utilizada. Cada vez mais, os autores de aplicações estão retrabalhando seu código para remover estes pressupostos — mas se o autor não estiver mantendo o código de forma ativa, você pode precisar fazer isto você mesmo.

Estas são as tarefas que precisam ser executadas para garantir o seu port pode ser compilado:

  1. Esteja atento para falhas de compilação

    Verifique regularmente o cluster de compilação automatizada de ports, o pointyhat, e o scanner de arquivos de distribuição para ver se algum dos ports que você mantém está falhando na compilação ou no download do código fonte (veja a seção sobre recursos para maiores informações sobre estes sistemas). Relatórios de falha também podem chegar até você por email, vindos de outros usuários ou dos sistemas automatizados.

  2. Colete informações

    Uma vez que você tome conhecimento de um problema, colete informações para ajudá-lo a corrigi-lo. Os erros de compilação reportados pelo pointyhay são acompanhados por logs os quais irão lhe mostrar onde a compilação falhou. Se a falha tiver sido reportada à você por um usuário, peça a ele para lhe enviar informações as quais possam lhe ajudar no diagnóstico do problema, tais como:

    • Logs de compilação

    • Os comandos e as opções que foram utilizadas para compilar o port (incluindo as opções definidas no /etc/make.conf)

    • A lista de aplicativos instalados em seus sistemas, como mostrada pelo pkg_info(1)

    • A versão do FreeBSD que eles estão utilizando, como mostrada pelo uname(1) -a

    • Quando a sua Coleção de Ports foi atualizada pela última vez

    • Quando o seu arquivo INDEX foi atualizado pela última vez

  3. Investigue e encontre uma solução

    Infelizmente não existe um processo simples a ser seguido para fazer isto. Porém lembre-se: Se você estiver sem saber o que fazer, peça ajuda! A lista de discussão sobre a coleção de ports do FreeBSD é um bom lugar para começar, e os desenvolvedores do software também estão frequentemente dispostos a ajudar.

  4. Envie as alterações

    Assim como na atualização de um port, você agora deve incorporar as alterações, revisá-las, testá-las, e depois submeter um PR com elas, fornecendo feedback, se necessário.

  5. Envie patches para os desenvolvedores do software

    Em alguns casos você irá precisar modificar o software do seu port para que ele execute no FreeBSD. Alguns (mas não todos) desenvolvedores irão aceitar incorporar tais patches em seu código para a próxima release. Se eles aceitarem, isto pode até ajudar os seus usuários nos outros sistemas derivados do BSD e talvez evite esforços duplicados. Por favor, considere o envio de qualquer patch aplicável aos desenvolvedores do software como uma cortesia.

5.2.3. Investigue os relatórios de bugs e os PRs relacionados ao seu port

Esta seção é sobre a descoberta e correção de bugs.

Os bugs específicos ao FreeBSD são geralmente causados por suposições feitas pelo desenvolvedor sobre o ambiente de compilação e de execução que não se aplicam ao FreeBSD. É pouco provável que você encontre um problema deste tipo, eles são mais sutis e difíceis de diagnosticar.

Estas são as tarefas que precisam ser executadas para garantir que o seu port continua funcionando como esperado:

  1. Responda os relatórios de bugs

    Bugs podem ser reportados para você por meio de email através do Banco de Dados de Relatórios de Problema GNATS. Bugs também podem ser reportados diretamente à você pelos usuários.

    Você deve responder os PRs e demais relatórios no prazo de até 14 dias, mas por favor tente não levar tanto tempo. Tente responder o mais rápido possível, mesmo que seja só para dizer que você precisa de mais algum tempo antes que você possa trabalhar no PR.

    Se você não responder neste prazo de 14 dias, qualquer committer poderá realizar o commit do PR ao qual você não respondeu baseado na regra de maintainer-timeout.

  2. Colete informações

    Se a pessoa que reportou o bug não tiver fornecido também uma correção, você vai precisar coletar as informações que irão lhe permitir gerar uma.

    Se o bug pode ser reproduzido, você pode coletar a maioria das informações necessárias você mesmo. Se não conseguir reproduzi-lo, peça para a pessoa que reportou o bug para coletar as informações para você, tais como:

    • Uma descrição detalhada das suas ações, comportamento esperado para o programa e o seu comportamento atual

    • Cópia dos dados que desencadearam o bug

    • Informação sobre o seu ambiente de compilação e execução — como, por exemplo, a lista dos aplicativos instalados e a saída do env(1)

    • Dumps de memória

    • Rastreamento de pilhas

  3. Elimine os relatórios incorretos

    Alguns dos relatórios de bugs podem estar incorretos. Por exemplo, o usuário pode ter simplesmente utilizado o programa de forma errada; ou os aplicativos instalados podem estar desatualizados e precisando de atualização. À vezes, o bug reportado não é específico ao FreeBSD. Neste caso, relate o bug para o desenvolvedor do software. Se a correção do bug estiver dentro da sua capacidade técnica, você também pode aplicar um patch ao seu port, para que a correção seja disponibilizada antes do release da nova versão oficial por parte do desenvolvedor.

  4. Encontre uma solução

    Assim como ocorre com os erros de compilação, você vai precisar encontrar uma correção para o problema. Mais uma vez, lembre-se de pedir ajuda se você estiver sem saber por onde começar!

  5. Envie ou aprove as alterações

    Assim como ocorre na atualização de um port, agora você deve incorporar as alterações, revisá-las, testá-las, e enviar as suas mudanças em um PR (ou enviar um followup se já existir um PR para o problema). Se outro usuário tiver submetido alterações em um PR, você também pode enviar um followup dizendo se aprova ou não estas mudanças.

5.2.4. Forneça suporte

Faz parte da função de mantenedor prover suporte — não para o software em geral — mas para o port e para qualquer problema ou peculiaridade que seja específica do FreeBSD. Usuários podem contatá-lo com perguntas, sugestões, problemas e patches. Na maior parte do tempo serão mensagens especificas ao FreeBSD.

Ocasionalmente você pode precisar usar as suas habilidades diplomáticas para gentilmente direcionar os usuários que buscam suporte geral aos recursos apropriados. Menos frequentemente você irá encontrar pessoas perguntando por que o RPM não está atualizado ou como eles podem fazer o software executar no Linux XYZ. Aproveite a oportunidade para informar que o seu port está atualizado (se ele estiver, é claro) e sugira que eles testem o FreeBSD.

À vezes os usuários e desenvolvedores irão decidir que você é um pessoa ocupada, cujo tempo é valioso e irão fazer parte do trabalho para você. Por exemplo, eles podem:

  • Submeter um PR ou enviar um patch para atualizar o seu port,

  • investigar e talvez disponibilizar uma correção para um PT, ou

  • de outra forma, submeter mudanças para o seu port.

Nestes casos a sua principal obrigação é responder rapidamente. Mais uma vez, o tempo limite de espera pela resposta de um mantenedor é de 14 dias. Após este período as alterações podem ser processadas sem a sua aprovação. Eles se deram ao trabalho de fazer isto por você, portanto, tente pelo menos responder prontamente. Em seguida analise, aprove, modifique ou discuta as alterações com eles o mais rapidamente possível.

Se você puder fazê-los sentir que a contribuição deles é apreciada (e ela deveria ser), você terá melhores chances de persuadi-los a fazer mais coisas para você no futuro :-).

Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.

Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.