8. Mensagens de Log de Commit

Esta seção contém algumas sugestões e tradições de como os logs de commit são formatados.

Além de incluir uma mensagem informativa com cada commit, algumas informações adicionais podem ser necessárias.

Essas informações consistem em uma ou mais linhas contendo a palavra-chave ou frase, dois-pontos, guias para formatação e, em seguida, as informações adicionais.

As palavras ou frases-chave são:

PR:O relatório do problema (se houver) que é afetado (normalmente, por estar fechado) por este commit. Vários PRs podem ser especificados em uma linha, separados por vírgulas ou espaços.
Submitted by:

O nome e o endereço de e-mail da pessoa que enviou a correção; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD.

Se o requisitante for o mantenedor do port que está sendo atualizado pelo commit, inclua "(maintainer)" após o endereço de e-mail.

Evite ofuscar o endereço de e-mail do remetente, pois isso adiciona trabalho adicional ao pesquisar os registros.

Reviewed by:O nome e o endereço de e-mail da pessoa ou pessoas que revisaram a alteração; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD. Se um patch foi submetido a uma lista de discussão para revisão e a revisão foi favorável, basta incluir o nome da lista.
Approved by:

O nome e endereço de e-mail da pessoa ou pessoas que aprovaram a alteração; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD. É costume obter aprovação prévia para um commit se for para uma área da árvore na qual você normalmente não faz commit. Além disso, durante a preparação para uma nova versão, todos os commits devem ser aprovados pela equipe de engenharia de release.

Enquanto estiver sob orientação, obtenha aprovação do mentor antes do commit. Digite o nome de usuário do mentor neste campo e adicione uma nota de que ele é um mentor:

Approved by: username-of-mentor (mentor)

Se uma equipe aprovou esses commits, inclua o nome da equipe seguido do nome de usuário do aprovador entre parênteses. Por exemplo:

Approved by: re (username)
Obtained from:O nome do projeto (se houver) do qual o código foi obtido. Não use esta linha para o nome de uma pessoa individual.
Sponsored by:Organizações patrocinadoras dessa mudança, se houver. Separe várias organizações com vírgulas. Se apenas uma parte do trabalho foi patrocinada, ou diferentes montantes de patrocínio foram fornecidos a diferentes autores, por favor, forneça os devidos créditos entre parênteses após cada nome de patrocinador. Por exemplo, Example.com (alice, refatoração de código), Wormulon (bob), Momcorp (cindy) mostra que Alice foi patrocinada pela Example.com para refatoração de código, enquanto Wormulon patrocinou o trabalho de Bob e a Momcorp patrocinou o trabalho de Cindy. Outros autores não foram patrocinados ou optaram por não listar o patrocínio.
MFC after:Para receber um lembrete por e-mail para o MFC em uma data posterior, especifique o número de dias, semanas ou meses após os quais um MFC está planejado.
MFC to:Se o commit deve ser mesclado em um subconjunto de branches estáveis, especifique os nomes das branchs.
MFC with:Se o commit deve ser mesclado junto com um commit anterior em um único MFC (por exemplo, onde o commit corrige um bug da alteração anterior), especifique o número de revisão correspondente.
Relnotes:Se a alteração for candidata a inclusão nas notas de lançamento da próxima versão da branch, defina como yes.
Security:Se a alteração estiver relacionada a uma vulnerabilidade de segurança ou exposição de segurança, inclua uma ou mais referências ou uma descrição do problema. Se possível, inclua um URL VuXML ou um ID CVE.
Evento:Descrição para o evento em que essa confirmação foi feita. Se este for um evento recorrente, adicione o ano ou até mesmo o mês. Por exemplo, isso pode ser FooBSDcon 2019 . A idéia por trás dessa linha é dar reconhecimento a conferências, reuniões e outros tipos de reuniões e mostrar que elas são úteis. Por favor, não use a linha Patrocinado por: para isso, pois isso significa que as organizações patrocinam determinados recursos ou desenvolvedores que trabalham neles.
Differential Revision:A URL completa da revisão do Phabricator. Esta linha deve ser a última linha . Por exemplo: https://reviews.freebsd.org/D1708.
Exemplo 2. Commit Log para um commit baseado em um PR

O commit é baseado em um patch de um PR enviado por John Smith. Os campos da mensagem de commit PR e Submitted by são preenchidos.

...

	    PR:                    12345
	    Submitted by:	   John Smith <John.Smith@example.com>

Exemplo 3. Commit log de um commit que precisa de revisão

O sistema de memória virtual está sendo alterado. Depois de enviar os patches para a lista de discussão apropriada (neste caso, freebsd-arch) e as mudanças foram aprovadas.

...

	    Reviewed by:       -arch

Exemplo 4. Commit log de um commit que precisa de aprovação

Commit um port, depois de trabalhar com o MAINTAINER, que disse para ir em frente e executar o commit.

...

	    Approved by:	    abc (maintainer)

No qual o abc é o nome da conta da pessoa que aprovou.


Exemplo 5. Commit log de um commit que importa código do OpenBSD

Efetuando o commit de códigos baseados no trabalho feito no projeto OpenBSD.

...

	    Obtained from:      OpenBSD

Exemplo 6. Commit Log para uma mudança no FreeBSD-CURRENT com um commit planejado para o FreeBSD-STABLE para seguir em uma data posterior.

Efetuando o commit de códigos que serão mesclados do FreeBSD-CURRENT na branch do FreeBSD-STABLE após duas semanas.

...

MFC after:      2 weeks

Onde 2 é o número de dias, semanas ou meses após o qual um MFC é planejado. A opção weeks pode ser day, dias, semana, semanas, mês, meses.


Muitas vezes é necessário combinar isso.

Considere a situação em que um usuário enviou um código contendo o PR do projeto NetBSD. Olhando para o PR, o desenvolvedor vê que não é uma área da árvore na qual eles normalmente trabalham, então eles têm a mudança revisada pela lista de discussão arch. Como a mudança é complexa, o desenvolvedor opta pelo MFC após um mês para permitir testes adequados.

A informação extra para incluir no commit seria algo como

Exemplo 7. Exemplo de log de commit combinado
PR:                 54321
Submitted by:       John Smith <John.Smith@example.com>
Reviewed by:        -arch
Obtained from:      NetBSD
MFC after:          1 month
Relnotes:           yes

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.