path: root/pt_BR.ISO8859-1/articles/contributing-ports/article.sgml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
        "../../../share/sgml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent">
%entities;
]>

<!--
     The FreeBSD Documentation Project
     The FreeBSD Brazilian Portuguese Documentation Project

     Original revision: r39544

     $FreeBSD$
-->

<article lang='pt_br'>
  <articleinfo>
    <title>Contribuindo para a Coleção de Ports do FreeBSD</title>

    <abstract>
      <title>Sumário</title>

      <para>Este artigo descreve as formas pelas quais uma pessoa pode
	contribuir com a Coleção de
	<literal>Ports</literal> do FreeBSD.</para>
    </abstract>

    <authorgroup>
      <author>
	<firstname>Sam</firstname>
	<surname>Lawrance</surname>
      </author>
      <author>
	<firstname>Mark</firstname>
	<surname>Linimon</surname>
      </author>
    </authorgroup>

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.general;
    </legalnotice>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD</releaseinfo>
  </articleinfo>

  <indexterm><primary>Contribuindo com o ports</primary></indexterm>

  <sect1>
    <title>Introdução</title>

    <para>A Coleção de <literal>Ports</literal>
      é 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.</para>

    <para>Qualquer um pode se envolver, e existem muitas formas
      diferentes de fazer isso.  Contribuir para a
      coleção de <literal>ports</literal> é 
      uma excelente forma de ajudar e de <quote>devolver</quote> 
      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!</para>
      
    <para>
      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.</para>
  </sect1>

  <sect1 id="what-contribute">
    <title>O que você pode fazer para ajudar</title>

    <para>Existem várias maneiras pelas quais você pode
      contribuir para manter a árvore de 
      <literal>Ports</literal> atualizada e em boas 
      condições de funcionamento:</para>
    
    <itemizedlist>
      <listitem>
	<para>Encontre algum software legal e útil e 
	  <link linkend="create-port">crie um 
	  <literal>port</literal></link> para ele.</para>
      </listitem>

      <listitem>
	<para>Existe um grande número de 
	  <literal>ports</literal> que não têm nenhum 
	  mantenedor (<quote>maintainer</quote>).  Torne-se um 
	  mantenedor e <link linkend="adopt-port">adote um 
	  <literal>port</literal></link>.</para>
      </listitem>

      <listitem>
	<para>Se você tiver criado ou adotado um
	  <literal>port</literal>, tome conhecimento <link 
	  linkend="maintain-port">do que precisa fazer agora que
	  é um mantenedor</link>.</para>
      </listitem>

      <listitem>
	<para>Quando você estiver procurando por um desafio
	  rápido você pode <link 
	  linkend="fix-broken">corrigir um bug ou um
	  <literal>port</literal> quebrado</link>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="create-port">
    <title>Criando um novo <literal>port</literal></title>

    <para>Existe um documento separado, disponível para ajudar
      e guiá-lo no processo de criação (ou de
      atualização) de um <literal>port</literal>,
      chamado <ulink
      url="&url.books.porters-handbook;"><literal>Porter's
      Handbook</literal></ulink>.  O <literal>Porter's
      Handbook</literal> é a melhor fonte de referência
      para se trabalhar no sistema de <literal>ports</literal>.  Ele
      fornece detalhes de como o sistema de <literal>ports</literal>
      funciona e discute as boas práticas recomendadas.</para>
  </sect1>

  <sect1 id="adopt-port">
    <title>Adotando um <literal>port</literal> sem
      manutenção</title>

    <sect2>
      <title>Escolhendo um <literal>port</literal> sem
	manutenção</title>

      <para>Assumir a responsabilidade pela manutenção 
	de um <literal>port</literal> que está abandonado 
	é uma excelente forma de se envolver.  
	<literal>Ports</literal> sem manutenção 
	só são atualizados ou consertados quando 
	alguém se voluntaria à trabalhar neles.  
	Existe um grande número de <literal>ports</literal> 
	sem manutenção.  É uma boa idéia 
	iniciar com a adoção de um 
	<literal>port</literal> que você usa 
	regularmente.</para>

      <para>Os <literal>ports</literal> sem manutenção 
	tem a variável <makevar>MAINTAINER</makevar> setada 
	como <literal>ports@FreeBSD.org</literal> em seu
	<filename>Makefile</filename>.  A lista dos
	<literal>ports</literal> sem manutenção, seus
	erros atuais, e seus respectivos relatórios de problema
	, pode ser vista no  <ulink
	url="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">Sistema
	de Monitoração de Ports do
	FreeBSD</ulink>.</para>
      
      <para>Alguns <literal>ports</literal> afetam um grande
	número de outros devido as suas dependências e 
	aos <literal>ports</literal> escravos.  Você deve 
	esperar até que tenha alguma experiência antes 
	de se voluntariar para manter um <literal>port</literal> 
	destes.</para>
	
      <para>Você pode descobrir se um <literal>port</literal> 
	tem ou não dependências ou  
	<literal>ports</literal>
	escravos, observando o índice principal de ports
	chamado <filename>INDEX</filename>.  (O nome do arquivo varia
	de acordo com a release do &os;; por exemplo,
	<filename>INDEX-8</filename>.)  Alguns
	<literal>ports</literal> têm dependências
	condicionais que não são incluídas na
	compilação padrão do
	<filename>INDEX</filename>.  Esperamos que você seja
	capaz de identificar estes <literal>ports</literal>
	observando os <filename>Makefile</filename>s dos outros
	<literal>ports</literal>.</para>
    </sect2>

    <sect2>
      <title>Como adotar um <literal>port</literal></title>

      <para>Primeiro certifique-se de que você compreende as 
	suas <link linkend="maintain-port">responsabilidades como um
	mantenedor</link>.   Também leia o <ulink
	url="&url.books.porters-handbook;">Porter's Handbook</ulink>.
	<emphasis>Por favor, não se comprometa com mais do 
	que o que você se sente capaz de 
	fazer.</emphasis></para>
      
      <para>Você pode pedir para se tornar o responsável
	por um <literal>port</literal> sem manutenção no
	momento em que desejar.  Basta definir o
	<makevar>MAINTAINER</makevar> para o seu próprio email
	e enviar um PR (relatório de problema) com a
	mudança.  Se o <literal>port</literal> 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 <literal>comitters</literal> 
	estão pouco dispostos a designar alguém sem um
	histórico conhecido junto ao &os; como
	responsável pela manutenção de um
	<literal>port</literal>.  Enviar PRs os quais corrigem erros
	de compilação ou que atualizam 
	<literal>ports</literal> é a melhor forma de
	estabelecer um.</para>
      
      <para>Envie o seu PR com a categoria <literal>ports</literal> 
	e a classe <literal>change-request</literal>.  Um
	<literal>comitter</literal> irá examinar o seu PR, dar
	<literal>commit</literal> das alterações e
	finalmente fechar o seu PR.  Algumas vezes este processo pode
	demorar um pouco (afinal os <literal>comitters</literal>
	também são voluntários).</para>
    </sect2>
  </sect1>

  <sect1 id="maintain-port">
    <title>Os desafios dos mantenedores de 
      <literal>ports</literal></title>

    <para>Esta seção lhe dará uma idéia de
      porque os <literal>ports</literal> precisam ser mantidos e
      irá apresentar as responsabilidades de um mantenedor de
      <literal>ports</literal>.</para>
      
    <sect2 id="why-maintenance">
      <title>Porque os <literal>ports</literal> precisam de
	manutenção</title>

      <para>Criar um <literal>port</literal> é uma tarefa que
	demanda esforço uma única vez.  Garantir que um
	<literal>port</literal> está atualizado e que continua
	a compilar e a executar é um esforço de 
	manutenção permanente.  Os mantenedores
	(<quote>maintainers</quote>), são pessoas as quais
	dedicam uma parte do seu tempo para a realização
	destes objetivos.</para>
      
      <para>A principal razão pela qual o sistema de
	<literal>ports</literal> precisa de manutenção
	é trazer os melhores e mais recentes softwares de
	terceiros para a comunidade &os;.  Um desafio adicional
	é manter os <literal>ports</literal> individuais
	trabalhando com o <literal>framework</literal> da
	Coleção de <literal>Ports</literal> a medida que
	ele evolui.</para>

      <para>Como mantenedor, você vai precisar gerenciar os
	seguintes desafios:</para>

      <itemizedlist>
	<listitem>
	  <formalpara>
	    <title>Novas versões de software e
	      atualizações.</title>

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

	<listitem>
	  <formalpara>
	    <title>Alterações em 
	      dependências.</title>

	    <para>Se forem feitas mudanças significativas nas
	      dependências de seu <literal>port</literal>, ele
	      pode precisar ser atualizado para que continue a
	      funcionar corretamente.</para>
	  </formalpara>
	</listitem>

	<listitem>
	  <formalpara>
	    <title>Alterações que afetam
	    <literal>ports</literal> que dependem do seu.</title>

	    <para>Se outros <literal>ports</literal> dependem de um
	      <literal>port</literal> que você mantém,
	      alterações em seu <literal>port</literal>
	      podem demandar coordenação com outros
	      mantenedores.</para>
	  </formalpara>
	</listitem>

	<listitem>
	  <formalpara>
	    <title>Interação com outros usuários,
	      mantenedores e desenvolvedores.</title>

	    <para>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 <literal>ports</literal> que sejam especificos 
	      ao &os;.</para>
	  </formalpara>
	</listitem>

	<listitem>
	  <formalpara>
	    <title>Caça aos bugs.</title>

	    <para>Um <literal>port</literal> 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 <literal>port</literal> para
	      identificar problemas antes que eles cheguem na
	      Coleção de <literal>Ports</literal>
	      é ainda melhor.</para>
	  </formalpara>
	</listitem>

	<listitem>
	  <formalpara>
	    <title>Alterações na política e na
	      infra-estrutura de <literal>ports</literal>.</title>

	    <para>Ocasionalmente, os sistemas que são 
	      utilizados para compilar os <literal>ports</literal> 
	      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 <literal>ports</literal> serem afetados e
	      precisarem de atualização.</para>
	  </formalpara>
	</listitem>

	<listitem>
	  <formalpara>
	    <title>Alterações no sistema base.</title>

	    <para>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
	      <literal>port</literal>.</para> 
	  </formalpara>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Responsabilidades de um Mantenedor</title>

      <sect3>
	<title>Mantenha seus <literal>ports</literal> 
	  atualizados</title>

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

	<para>Esta é uma visão geral.  Maiores
	  informações sobre o processo de
	  atualização de um <literal>port</literal>
	  estão disponíveis no 
	  <ulink url="&url.books.porters-handbook;">
	  Porter's Handbook</ulink>.</para>

	<procedure>
	  <step>
	    <title>Fique atentendo para as 
	      atualizações</title>

	    <para>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
	      <literal>port</literal>.  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 <literal>port</literal> 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.</para>
	    
	    <para>Você também pode receber um email
	      automático do <literal>sistema de
	      verificação de ports do &os;</literal>
	      informando que uma nova versão do seu
	      <literal>port's distfile</literal> está
	      disponível.  Maiores informações
	      sobre este sistema (incluindo a de como parar emails
	      futuros) serão fornecidas na mensagem.</para>
	  </step>

	  <step>
	    <title>Incorpore as alterações</title>

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

	  <step>
	    <title>Revisão e teste</title>

	    <para>Examine cuidadosamente e teste as suas
	      alterações:</para>

	    <itemizedlist>
	      <listitem>
		<para>Compile, instale e teste o seu
		  <literal>port</literal> no maior número
		  possível de plataformas e arquiteturas.
		  É comum que um <literal>port</literal>
		  funcione em um <literal>branch</literal> ou
		  plataforma e falhe em outra.</para>
	      </listitem>

	      <listitem>
		<para>Certifique-se de que as dependências do
		  seu <literal>port</literal> estão completas.
		  A melhor forma de fazer isto é instalar a sua
		  própria <literal>ports</literal> 
		  <application>tinderbox</application>.  Consulte a
		  seção sobre <link
		  linkend="resources">recursos</link> para maiores
		  informações.</para>
	      </listitem>

	      <listitem> 
		<para>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.</para> 
	      </listitem>

	      <listitem>
		<para>Verifique o seu <literal>port</literal>
		  utilizando o &man.portlint.1; como um guia.
		  Consulte a seção sobre <link
		  linkend="resources">recursos</link> para
		  informações importantes sobre o uso do
		  <application>portlint</application>.</para>
	      </listitem>

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

	  <step>
	    <title>Envie as alterações</title>

	    <para>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
	      <ulink url="&url.articles.problem-reports;">Escrevendo
	      Relatórios de Problema para o FreeBSD</ulink>
	      para maiores informações sobre como
	      escrever um bom PR.</para>

	    <note>
	      <para>Por favor, não envie um arquivo
		&man.shar.1; com o <literal>port</literal> inteiro.
		Em vez disso, utilize &man.diff.1;
		<literal>-ruN</literal>.  Desta forma, os
		<literal>committers</literal> podem ver com muito mais
		facilidade e precisão quais são as
		mudanças que estão sendo feitas.  A
		seção <ulink
		url="&url.books.porters-handbook;/port-upgrading.html">Atualizações</ulink>
		do <literal>Porter's Handbook</literal> tem maiores
		informações.</para>
	    </note>
	  </step>

	  <step>
	    <title>Aguarde</title>

	    <para>Em algum momento um <literal>committer</literal> vai
	      cuidar do seu PR.  Isto pode demorar alguns minutos, ou
	      pode levar semanas &mdash; desta forma, por favor, seja
	      paciente.</para>
	  </step>

	  <step>
	    <title>Dê feedbacks</title>

	    <para>Se um <literal>committer</literal> 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.</para>
	  </step>

	  <step>
	    <title>E finalmente...</title>

	    <para>As suas alterações serão
	      aceitas e o seu <literal>port</literal> estará
	      atualizado.  O PR será fechado pelo
	      <literal>committer</literal>.  E é isso!</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Assegure que os seus <literal>ports</literal> continuem
	  compilando corretamente.</title>

	<para>Esta seção é sobre descobrir e
	  corrigir problemas que impeçam os seus
	  <literal>ports</literal> de compilar corretamente.</para>
	
	<para>O funcionamendo da <literal>Coleção de
	  Ports</literal> é garantido pelo &os; apenas no ramo
	  <literal>-STABLE</literal> do sistema.   Você deve
	  estar executando o <literal>8-STABLE</literal> ou o
	  <literal>9-STABLE</literal>, preferencialmente o
	  último.  Em teoria, você deve ser capaz de
	  usá-lo com a última <literal>release</literal>
	  de cada ramo estável (uma vez que as
	  <literal>ABIs</literal> não deveriam mudar) mas se
	  você puder executar o ramo <literal>-STABLE</literal>,
	  isto será ainda melhor.</para>

	<para>Uma vez que a maioria das instalações do
	  FreeBSD rodam em maquinas PC compatíveis (como
	  é denominada a arquitetura <literal>i386</literal>),
	  nós esperamos que você mantenha os seus
	  <literal>ports</literal> funcionando nesta arquitetura.
	  Nós preferimos que os <literal>ports</literal>
	  também funcionem de forma nativa na arquitetura
	  <literal>amd64</literal>.  É totalmente justo que
	  você peça ajuda se você não
	  possuir uma destas máquinas.</para>
	
	<note>
	  <para>As falhas mais usuais na compilação para
	    máquinas não-<literal>i386</literal> ocorrem
	    porque o programador original assumiu, por exemplo, que os
	    ponteiros são do tipo <literal>int</literal>, ou
	    então que uma versão antiga e relativamente
	    mais frouxa do compilador <application>gcc</application>
	    está sendo utilizada.  Cada vez mais, os autores de
	    aplicações estão retrabalhando seu
	    código para remover estes pressupostos &mdash; mas
	    se o autor não estiver mantendo o código 
	    de forma ativa, você pode precisar fazer isto
	    você mesmo.</para>
	</note>

	<para>Estas são as tarefas que precisam ser executadas
	  para garantir o seu <literal>port</literal> pode ser
	  compilado:</para>
	
	<procedure>
	  <step>
	    <title>Esteja atento para falhas de
	      compilação</title>

	    <para>Verifique regularmente o cluster de
	      compilação automatizada de 
	      <literal>ports</literal>, o <ulink
	      url="http://pointyhat.FreeBSD.org">pointyhat</ulink>,  e
	      o <ulink url="http://www.portscout.org">scanner de
	      arquivos de distribuição</ulink> para ver
	      se algum dos <literal>ports</literal> que você 
	      mantém está falhando na 
	      compilação ou no download do 
	      código fonte (veja a seção sobre 
	      <link linkend="resources">recursos</link> 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.</para>
	  </step>

	  <step>
	    <title>Colete informações</title>

	    <para>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:</para>
	    
	    <itemizedlist>
	      <listitem>
		<para>Logs de compilação</para>
	      </listitem>

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

	      <listitem>
		<para>A lista de aplicativos instalados em seus
		  sistemas, como mostrada pelo &man.pkg.info.1;</para>
	      </listitem>

	      <listitem>
		<para>A versão do &os; que eles estão
		  utilizando, como mostrada pelo 
		  &man.uname.1;<command> -a</command></para>
	      </listitem>

	      <listitem>
		<para>Quando a sua Coleção de 
		  <literal>Ports</literal> foi atualizada pela
		  última vez</para>
	      </listitem>

	      <listitem>
		<para>Quando o seu arquivo <filename>INDEX</filename>
		  foi atualizado pela última vez</para>
	      </listitem>
	    </itemizedlist>
	  </step>

	  <step>
	    <title>Investigue e encontre uma
	      solução</title>

	    <para>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.</para>
	  </step>

	  <step>
	    <title>Envie as alterações</title>

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

	  <step>
	    <title>Envie <literal>patches</literal> para os
	      desenvolvedores do software</title>

	    <para>Em alguns casos você irá precisar 
	      modificar o software do seu <literal>port</literal> para
	      que ele execute no &os;.  Alguns (mas não todos)
	      desenvolvedores irão aceitar incorporar tais
	      <literal>patches</literal> 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
	      <literal>patch</literal> aplicável aos
	      desenvolvedores do software como uma cortesia.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>

	<title>Investigue os relatórios de bugs e os PRs
	  relacionados ao seu <literal>port</literal></title>

	<para>Esta seção é sobre a descoberta 
	  e correção de bugs.</para>

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

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

	<procedure>
	  <step>
	    <title>Responda os relatórios de bugs</title>

	    <para>Bugs podem ser reportados para você por 
	      meio de email através do <ulink
	      url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">Banco
	      de Dados de Relatórios de Problema GNATS</ulink>.
	      Bugs também podem ser reportados diretamente
	      à você pelos usuários.</para>

	    <para>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.</para>
	    
	    <para>Se você não responder neste prazo de 14
	      dias, qualquer <literal>committer</literal>
	      poderá realizar o <literal>commit</literal> do PR
	      ao qual você não respondeu baseado na regra
	      de <literal>maintainer-timeout</literal>.</para>
	  </step>

	  <step>
	    <title>Colete informações</title>

	    <para>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.</para>
	    
	    <para>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:</para>
	    
	    <itemizedlist>
	      <listitem>
		<para>Uma descrição detalhada das suas
		  ações, comportamento esperado para o
		  programa e o seu comportamento atual</para>
	      </listitem>

	      <listitem>
		<para>Cópia dos dados que desencadearam o
		  bug</para>
	      </listitem>

	      <listitem>
		<para>Informação sobre o seu ambiente de
		  compilação e execução
		  &mdash; como, por exemplo, a lista dos aplicativos
		  instalados e a saída do &man.env.1;</para>
	      </listitem>

	      <listitem>
		<para>Dumps de memória</para>
	      </listitem>

	      <listitem>
		<para>Rastreamento de pilhas</para>
	      </listitem>
	    </itemizedlist>
	  </step>

	  <step>
	    <title>Elimine os relatórios incorretos</title>

	    <para>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 <literal>patch</literal> ao seu
	      <literal>port</literal>, para que a
	      correção seja disponibilizada antes do
	      release da nova versão oficial por parte do
	      desenvolvedor.</para>
	  </step>

	  <step>
	    <title>Encontre uma solução</title>

	    <para>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!</para>
	  </step>

	  <step>
	    <title>Envie ou aprove as alterações</title>

	    <para>Assim como ocorre na atualização de um
	      <literal>port</literal>, 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.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Forneça suporte</title>

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

	<para>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
	  <literal>RPM</literal> não está atualizado ou
	  como eles podem fazer o software executar no Linux XYZ.
	  Aproveite a oportunidade para informar que o seu
	  <literal>port</literal> está atualizado (se ele
	  estiver, é claro) e sugira que eles testem o
	  &os;.</para>
	
	<para>À 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:</para>
	<itemizedlist>
	  <listitem>
	    <para>Submeter um PR ou enviar um <literal>patch</literal>
	      para atualizar o seu <literal>port</literal>,</para>
	  </listitem>

	  <listitem>
	    <para>investigar e talvez disponibilizar uma
	      correção para um PT, ou</para>
	  </listitem>

	  <listitem>
	    <para>de outra forma, submeter mudanças para o seu 
	      <literal>port</literal>.</para>
	  </listitem>
	</itemizedlist>

	<para>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.</para>
	
	<para>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
	  <!-- smiley -->:-).</para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="fix-broken">
    <title>Localizando e corrigindo um <literal>port</literal>
      quebrado.</title>

    <para>Existem dois lugares muito bons nos quais você pode
      encontrar <literal>ports</literal> que precisam de alguma
      atenção.</para>

    <para>Você pode utilizar a <ulink
      url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">interface
      web</ulink> do banco de dados dos Relatórios de Problema
      para pesquisar e visualizar os PRs não resolvidos.  A
      maioria dos PRs da categoria <literal>ports</literal> 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
      <literal>sw-bug</literal> é um bom ponto de
      partida).</para>
    
    <para>O outro lugar é o <ulink
      url="http://portsmon.FreeBSD.org/">Sistema de
      Monitoração de <literal>Ports</literal> do
      &os;</ulink>.  Em especial, procure por <literal>ports</literal>
      sem manutenção e com erros de
      compilação e por <literal>ports</literal> que
      estejam marcados como <makevar>BROKEN</makevar> (quebrados).
      É OK enviar alterações para um
      <literal>port</literal> que está sendo mantido, mas
      lembre-se de consultar primeiro o mantenedor para o caso dele
      já estar trabalhando na solução do
      problema.</para>
    
    <para>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.</para>
  </sect1>

  <sect1 id="mortal-coil">
    <title>Saber quando parar</title>

    <para>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 <literal>ports</literal>.  Tudo bem!  Por favor, 
      nos avise se você não estiver mais utilizando um
      <literal>port</literal>, 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
      <literal>ports</literal> sem ter que aguardar pela sua resposta.
      Lembre-se, o &os; é um projeto voluntário, se 
      manter um <literal>port</literal> não é mais 
      divertido, provavelmente está na hora de deixar alguma 
      outra pessoa fazê-lo.</para>
    
    <para>De qualquer forma, a Equipe de Gerenciamento do
      <literal>Ports</literal> (<literal>portmgr</literal>) se reserva
      o direito de revogar a sua condição de mantenedor
      de um <literal>port</literal> 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.</para>
  </sect1>

  <sect1 id="resources">
    <title>Recursos para mantenedores de <literal>ports</literal> e 
      colaboradores</title>

    <para>O <ulink url="&url.books.porters-handbook;">Porter's
	Handbook</ulink> é o seu guia de mochila para o sistema
	de <literal>ports</literal>.  Mantenha ele sempre a
	mão!</para>

    <para>O artigo <ulink url="&url.articles.problem-reports;">Escrevendo
      Relatórios de Problemas para o FreeBSD</ulink> 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
      <literal>ports</literal>.  Ao seguir as
      recomendações deste artigo você irá
      nos ajudar a reduzir o tempo necessário para processar o
      seu PR.</para>
    
    <para>O <ulink
	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
	Banco de Dados de Relatórios de Problemas</ulink>.</para>

    <para>O <ulink url="http://pointyhat.FreeBSD.org/">Pointyhat</ulink>
      &eacute o cluster de compilação do sistema de
      <literal>ports</literal>.  Você pode utilizar o Pointyhat
      para  verificar os logs de compilação de um
      <literal>port</literal> em todas as arquiteturas e releases
      principais.</para>
    
    <para>O <ulink url="http://portsmon.FreeBSD.org/">Sistema de
      Monitoração de Ports do &os;</ulink> pode lhe
      mostrar informações de referência cruzada
      sobre um <literal>port</literal> 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
      <literal>ports</literal> quebrados e sem
      manutenção os quais precisam ser 
      corrigidos.</para>
    
    <para>O <ulink url="http://www.portscout.org">Scanner de Arquivos 
      de Distribuição</ulink> da Coleção 
      de Ports do FreeBSD pode lhe mostrar <literal>ports</literal> 
      para os quais não é possível fazer o 
      download do código fonte.  Você pode 
      utilizá-lo nos seus próprios 
      <literal>ports</literal> ou usá-lo 
      para encontrar <literal>ports</literal> que precisam ter o seu
      <makevar>MASTER_SITES</makevar> atualizado.</para>
    
    <para>O <literal>ports</literal> 
      <application>tinderbox</application>
      é a forma mais completa de testar um
      <literal>port</literal> 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
      <filename>ports/ports-mgmt/tinderbox</filename>.  Você
      irá encontrar maiores informações na <ulink
      url="http://tinderbox.marcuscom.com/">Home page do marcuscom
      sobre o tinderbox</ulink>.</para>
    
    <para>O &man.portlint.1; é um aplicativo o qual pode ser
      utilizado para verificar se o seu <literal>port</literal> esta
      em conformidade com as muitas e importantes diretrizes
      funcionais e de estilo que se aplicam a um
      <literal>port</literal>.  O <application>portlint</application>
      é um aplicação heurística simples,
      de forma que você deve usá-lo <emphasis>apenas como
      um guia</emphasis>.  Se o <application>portlint</application>
      sugerir uma alteração que lhe parece ser
      irracional, consulte o <ulink
      url="&url.books.porters-handbook;">Porter's Handbook</ulink> ou
      peça orientação usando os canais
      apropriados.</para>
    
    <para>A &a.ports; destina-se a discussão de assuntos gerais
      relacionados ao sistema de <literal>ports</literal>.  Ela
      é um bom lugar para se pedir ajuda.  Você pode se
      <ulink
      url="http://lists.freebsd.org/mailman/listinfo">inscrever, ou
      ler e consultar o histórico de mensagens da
      lista</ulink>.  A leitura do histórico da &a.ports-bugs;
      e da &a.cvs-ports; também pode ser interessante.</para>
  </sect1>
</article>