3. Contribuindo com a coleção de ports

3.1. Adotando um port não mantido

3.1.1. Escolhendo um port não mantido

Assumir a manutenção de um port sem mantenedor é uma ótima maneira de se envolver. Os ports sem mantenedor só são atualizados e corrigidos quando alguém se oferece para trabalhar neles. Há um grande número de ports não mantidos. É uma boa ideia começar com a adoção de uma port que você usa regularmente.

Os ports sem um responsável tem o seu MAINTAINER configurado como ports@FreeBSD.org. Uma lista com todos os ports nesta situação, bem como os seus erros atuais e os seus relatórios de problemas pode ser visualizada no Sistema de Monitoração da coleção de ports do FreeBSD.

Alguns ports afetam um grande número de outros devido a dependências e relacionamentos de ports escravos. Geralmente, esperamos que as pessoas tenham alguma experiência antes de se voluntariarem para manter tais ports.

Você pode verificar se um port tem ou não dependências ou se outros ports dependem dele consultando o índice mestre de ports chamado INDEX. (O nome do arquivo varia de acordo com a versão do FreeBSD; por exemplo, INDEX-8.) Alguns ports têm dependências condicionais que não estão incluídas na construção do INDEX padrão. Esperamos que você seja capaz de reconhecer estes ports através da analise do arquivo Makefile de outros ports.

3.1.2. Como adotar o port

Primeiro, certifique-se de entender quais serão as suas responsabilidades de como mantenedor. Leia também o Porter's Handbook. Por favor, não se comprometa com mais do que você acha que pode lidar sem se sobrecarregar.

Você pode solicitar para se tornar o responsável pela manutenção de qualquer port que não esteja sendo mantido por outra pessoa assim que desejar. Basta definir o parâmetro MAINTAINER para o seu próprio endereço de e-mail e enviar um PR (Relatório de Problemas) com a alteração. Se o port tiver erros de compilação ou precisar de atualização, você pode aproveitar para incluir quaisquer outras alterações que sejam necessárias neste mesmo PR. Isso irá acelerar o processo pois muitos committers não estão dispostos a atribuir a responsabilidade de manutenção de um port para alguém que não tenha um histórico conhecido com o FreeBSD. O envio de PRs (relatórios de problema) para corrigir erros de compilação ou para atualizar um port é a melhor maneira de estabelecer este histórico.

Submeta o seu relatório de problema na categoria ports e utilize a classe change-request. Um committer irá examinar o seu relatório, confirmará as alterações e, por fim, fechará o relatório. Às vezes, esse processo pode demorar um pouco (os committers também são voluntários).

3.2. O desafio para os mantenedores de um port

Esta seção lhe dará uma ideia do motivo pelo qual os ports precisam ser mantidos e descreve as responsabilidades de um mantenedor de ports.

3.2.1. Por que os ports requerem manutenção

Criar um port é uma tarefa eventual. Mas garantir que um port esteja sempre atualizado e que continue a ser compilado e executado corretamente requer um esforço de manutenção contínuo. Os mantenedores são as pessoas que dedicam parte do seu tempo para atingir esses objetivos.

