$FreeBSD$ Este artigo descreve as formas pelas quais uma pessoa pode contribuir com a Coleção de Ports do FreeBSD. Sam Lawrance Mark Linimon &tm-attrib.freebsd; &tm-attrib.general; Contribuindo com o ports A Coleção de Ports é um trabalho permanente, em constante evolução. Nós queremos oferecer aos nossos usuários um repositório de softwares de terceiros que seja fácil de utilizar, atualizado e de alta qualidade. Qualquer um pode se envolver, e existem muitas formas diferentes de fazer isso. Contribuir para a coleção de ports é uma excelente forma de ajudar e de devolver algo para o projeto. Não importa se você está à procura de participação contínua, ou apenas um desafio divertido para um dia chuvoso, nós vamos adorar receber a sua ajuda! Como voluntário, o que você faz é limitado apenas pelo que você quer fazer. No entanto, pedimos que você tome conhecimento do que os outros membros da comunidade &os; irão esperar de você. Você pode querer levar isso em conta antes de decidir se voluntariar. Existem várias maneiras pelas quais você pode contribuir para manter a árvore de Ports atualizada e em boas condições de funcionamento: Encontre algum software legal e útil e crie um port para ele. Existe um grande número de ports que não têm nenhum mantenedor (maintainer). Torne-se um mantenedor e adote um port. Se você tiver criado ou adotado um port, tome conhecimento do que precisa fazer agora que é um mantenedor. Quando você estiver procurando por um desafio rápido você pode corrigir um bug ou um port quebrado. Existe um documento separado, disponível para ajudar e guiá-lo no processo de criação (ou de atualização) de um port, chamado Porter's Handbook. O Porter's Handbook é a melhor fonte de referência para se trabalhar no sistema de ports. Ele fornece detalhes de como o sistema de ports funciona e discute as boas práticas recomendadas. Assumir a responsabilidade pela manutenção de um port que está abandonado é uma excelente forma de se envolver. Ports sem manutenção só são atualizados ou consertados quando alguém se voluntaria à trabalhar neles. Existe um grande número de ports sem manutenção. É uma boa idéia iniciar com a adoção de um port que você usa regularmente. Os ports sem manutenção tem a variável MAINTAINER setada como ports@FreeBSD.org em seu Makefile. A lista dos ports sem manutenção, seus erros atuais, e seus respectivos relatórios de problema , pode ser vista no Sistema de Monitoração de Ports do FreeBSD. Alguns ports afetam um grande número de outros devido as suas dependências e aos ports escravos. Você deve esperar até que tenha alguma experiência antes de se voluntariar para manter um port destes. Você pode descobrir se um port tem ou não dependências ou ports escravos, observando o índice principal de ports chamado INDEX. (O nome do arquivo varia de acordo com a release do &os;; por exemplo, INDEX-8.) Alguns ports têm dependências condicionais que não são incluídas na compilação padrão do INDEX. Esperamos que você seja capaz de identificar estes ports observando os Makefiles dos outros ports. Primeiro certifique-se de que você compreende as suas responsabilidades como um mantenedor. Também leia o Porter's Handbook. Por favor, não se comprometa com mais do que o que você se sente capaz de fazer. Você pode pedir para se tornar o responsável por um port sem manutenção no momento em que desejar. Basta definir o MAINTAINER para o seu próprio email e enviar um PR (relatório de problema) com a mudança. Se o port tiver erros de compilação ou se estiver precisando de atualização, você pode querer enviar quaisquer outras alterações no mesmo PR. Isto irá ajudar porque muitos comitters estão pouco dispostos a designar alguém sem um histórico conhecido junto ao &os; como responsável pela manutenção de um port. Enviar PRs os quais corrigem erros de compilação ou que atualizam ports é a melhor forma de estabelecer um. Envie o seu PR com a categoria ports e a classe change-request. Um comitter irá examinar o seu PR, dar commit das alterações e finalmente fechar o seu PR. Algumas vezes este processo pode demorar um pouco (afinal os comitters também são voluntários). 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. 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 &os;. 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 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. Se forem feitas mudanças significativas nas dependências de seu port, ele pode precisar ser atualizado para que continue a funcionar corretamente. Se outros ports dependem de um port que você mantém, alterações em seu port podem demandar coordenação com outros mantenedores. 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 &os;. Um port pode ser afetado por erros que são específicos ao &os;. 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. Ocasionalmente, 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. O &os; 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. 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. 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 &os; 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. 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. 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 &man.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 &man.portupgrade.1;. 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. Por favor, não envie um arquivo &man.shar.1; com o port inteiro. Em vez disso, utilize &man.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. 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. 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. As suas alterações serão aceitas e o seu port estará atualizado. O PR será fechado pelo committer. E é isso! 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 &os; 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. 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: 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. 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 &man.pkg.info.1; A versão do &os; que eles estão utilizando, como mostrada pelo &man.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 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 &a.ports; é um bom lugar para começar, e os desenvolvedores do software também estão frequentemente dispostos a ajudar. 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. Em alguns casos você irá precisar modificar o software do seu port para que ele execute no &os;. 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. Esta seção é sobre a descoberta e correção de bugs. Os bugs específicos ao &os; 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 &os;. É 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: 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. 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 &man.env.1; Dumps de memória Rastreamento de pilhas 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 &os;. 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. 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! 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. 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 &os;. Usuários podem contatá-lo com perguntas, sugestões, problemas e patches. Na maior parte do tempo serão mensagens especificas ao &os;. 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 &os;. À 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 :-). Existem dois lugares muito bons nos quais você pode encontrar ports que precisam de alguma atenção. Você pode utilizar a interface web do banco de dados dos Relatórios de Problema para pesquisar e visualizar os PRs não resolvidos. A maioria dos PRs da categoria ports são referentes a atualizações, mas com um pouco de pesquisa e leitura das sinopses você deverá ser capaz de encontrar algo interessante para trabalhar (a classe sw-bug é um bom ponto de partida). O outro lugar é o Sistema de Monitoração de Ports do &os;. Em especial, procure por ports sem manutenção e com erros de compilação e por ports que estejam marcados como BROKEN (quebrados). É OK enviar alterações para um port que está sendo mantido, mas lembre-se de consultar primeiro o mantenedor para o caso dele já estar trabalhando na solução do problema. Depois que você tiver encontrado um bug ou problema, colete informações, investigue e conserte! Se existir já um PR, envie um followup. Caso contrário, crie um novo PR. Suas alterações serão revisadas e se tudo estiver OK, serão processadas e incorporadas. A medida que seus interesses e compromissos mudarem, você poderá se ver sem tempo para continuar com algumas (ou com todas) das suas contribuições para os seus ports. Tudo bem! Por favor, nos avise se você não estiver mais utilizando um port, ou se de outra forma você não tem mais tempo ou mesmo interesse para ser um mantenedor. Desta forma, poderemos seguir em frente e permitir que outras pessoas trabalhem com os problemas existentes nestes ports sem ter que aguardar pela sua resposta. Lembre-se, o &os; é um projeto voluntário, se manter um port não é mais divertido, provavelmente está na hora de deixar alguma outra pessoa fazê-lo. De qualquer forma, a Equipe de Gerenciamento do Ports (portmgr) se reserva o direito de revogar a sua condição de mantenedor de um port se você não estiver dando manutenção de forma ativa ao mesmo já há algum tempo (Atualmente, o período limite é de 3 meses). Com isto queremos dizer que existem problemas não resolvidos ou atualizações pendentes as quais não foram trabalhadas durante esse tempo. O Porter's Handbook é o seu guia de mochila para o sistema de ports. Mantenha ele sempre a mão! O artigo Escrevendo Relatórios de Problemas para o FreeBSD descreve as melhores práticas na elaboração e na submissão de um PR. Em 2005 foram submetidos mais de 11 mil relatórios de problema na categoria ports. Ao seguir as recomendações deste artigo você irá nos ajudar a reduzir o tempo necessário para processar o seu PR. O Banco de Dados de Relatórios de Problemas. O Pointyhat é o cluster de compilação do sistema de ports. Você pode utilizar o Pointyhat para verificar os logs de compilação de um port em todas as arquiteturas e releases principais. O Sistema de Monitoração de Ports do &os; pode lhe mostrar informações de referência cruzada sobre um port tais como erros de compilação e relatórios de problema. Se você é um mantenedor você pode utilizá-lo para verificar o status de compilação dos seus ports. Se você é um colaborador você pode utilizá-lo para encontrar ports quebrados e sem manutenção os quais precisam ser corrigidos. O Scanner de Arquivos de Distribuição da Coleção de Ports do FreeBSD pode lhe mostrar ports para os quais não é possível fazer o download do código fonte. Você pode utilizá-lo nos seus próprios ports ou usá-lo para encontrar ports que precisam ter o seu MASTER_SITES atualizado. O ports tinderbox é a forma mais completa de testar um port através de todo o ciclo de instalação, empacotamento, e desinstalação. Ele possui uma interface de linha de comando, mas também pode ser controlado através de uma interface web. Ele está disponível em ports/ports-mgmt/tinderbox. Você irá encontrar maiores informações na Home page do marcuscom sobre o tinderbox. O &man.portlint.1; é um aplicativo o qual pode ser utilizado para verificar se o seu port esta em conformidade com as muitas e importantes diretrizes funcionais e de estilo que se aplicam a um port. O portlint é um aplicação heurística simples, de forma que você deve usá-lo apenas como um guia. Se o portlint sugerir uma alteração que lhe parece ser irracional, consulte o Porter's Handbook ou peça orientação usando os canais apropriados. A &a.ports; destina-se a discussão de assuntos gerais relacionados ao sistema de ports. Ela é um bom lugar para se pedir ajuda. Você pode se inscrever, ou ler e consultar o histórico de mensagens da lista. A leitura do histórico da &a.ports-bugs; e da &a.cvs-ports; também pode ser interessante.