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:
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: |
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. |
Differential Revision: | A URL completa da revisão do Phabricator. Esta linha deve ser a última linha . Por exemplo: https://reviews.freebsd.org/D1708 . |
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>
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
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.
Efetuando o commit de códigos baseados no trabalho feito no projeto OpenBSD.
... Obtained from: OpenBSD
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
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>.