O principal motivo pelo qual a coleção de ports precisa de manutenção é o de trazer os mais recentes e o melhores softwares de terceiros para a comunidade FreeBSD. Um desafio adicional é manter os ports individuais funcionando dentro do framework da coleção de ports à medida que ela evolui.

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

  • Novas versões e atualizações de software. Novas versões e atualizações de software são disponibilizadas o tempo todo para os aplicativos já convertidos, e elas precisam ser incorporadas à Coleção de Ports a fim de prover software atualizado.

  • Mudanças nas dependências. Se forem feitas alterações significativas nas dependências do seu port, talvez seja necessário atualizá-las para que ele continue funcionando corretamente.

  • Mudanças que afetem os ports que dependem do seu. Se outros ports dependerem de um port que você mantém, as mudanças no seu port podem requerer um alinhamento prévio com outros mantenedores.

  • Interação com outros usuários, mantenedores e desenvolvedores. Parte de ser um mantenedor é assumir uma função de suporte. Não existe a expectativa de que você ofereça suporte de uma maneira geral (mas você é bem vindo se quiser fazer isso). O que você deve prover é um ponto de coordenação para as questões específicas do FreeBSD relacionadas aos seus ports.

  • Caça aos bugs. Um port pode ser afetado por bugs específicos do FreeBSD. Você precisará investigar, encontrar e consertar estes bugs quando forem reportados. Testar meticulosamente um port para identificar todos os seus possíveis problemas antes que ele seja adicionado à Coleção de Ports é ainda melhor.

  • Alterações na infraestrutura e política de ports. Ocasionalmente os sistemas utilizados para construir os ports e pacotes são atualizados ou uma nova recomendação que afeta a infraestrutura é realizada. Você deverá estar atento a estas mudanças caso seus ports sejam afetados e necessitem de atualização.

  • Mudanças no sistema base. O FreeBSD está em constante desenvolvimento. Mudanças no software, bibliotecas, kernel ou até mesmo mudanças de políticas podem resultar em necessidade de mudança nos ports.

3.2.2. Responsabilidades do mantenedor

3.2.2.1. Manter seus ports atualizados

Esta seção descreve o processo a ser seguido para manter seus ports atualizados.

Esta é uma visão geral. Mais informações sobre a atualização de um port está disponível no Porter's Handbook.

  1. Preste atenção às atualizações

    Monitorar os fabricantes upstream em relação a liberação de novas versões, patches e correções de segurança para o software. Listas de discussão de anúncios ou páginas web de noticias sobre o software são úteis para este propósito. Algumas vezes os usuários entrarão em contato com você perguntando quando seu port será atualizado. Se você estiver ocupado com outras atividades ou devido a qualquer outra razão não puder realizar a atualização naquele momento, pergunte se o usuário pode te ajudar enviando uma atualização.

    Você também pode receber emails automáticos do Verificador de Versões de Ports do FreeBSD informando a você que uma nova versão do disftile do seu port está disponível. Mais informações sobre este sistema (incluindo como deixar de receber seus emails no futuro) serão enviadas na mensagem.

  2. Incorporar mudanças

    Quando estiverem disponíves, incorpore as mudanças em seu port. Você precisa ser capaz de gerar um patch entre o port original e o port atualizado.

  3. Revisão e teste

    Examine cuidadosamente e teste as suas mudanças:

    • Compile, instale e teste o seu port em todas plataformas e arquiteturas que você puder. É comum um port funcionar em uma branch ou plataforma e falhar em outra.

    • Certifique-se de que as dependências do seu port estão completas. A maneira recomendada de fazer isso é instalando seu próprio ports tinderbox. Consulte a seção sobre recursos para mais informações.

    • Verifique se a lista de componentes do pacote está atualizada. Isto envolve adicionar novos arquivos e diretórios , bem como remover as entradas sem uso.

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

    • Considere se as mudanças no seu port podem fazer com que outros ports tenham problemas. Se este for o caso, coordene as mudanças com os mantenedores destes ports. Isto é especialmente importante se a sua atualização modifica a versão de uma biblioteca compartilhada; neste caso, os ports afetados precisarão obter no mínimo um incremento no seu PORTREVISION para que eles possam ser atualizados automaticamente por ferramentas automatizadas como o portmaster ou o portupgrade(1).

  4. Envie as alterações

    Submeta sua atualização enviando um relatório de problema (PR) com uma explicação das alterações e um patch contendo as diferenças entre o port original e a versão atualizada. Por favor, consulte o artigo Escrevendo um Relatório de Problema para o FreeBSD para mais informações sobre como escrever um PR realmente bom.

    Nota:

    Por favor não submeta um arquivo shar(1) do port inteiro, ao invés disso, utilize o comando diff(1) -ruN. Desta forma, os committers podem ver com mais facilidade exatamente quais alterações estão sendo feitas. Consulte a seção Upgrading do Porter's Handbook para maiores informações.

  5. Aguarde

    Em algum momento, um commiter lidará com o seu PR. Isto pode levar alguns minutos ou pode levar semanas - portanto, seja paciente.

  6. Dê feedback

    Se um committer encontrar um problema nas suas alterações, ele provavelmente o encaminhará de volta para você. Uma resposta rápida a este contato irá ajudá-lo a ter o seu PR resolvido mais rapidamente. É muito importante manter o canal de comunicação aberto para agilizar a resolução de qualquer eventual problema.

  7. E finalmente

    As suas alterações serão incorporadas na arvore de código fonte e o seu port será atualizado. O PR então será fechado pelo committer. É isso!

3.2.2.2. Certifique-se de que seus ports continuem a ser compilados corretamente

Esta seção é sobre a descoberta e a solução de problemas que fazem seus ports deixarem de ser compilados corretamente.

O projeto FreeBSD garante o funcionamento da coleção de Ports apenas na branch -STABLE. Teoricamente, você deve será capaz de garantir o funcionamento do port ao executá-lo na ultima release de cada branch(já que não se espera que as ABIs mudem), mas se você puder executar a branch, será ainda melhor.

Como a maioria das instalações do FreeBSD rodam em máquinas compatíveis com o PC (o que é chamado de arquitetura i386), esperamos que você mantenha o port funcionando nesta arquitetura. Nós preferimos que os ports também funcionem de forma nativa na arquitetura amd64. É completamente justo pedir ajuda caso você não tenha uma dessas máquinas para fazer seus testes.

Nota:

Os padrões usuais nas falhas para máquinas não-x86 são que os programadores originais assumiram que, por exemplo, os ponteiros são ints, ou que um compilador gcc mais antigo seria utilizado. Cada vez mais, os autores de aplicativos estão retrabalhando o código das suas aplicações para remover essas suposições - mas se o autor não estiver mantendo ativamente o código, talvez seja necessário que você mesmo faça isso.

Estas são as tarefas que você precisa executar para garantir que o seu port pode ser compilado:

  1. Preste atenção para falhas de compilação

    Confira o seu e-mail e busque por mensagens do pkg-fallout@FreeBSD.org e consulte o scanner de arquivos distfiles para verificar se algum dos ports que estão falhando na compilação estão desatualizados.

  2. Colete informação

    Quando você estiver ciente de um problema, colete informações para ajudá-lo a solucioná-lo. Os erros de compilação relatados pelo pkg-fallout são acompanhados por logs que mostram onde a compilação falhou. Se a falha foi reportada para você por um usuário, peça para que ele lhe envie informações que possam ajudar no diagnóstico do problema, tais como:

    • Logs de compilação

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

    • Uma lista dos pacotes instalados no sistema como mostrado pelo comando pkg-info(8)

    • A versão do FreeBSD que ele está executando como mostrado pelo comando uname(1) -a

    • Quando a coleção de ports dele foi atualizada pela última vez

    • Quando a árvore de ports e o arquivo INDEX dele foram atualizados pela última vez

  3. Investigue e encontre uma solução

    Infelizmente não existe nenhum processo direto a ser seguido para fazer isso. Porém, lembre-se: se você está emperrado, peça ajuda! A lista de discussão de ports do FreeBSD é um bom lugar para começar, e os desenvolvedores de upstream são frequentemente muito prestativos.

  4. Envie as alterações

    Assim como na atualização de um port, agora você deve incorporar as alterações, revisar, testar e enviar suas alterações em um relatório de problemas (PR) e fornecer feedback, se solicitado.

  5. Envie os patches para os autores upstream

    Em alguns casos, você terá que fazer um patch para que um port execute no FreeBSD. Alguns (mas não todos) autores upstream aceitarão incorporar tais patches em seu código na próxima versão. Se eles aceitarem, isto poderá até ajudar os usuários de outros sistemas BSD e talvez evitar um esforço duplicado. Por favor, considere o envio aos autores de quaisquer patches aplicáveis como uma cortesia.

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

Esta seção é sobre como descobrir e corrigir bugs.

Bugs específicos do FreeBSD são causados geralmente por suposições sobre os ambientes de compilação e execução que não se aplicam ao FreeBSD. É pouco provável que você encontre um problema desse tipo, mas se encontrar ele poderá ser mais sutil e difícil de diagnosticar.

