Processo de Relatório de Status do FreeBSD

Não assuma que a pessoa que lerá o relatório conhece o seu projeto.

Os relatórios de status possuem uma ampla distribuição. Eles são frequentemente um dos principais itens de notícias no site do FreeBSD e são uma das primeiras coisas que as pessoas vão ler se quiserem saber um pouco sobre o que é o FreeBSD. Considere este exemplo:

Alguém que esteja lendo isso, se estiver familiarizado com as páginas do manual UNIX, saberá que abc(4) é algum tipo de dispositivo. Mas por que o leitor deveria se importar? Que tipo de dispositivo é esse? Compare com esta versão:

Agora o leitor sabe que abc é um driver de interface de rede. Mesmo que eles não usem nenhum produto Yoyodyne, você comunicou que o suporte do FreeBSD para dispositivos de rede está melhorando.

Os relatórios de status não são apenas para informar a todos que coisas foram feitas, eles também precisam explicar por que elas foram feitas.

Continuando com o exemplo anterior. Por que é interessante que agora suportemos os cartões Yoyodyne Frobnicator? Eles são amplamente utilizados? São usados em um dispositivo popular específico? Eles são usados em uma área específica em que o FreeBSD tem (ou gostaria de ter) presença? Eles são os cartões de rede mais rápidos do planeta? Os relatórios de status frequentemente dizem coisas como essas:

E então eles param. Talvez o leitor seja um ávido fã da Cyberdyne e saiba quais novos recursos emocionantes o T800 traz. Isso é improvável. É muito mais provável que eles tenham ouvido vagamente sobre o que você importou (especialmente na árvore de ports: lembre-se de que existem mais de 30.000 outras coisas lá também…​). Liste alguns dos novos recursos ou correções de bugs. Diga-lhes por que é uma boa coisa que tenhamos a nova versão.

Não recicle os mesmos itens do relatório de status.

Tenha em mente que os relatórios de status não são apenas relatórios sobre o status do projeto, são relatórios sobre a mudança de status do projeto. Se houver um projeto em andamento, gaste algumas frases apresentando-o, mas depois gaste o restante do relatório falando sobre o novo trabalho. Qual progresso foi feito desde o último relatório? O que ainda falta ser feito? Quando é provável que esteja concluído (ou, se "concluído" não se aplica realmente, quando é provável que esteja pronto para uso mais amplo, para testes, para implementação em produção e assim por diante)?

Não se esqueça dos seus patrocinadores.

Se você ou seu projeto receberam patrocínio ou bolsa de estudo de alguém ou você já estava trabalhando como contratado ou funcionário de uma empresa, por favor inclua essa informação. Patrocinadores sempre apreciam quando são agradecidos pelo seu financiamento, mas também é benéfico para eles mostrarem que estão apoiando ativamente o Projeto dessa maneira. Por último, mas não menos importante, isso ajuda o FreeBSD a aprender mais sobre seus importantes consumidores.

Se você precisa de ajuda, deixe isso explícito!

Precisa de ajuda com algo? Existem tarefas que outras pessoas podem fazer? Existem duas maneiras de usar a parte de tarefas pendentes do relatório de status: para solicitar ajuda ou para dar uma visão geral rápida da quantidade de trabalho restante. Se já houver pessoas suficientes trabalhando no projeto, ou se ele estiver em um estado em que adicionar mais pessoas não aceleraria o processo, então é melhor usar a segunda opção. Fale sobre algumas das grandes tarefas em andamento e talvez indique quem está focado em cada uma delas.

Enumere as tarefas, com detalhes suficientes para que as pessoas saibam se são capazes de realizá-las, e convide-as a entrar em contato.

Os seguintes métodos estão disponíveis para você enviar os seus relatórios:

Um modelo de relatório em AsciiDoc está disponível aqui.

Os relatórios são sempre aceitos pela equipe de status, mas o principal processo de coleta ocorre no último mês de cada trimestre, ou seja, em março, junho, setembro e dezembro. Chamadas explícitas para relatórios de status serão enviadas nesses meses. Os meses de janeiro, abril, julho e outubro são dedicados a reunir os relatórios enviados durante o trimestre anterior; isso pode incluir aguardar por envios tardios. A publicação dos relatórios de status é feita durante os mesmos meses assim que os relatórios estiverem prontos.

Todas as submissões de relatórios podem ter o prazo estendido enviando um email para a equipe de status até o prazo estendido, que é de 8 dias após o final do trimestre. As entradas da equipe de gerenciamento do ports por padrão utilizam o prazo estendido, devido à sobreposição entre os relatórios de status e os branchs trimestrais do ports.

A revisão dos relatórios enviados por pessoas que não fazem parte da equipe de status deve estar essencialmente concluída até meados de janeiro/abril/julho/outubro (deadline para a revisão de terceiros). Ou seja, exceto por erros de digitação ou outra revisão leve, a equipe de status deve ser capaz de começar a montar os envios logo após o dia 15. Observe que isso não é uma restrição completa e a equipe de status ainda pode aceitar revisões após essa data.

As chamadas para relatórios de status são enviadas para os seguintes destinatários:

A maneira mais fácil de enviar chamadas para relatórios de status é usar o script Perl sendcalls existente no diretório tools/sendcalls do repositório doc no git. O script envia automaticamente chamadas para todos os destinatários pretendidos. Ele também pode ser usado por meio de uma tarefa agendada no cron, por exemplo:

Pode ser que valha a pena fazer uma chamada para relatórios nos fóruns, como foi feito no passado.

Os relatórios enviados são revisados e mesclados na subpasta apropriada de doc/website/content/en/status/ assim que são recebidos. Enquanto os relatórios estão sendo atualizados, pessoas fora da equipe de status também podem revisar as entradas individuais e propor correções.

Geralmente, o último passo no processo de revisão de conteúdo é escrever a introdução em um arquivo chamado intro.adoc: uma boa introdução só pode ser escrita depois que todos os relatórios foram coletados. Se possível, é uma boa ideia pedir a diferentes pessoas para escrever a introdução para adicionar variedade: pessoas diferentes trarão diferentes pontos de vista e ajudarão a manter o texto interessante.

Assim que todos os relatórios e a introdução estiverem prontos, o arquivo _index.adoc precisa ser criado: este é o arquivo no qual os relatórios são distribuídos nas várias categorias e classificados.

Quando todos os arquivos do relatório de status estiverem prontos, é hora de publicá-lo.

Primeiramente, o arquivo doc/website/content/en/status/_index.adoc é editado: a próxima data de entrega é atualizada e um link para o novo relatório é adicionado. A alteração é, então, enviada para o repositório e a equipe de status verifica se tudo está funcionando conforme o esperado.

Em seguida, é adicionada uma entrada de notícias na página principal do site em doc/website/data/en/news/news.toml.

Aqui está um exemplo para uma entrada de notícias:

Assim que a versão HTML do relatório estiver compilada e online, o w3m(1) é usado fazer o dump do website em formato de texto simples, por exemplo:

O w3m(1) possui suporte completo para unicode. O -dump simplesmente produz uma saída de texto da renderização do código HTML, que pode então ter alguns elementos recortados, enquanto o -cols garante que tudo seja enquadrado em 80 colunas.

Um link para o relatório gerado é adicionado entre a introdução e a primeira entrada.

O relatório está finalmente pronto para ser enviado, alterando o posicionamento (o relatório deve ser inserido) e garantindo que ele esteja codificado em UTF-8.

Duas mensagens de e-mail são enviadas, ambas com o assunto no formato Relatório de Status do FreeBSD - <Primeiro/Segundo/Terceiro/Quarto> Trimestre de <ano>: