Contribuindo com o FreeBSD

Jordan Hubbard

Sam Lawrance

Mark Linimon

Nota Legal

FreeBSD is a registered trademark of the FreeBSD Foundation.

IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical and Electronics Engineers, Inc. in the United States.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol.

Resumo

Este artigo descreve maneiras diferentes sobre como um indivíduo ou organização pode contribuir com o Projeto FreeBSD.


Então você quer contribuir com o FreeBSD? Isso é ótimo! O FreeBSD depende das contribuições da sua base de usuários para sobreviver. Suas contribuições não são apenas apreciadas, elas são vitais para que o FreeBSD continue crescendo.

Um grande e crescente número de contribuidores internacionais, de uma grande variedade de idade e áreas de conhecimento técnico, desenvolvem o FreeBSD. Sempre existe mais trabalho a ser feito do que pessoas disponíveis para realizá-lo, e mais ajuda é sempre bem vinda.

Como um voluntário, o que você pode fazer só é limitado pelo que você quer fazer. Entretanto, o que lhe pedimos é que esteja ciente a respeito do que outros membros da comunidade FreeBSD esperará de você. Você pode querer levar isso em consideração antes de decidir se voluntariar.

O Projeto FreeBSD é responsável por um ambiente completo de sistema operacional, em vez de apenas um kernel ou alguns utilitários dispersos. Assim sendo, nossa lista TODO passa por uma grande variedade de tarefas: da documentação do sistema, testes de versão beta e apresentação, ao instalador do sistema e outros tipos altamente especializados de desenvolvimento do kernel. Pessoas de qualquer nível de conhecimento, em quase qualquer área, quase que certamente poderá ajudar no projeto.

Entidades comerciais engajadas em iniciativas relacionadas ao FreeBSD também são encorajadas a entrar em contato conosco. Você precisa de uma extensão especial para fazer seu produto funcionar? Você vai nos encontrar receptivos às suas solicitações, considerando que não sejam muito estranhas. Está trabalhando em um produto de valor adicionado? Por favor nos informe! Podemos ser capazes de trabalhar cooperativamente em algum aspecto dele. O mundo do software livre está desafiando muitas premissas sobre como um software é desenvolvido, vendido e mantido, e nós pedimos que você pelo de uma segunda olhada.

1. O que é necessário

A lista de tarefas e sub-projetos a seguir representa algo como uma amálgama de várias listas de TODO e outras solicitações.

1.1. Tarefas em execução por não-programadores.

Muitas pessoas que estão envolvidas com o FreeBSD não são programadores. O Projeto inclui escritores de documentação, Web designers, e pessoas de suporte. Todas estas pessoas contribuem investindo tempo e sua vontade de aprender.

  1. Leia o FAQ e Handbook periodicamente. Se algo estiver explicado de forma pobre, ambígua, desatualizada ou incorreta, nos comunique. Melhor ainda, envie-nos uma versão ajustada (O formato Docbook não é difícil de aprender, mas não existem objeções em relação ao envio de material no formato ASCII).

  2. Ajude a traduzir a documentação do FreeBSD para a sua linguagem nativa. Se a documentação já existe na sua língua, você pode ajudar a traduzir documentos adicionais ou verificar se as traduções estão atualizadas e corretas. Primeiro dê uma olhada no FAQ de Traduções contido no Manual de Documentação do Projeto FreeBSD. Você não estará se comprometendo a traduzir toda a documentação do FreeBSD fazendo isto - como um voluntário, você pode fazer tantas quantas traduções desejar. Uma vez que alguém começa a traduzir, outros se unem ao esforço. Se você tem tempo ou energia para traduzir apenas uma parte da documentação, por favor traduza as instruções de instalação.

  3. Leia a lista de discussão para perguntas gerais sobre o FreeBSD ocasionalmente (ou regularmente se possível). Pode ser muito recompensador compartilhar a sua experiência e ajudar outras pessoas a resolverem seus problemas; Às vezes você poderá até aprender algo novo! Estes fóruns também podem ser uma fonte de ideias de coisas a serem melhoradas.

1.2. Tarefas em execução por programadores