Estas são as tarefas que você precisa executar para garantir que o seu port continuará funcionando como pretendido:

  1. Responda os relatórios de bugs

    Bugs podem ser reportados para você por e-mail através do Sistema de Relatório de Problemas. Os bugs também podem ser reportados diretamente a você pelos usuários.

    Você deve responder os PRs (Relatório de Problemas) e outros relatórios dentro de 14 dias, mas por favor, tente não levar tanto tempo. Tente responder o mais rápido possível, mesmo que seja apenas para dizer que você precisa de mais algum tempo antes de poder trabalhar no PR.

    Se você não tiver respondido após 14 dias, qualquer committer poderá efetuar o commit de um PR que você não tenha respondido por meio da regra de maintainer-timeout.

  2. Colete informação

    Se a pessoa que reportou o bug não tiver fornecido uma correção, você precisará coletar as informações que permitirão gerar uma.

    Se o bug for reproduzível, você poderá coletar a maior parte das informações necessárias você mesmo. Caso contrário, peça à pessoa que relatou o bug para coletar as informações para você, tais como:

    • Uma descrição detalhada das suas ações, comportamento esperado e comportamento real do aplicativo

    • Cópias dos dados de entrada usados para acionar o bug

    • Informações sobre seu ambiente de compilação e execução - por exemplo, uma lista de pacotes instalados e a saída de env(1)

    • Core dumps

    • Stack traces

  3. Elimine os relatórios incorretos

    Alguns relatórios de erros podem estar incorretos. Por exemplo, o usuário pode ter simplesmente usado de forma errada o programa; ou seus pacotes instalados podem estar desatualizados e precisam ser atualizados. Às vezes, um bug relatado não é específico do FreeBSD. Neste caso relate o bug para os desenvolvedores upstream. Se você for capaz de corrigir o bug, você também poderá criar um patch do port para que a correção seja aplicada antes da próxima versão do upstream.

  4. Encontre uma solução

    Tal como acontece com erros de compilação, você precisará encontrar uma correção para o problema. Mais uma vez, lembre-se de perguntar se você estiver emperrado!

  5. Envie ou aprove alterações

    Assim como na atualização de um port, agora você deve incorporar alterações, revisar, testar e enviar suas alterações em um PR (ou enviar um follow-up se já existir um PR para o problema). Se outro usuário tiver enviado alterações no PR, você também poderá enviar um follow-up dizendo se aprova ou não as alterações.

3.2.2.4. Forneça Suporte

Parte de ser um mantenedor é prover suporte - não para o software em geral - mas para o port e quaisquer peculiaridades e problemas específicos dele no FreeBSD. Os usuários podem entrar em contato com dúvidas, sugestões, problemas e patches. Na maioria das vezes, sua correspondência será específica para o FreeBSD.

Ocasionalmente, você pode ter que invocar suas habilidades diplomáticas, e gentilmente, direcionar os usuários que buscam suporte genérico para os recursos apropriados. Com menos frequência você encontrará uma pessoa perguntando por que os RPMs não estão atualizados ou como eles podem fazer o software rodar sob o Foo Linux. Aproveite a oportunidade para dizer a eles que o seu port está atualizado (se estiver, é claro!) e sugira que eles experimentem o FreeBSD.

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

  • enviar um PR ou lhe enviar patches para atualizar o seu port,

  • investigar e talvez fornecer uma correção para um PR, ou

  • caso contrário, enviar alterações para o seu port.

Nestes casos, a sua principal obrigação é responder rapidamente. Mais uma vez, o tempo limite para mantenedores não responsivos é de 14 dias. Após esse período, as alterações podem ser aceitas mesmo sem terem sido aprovadas. Eles se deram ao trabalho de fazer isso por você; por favor, tente pelo menos responder prontamente. Em seguida, revise, aprove, modifique ou discuta as alterações com eles o mais rápido possível.

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

3.3. Encontre e conserte um port quebrado

Existem dois lugares realmente bons para se encontrar um port que precisa de alguma atenção.

