Contribuindo para a Coleção de Ports do FreeBSD
Anterior |  | Próxima

# 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 `ports`. 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.

- 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 :-).

Anterior | Principal | Próxima
Adotando um `port` sem manutenção |  | Localizando e corrigindo um `port` quebrado.

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>.