A maioria das tarefas listadas aqui requerem um investimento considerável de tempo ou conhecimento profundo do kernel do FreeBSD; ou, ambos. Entretanto, também existem muitas tarefas úteis que são apropriadas para os "hackers de final de semana".

  1. Se você executa o FreeBSD-CURRENT e possui uma boa conexão com a Internet, existe uma máquina current.FreeBSD.org a qual compila uma release completa uma vez por dia - de vez em quando, tente instalar uma destas versões e informe quaisquer problemas no processo.

  2. Leia a Lista de discussão de relatórios de problemas do FreeBSD. Talvez exista um problema que você possa comentar construtivamente ou existam correções que você possa testar. Ou você pode até consertar um dos problemas por conta própria.

  3. Se você souber de qualquer problema que tenha sido corrigido com sucesso no -CURRENT e cuja correção não tenha sido aplicada ao -STABLE após um intervalo razoável de tempo (normalmente algumas semanas), envie ao committer um lembrete educado.

  4. Mova as contribuições de software para src/contrib na árvore do código fonte.

  5. Tenha certeza que o código disponível em src/contrib está atualizado.

  6. Compile o sistema (ou apenas uma parte dele) com um nível de debug extra habilitado e corrija a causa dos alertas encontrados.

  7. Corrija os alertas existentes para os ports que ainda fazem coisas ultrapassadas tais como utilizar gets() ou incluir malloc.h.

  8. Se você contribuiu com algum dos ports, e teve que fazer alguma mudança específica para o FreeBSD, envie suas correções de volta aos autores originais (isto tornará sua vida mais fácil quando eles lançarem a próxima versão).

  9. Consiga cópias de padrões formais tais como o POSIX®. Compare o comportamento do FreeBSD àquele requerido pelo padrão. Se o comportamento diferir, particularmente em pontos sutis ou obscuros da especificação, envie-nos um PR sobre ele. Se você for capaz, descubra como corrigi-lo e inclua um patch em seu PR. Se você acredita que o padrão está errado, peça ao comitê de padrões que considere a pergunta.

  10. Sugira novas tarefas para esta lista!

1.3. Trabalhe no banco de dados de PR (relatório de problemas)

A Lista de PRs do FreeBSD mostra todos os relatórios de problemas ativos no momento e os pedidos de melhoria que foram submetidos pelos usuários do FreeBSD. O banco de dados inclui tarefas para programadores e para não-programadores. Consulte os PRs abertos, e veja se algum deles é de seu interesse. Alguns deles podem ser tarefas muito simples que necessitam apenas que um par extra de olhos olhe para eles e confirme que a correção proposta funciona. Outros podem ser muito mais complexos, ou podem nem ter vindo com uma correção.

Comece com os PRs que ainda não foram atribuídos a ninguém. Se um PR estiver atribuído a outra pessoa, mas se parecer com algo que você possa cuidar, envie um e-mail para a pessoa encarregada do mesmo e pergunte se você pode trabalhar nele — ele pode já ter um patch pronto para ser testado, ou você pode discutir novas idéias com ele.

1.4. Tarefas em andamento relacionadas a coleção de Ports

A coleção de Ports é um trabalho permanente em andamento. Queremos fornecer aos nossos usuários um repositório de software de terceiros fácil de usar, atualizado e de alta qualidade. Precisamos que as pessoas doem parte de seu tempo e esforço para nos ajudar a alcançar esse objetivo.

Qualquer um pode se envolver e existem muitas maneiras diferentes de fazer isso. Contribuir para a coleção de ports é uma excelente maneira de ajudar "a devolver algo" ao projeto. Se você está procurando um papel contínuo ou um desafio divertido para um dia chuvoso, nós adoraríamos ter a sua ajuda!

Existem várias maneiras fáceis de contribuir para manter a árvore de ports atualizada e em boas condições de funcionamento:

1.5. Escolha um dos itens da “página de idéias”

A lista de projetos do FreeBSD e de idéias para voluntários também está disponível para as pessoas dispostas a contribuir com o projeto FreeBSD. Esta lista é atualizada regularmente e contém itens tanto para programadores e como para não programadores e traz ainda informações sobre cada projeto .

2. Como Contribuir

Contribuições para o sistema geralmente se enquadram em uma das 5 categorias seguintes:

2.1. Relatórios de Bugs e Comentários Gerais

Uma ideia ou sugestão técnica de interesse geral deverá ser enviada para a Lista de discussão de assuntos técnicos do FreeBSD. Da mesma forma, pessoas com este tipo de interesse (e tolerância para um alto volume de mensagens!) poderão assinar a Lista de discussão de assuntos técnicos do FreeBSD. Veja o Handbook do FreeBSD para mais informações sobre esta e outras listas.

Se você encontrar um bug ou estiver enviando uma mudança específica, por favor relate-o usando o relatório de envio de bug. Tente preencher cada campo com do relato de bug. A não ser que exceda 65KB, inclua qualquer correção diretamente no relatório. Se o patch é apropriado para ser aplicado na árvore do código fonte coloque [PATCH] no resumo do relatório. Ao incluir patches, não use copiar-e-colar, pois o copiar-e-colar transforma tabs em espaços e os torna inúteis. Quando os patches são muito maiores que 20KB, considere comprimi-los (por exemplo, com gzip(1) ou bzip2(1)) antes de fazer o envio.

Após preencher o relatório, você receberá a confirmação com o número de rastreamento. Guarde este número para que você possa nos atualizar com detalhes sobre do problema.

Veja também este artigo sobre como escrever bons relatórios de problemas.

2.2. Mudanças na Documentação

Mudanças na documentação são supervisionadas pela lista de documentação do projeto FreeBSD. Por favor veja o Manual do Projeto de Documentação do FreeBSD para instruções completas. Envie contribuições e mudanças (mesmo as pequenas são bem vindas!) utilizando o mesmo método de qualquer outro relatório de bug.

2.3. Mudanças no Código Fonte Existente

Um acréscimo ou mudança em um código fonte existe é um tema um pouco complicado e depende muito de como você está desatualizado com o estado atual do desenvolvimento do FreeBSD. Existe uma release especial do FreeBSD em andamento conhecida como "FreeBSD-CURRENT" que é disponibilizada de várias maneiras para conveniência dos desenvolvedores que trabalham ativamente no sistema. Veja o Handbook do FreeBSD para mais informação sobre como obter e usar o FreeBSD-CURRENT.

Trabalhar com versões antigas do código, infelizmente, muitas vezes significa que as suas alterações serão demasiadamente obsoletas ou muito divergentes para possibilitar uma fácil re-integração ao FreeBSD. As possibilidades de que isso ocorra podem ser minimizadas um pouco através da sua inscrição na lista de distribuição de comunicados oficiais do projeto FreeBSD e na lista de discussão do FreeBSD-CURRENT, nas quais as discussões sobre o estado atual do sistema ocorrem.

Supondo que você consiga obter acesso à uma versão razoavelmente atualizada do código fonte do sistema para basear as suas alterações, o próximo passo é produzir um conjunto de diffs para enviar aos mantenedores do FreeBSD. Isto é feito com o comando diff(1).

O formato preferido do diff(1) para o envio de um patch, é o formato de saída unificada gerado pelo comando diff -u.

% diff -u oldfile newfile

ou

% diff -u -r -N olddir newdir

deverá gerar um conjunto de diffs unificados para o arquivo de origem informado ou para a hierarquia de diretórios.

Consulte o manual do diff(1) para maiores informações.

Uma vez que você tenha o conjunto de diffs (os quais você pode testar com o comando patch(1)), você deve submetê-lo para inclusão no FreeBSD por meio de um relatório de bug. Você não deve enviar os diffs para a lista de discussão de assuntos técnicos do FreeBSD ou eles irão se perder! Agradecemos imensamente a sua submissão (este é um projeto voluntário!); Devido ao alto volume de trabalho, nós podemos não ser capazes de resolvê-lo imediatamente, mas ele permanecerá em nosso banco de dados até que o façamos. Marque a sua submissão incluindo a palavra [PATCH] na sinopse do relatório.