Você pode usar a interface web do banco de dados dos Relatório de Problemas para pesquisar e visualizar os PRs não resolvidos. A maioria dos PRs relacionados aos ports são atualizações, mas com um pouco de pesquisa e análise das sinopses você deve encontrar algo interessante para trabalhar (a classe bug-bug é um bom lugar para começar).

O outro lugar é o Sistema de Monitoramento de Ports do FreeBSD. Em particular, procure por ports sem mantenedores com erros de compilação e por ports marcados com BROKEN. Não existe nenhum problema em também enviar alterações para um port com um mantenedor ativo, mas antes lembre-se de consultar o mantenedor para o caso dele já estar trabalhando no problema.

Depois de encontrar um bug ou problema, colete informações, investigue e corrija! Se houver um PR existente, de seguimento a ele. Caso contrário, crie um novo PR. Suas alterações serão analisadas e, se tudo estiver OK, elas serão aceitas e incorporadas.

3.4. Quando parar

À medida que seus interesses e compromissos mudam, você pode descobrir que não tem mais tempo para continuar com algumas (ou todas) as suas contribuições para a coleção de ports. Tudo bem! Por favor, nos avise se você não estiver mais usando um port ou se não tiver mais tempo ou interesse em ser um mantenedor. Desta forma, podemos seguir em frente e permitir que outras pessoas tentem trabalhar nos problemas existentes com o port sem termos que esperar por sua resposta. Lembre-se, o FreeBSD é um projeto voluntário, então se a manutenção de um port não for mais divertida, provavelmente é hora de deixar alguém fazer isso!

De qualquer forma, a Equipe de Gerenciamento da Coleção de Ports (portmgr) reserva-se o direito de redefinir o seu status de mantenedor se você não tiver mantido ativamente o seu port durante um determinado período de tempo. (Atualmente, este período é definido como 3 meses.) Com isso, queremos dizer que existem problemas não resolvidos ou atualizações pendentes que não foram tratadas por você durante esse período.

3.5. Recursos para mantenedores de ports e contribuidores

O Porter's Handbook é o seu Guia de Mochileiro para o sistema de ports. Mantenha-o à mão!

O artigo Escrevendo um relatório de problemas para o FreeBSD descreve como melhor formular e enviar um PR. Em 2005, foram submetidos mais de onze mil relatórios de problemas relacionados aos ports! Ao seguir as boas práticas descritas neste artigo você nos ajudará a reduzir em muito o tempo necessário para lidar com seus PRs.

O Banco de dados de problemas reportados.

O Sistema de Monitoramento de Ports do FreeBSD pode mostrar informações cruzadas sobre os ports, tais como erros de compilação e relatórios de problemas. Se você é um mantenedor, você pode usá-lo para verificar o status de compilação dos seus ports. Como colaborador, você pode usá-lo para encontrar ports quebrados e ports sem um mantenedor ativo que precisam ser consertados.

O scanner de arquivos distfile da coleção de ports do FreeBSD pode lhe mostrar os ports para os quais os arquivos distfiles não estão disponíveis. Você pode utilizá-lo para verificar seus próprios ports ou para encontrar ports que precisam ter seu MASTER_SITES atualizado.

O uso do ports-mgmt/poudriere é a maneira mais completa de testar um port durante todo o ciclo de instalação, empacotamento e desinstalação. A documentação está localizada no Repositório do poudriere no github

O portlint(1) é uma aplicação que pode ser utilizada para verificar se o seu port está em conformidade com muitas diretrizes importantes de estilo e função. O portlint é um aplicativo heurístico simples, portanto você deve usá-lo apenas como um guia. Se o portlint sugerir alterações que não sejam razoáveis, consulte o Porter's Handbook ou peça conselhos.

A Lista de discussão de ports do FreeBSD é destinada para discussões gerais relacionadas aos ports. É um bom lugar para pedir ajuda. Você pode se inscrever, ler e pesquisar os arquivos da lista. Ler os arquivos da Lista de discussão sobre bugs dos ports do FreeBSD e as mensagens de commit no SVN da árvore de ports para head/ também pode ser interessante.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.