Se você achar adequado (por ex. você adicionou, deletou ou renomeou arquivos), agrupe as suas mudanças em um arquivo tar. Arquivos criados com o shar(1) também são bem vindos.

Se as suas mudanças são de uma natureza potencialmente sensível, por exemplo, se você não tiver certeza sobre os problemas de direitos autorais que regerão sua distribuição no futuro, envie-as para o Core Team core@FreeBSD.org ao invés de submetê-las por meio de um relatório de bug. O FreeBSD Core Team core@FreeBSD.org é formado por um grupo muito pequeno de pessoas as quais cuidam de muitas das tarefas diárias de administração do projeto FreeBSD. Observe que este grupo também é muito ocupado e portanto você só deve enviar um e-mail para eles se for realmente necessário.

Por favor, consulte os manuais intro(9) e style(9) para algumas informações sobre estilo de codificação. Nós apreciaríamos se você estivesse ao menos ciente destas informações antes de submeter o seu código.

2.4. Código novo ou pacotes de maior valor agregado

No caso de uma contribuição significativa de um trabalho de grande porte, ou a adição de uma nova característica importante ao FreeBSD, torna-se quase sempre necessário que se envie as alterações em um arquivo tar ou então que se faça o upload das mesmas para um servidor WWW ou FTP para que as outras pessoas possam acessá-las. Se você não possui acesso a um servidor WWW ou FTP, pergunte em uma lista de discussão apropriada do FreeBSD se alguém pode hospedar essas alterações para você.

Quando se trabalha com grandes quantidades de código, o sensível assunto de direitos autorais invariavelmente vem a tona. O Projeto FreeBSD prefere licenças de software livre tais como BSD ou ISC. Licenças copyleft, como a GPLv2, às vezes são permitidas. A lista completa pode ser encontrada na página sobre a política de licenciamento do core team.

2.5. Dinheiro ou Hardware

Nós ficamos sempre muito felizes em aceitar doações para agregar a causa do Projeto FreeBSD, em um esforço voluntário como o nosso, um pouco pode significar muito! Doações de hardware também são muito importantes para expandir a nossa lista de periféricos suportados, uma vez que normalmente não temos recursos para comprar estes itens nós mesmos.

2.5.1. Doando Dinheiro

A Fundação FreeBSD é uma entidade sem fins lucrativos e isenta de impostos, estabelecida com o objetivo de promover os objetivos do Projeto FreeBSD. Como uma entidade 501(c)3, a fundação é isenta de recolher as taxas do governo federal, bem como as do Estado do Colorado. As doações para uma entidade isenta de impostos são frequentemente dedutíveis dos impostos federais.

As doações podem ser enviadas através de cheques para:

The FreeBSD Foundation
P.O. Box 20247,
Boulder,
CO 80308
USA

A Fundação FreeBSD é agora capaz de receber doações através da web com o PayPal. Para fazer uma doação, por favor visite o website a Fundação.

Maiores informações sobre a Fundação FreeBSD podem ser obtidas no documento A Fundação FreeBSD - Uma introdução. Para contatar a Fundação por e-mail, escreva para info@FreeBSDFoundation.org.

2.5.2. Doando Hardware

O projeto FreeBSD aceita alegremente doações de hardware para os quais pode encontrar bom uso. Se você estiver interessado em doar componentes de hardware, por favor contate o Escritório de Relacionamento com Doadores.

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 O desafio para os mantenedores de um port. 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 mantenedores de ports e contribuidores 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 mantenedores de ports e contribuidores 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.

    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.

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 int-s, 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 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.

4. Começando em outras áreas

Procurando por algo interessante para começar, e que não foi mencionado em outras partes deste artigo? O Projeto FreeBSD tem várias páginas Wiki contendo áreas nas quais novos colaboradores podem ter ideias sobre como começar.

A página Júnior Jobs tem uma lista de projetos que podem ser de interesse para pessoas que estão apenas começando no FreeBSD, e querem trabalhar em coisas interessantes para molhar os pés.

A Página de Idéias contém várias coisas "legais" ou "interessantes" para se trabalhar no Projeto.