| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
KVM x86 |
| 4 |
======= |
| 5 |
|
| 6 |
Prefácio |
| 7 |
-------- |
| 8 |
|
| 9 |
O KVM se esforça para ser uma comunidade acolhedora; as contribuições de |
| 10 |
recém-chegados são valorizadas e incentivadas. Por favor, não se sinta |
| 11 |
desanimado ou intimidado pela extensão deste documento e pelas muitas |
| 12 |
regras/diretrizes que ele contém. Todo mundo comete erros e todo mundo já foi um |
| 13 |
novato em algum momento. Desde que você faça um esforço honesto para seguir as |
| 14 |
diretrizes do KVM x86, seja receptivo ao feedback e aprenda com os erros que |
| 15 |
cometer, você será recebido de braços abertos, não com tochas e forquilhas. |
| 16 |
|
| 17 |
(TL;DR) |
| 18 |
-------- |
| 19 |
Testes são obrigatórios. Seja consistente com os estilos e padrões estabelecidos. |
| 20 |
|
| 21 |
Árvores |
| 22 |
------- |
| 23 |
O KVM x86 está atualmente em um período de transição: deixando de fazer parte da |
| 24 |
árvore principal do KVM para se tornar "apenas mais uma arquitetura KVM". Como tal, |
| 25 |
o KVM x86 está dividido entre a árvore principal do KVM, |
| 26 |
``git.kernel.org/pub/scm/virt/kvm/kvm.git``, e uma árvore específica para KVM x86, |
| 27 |
``github.com/kvm-x86/linux.git``. |
| 28 |
|
| 29 |
De modo geral, as correções (fixes) para o ciclo atual são aplicadas diretamente |
| 30 |
na árvore principal do KVM, enquanto todo o desenvolvimento para o próximo ciclo |
| 31 |
é roteado através da árvore do KVM x86. No caso improvável de uma correção para o |
| 32 |
ciclo atual ser roteada através da árvore do KVM x86, ela será aplicada à branch |
| 33 |
``fixes`` antes de seguir para a árvore principal do KVM. |
| 34 |
|
| 35 |
Note que espera-se que este período de transição dure bastante tempo, ou seja, |
| 36 |
será o status quo em um futuro próximo. |
| 37 |
|
| 38 |
Branches |
| 39 |
~~~~~~~~ |
| 40 |
A árvore do KVM x86 é organizada em múltiplas branches de tópicos (topic |
| 41 |
branches). O objetivo de usar branches de tópicos mais granulares é facilitar o |
| 42 |
acompanhamento de uma área específica de desenvolvimento e limitar os danos |
| 43 |
colaterais de erros humanos e/ou commits com bugs; por exemplo, descartar o |
| 44 |
commit HEAD de uma branch de tópico não tem impacto nos hashes SHA1 de outros |
| 45 |
commits em andamento, e a necessidade de rejeitar um pull request devido a bugs |
| 46 |
atrasa apenas aquela branch de tópico específica. |
| 47 |
|
| 48 |
Todas as branches de tópicos, exceto a ``next`` e a ``fixes``, são incorporadas |
| 49 |
na ``next`` via um "Cthulhu merge" conforme a necessidade, ou seja, sempre que |
| 50 |
uma branch de tópico é atualizada. Como resultado, force pushes para a branch |
| 51 |
``next`` são comuns. |
| 52 |
|
| 53 |
Ciclo de Vida |
| 54 |
~~~~~~~~~~~~~ |
| 55 |
As correções (fixes) destinadas ao lançamento atual, também conhecido como |
| 56 |
mainline, são normalmente aplicadas diretamente na árvore principal do KVM, ou |
| 57 |
seja, não passam pela árvore do KVM x86. |
| 58 |
|
| 59 |
As mudanças destinadas ao próximo lançamento são roteadas através da árvore do |
| 60 |
KVM x86. Pull requests (do KVM x86 para o KVM principal) são enviados para cada |
| 61 |
branch de tópico do KVM x86, normalmente na semana anterior à abertura da janela |
| 62 |
de merge por Linus, por exemplo, na semana seguinte ao rc7 para lançamentos |
| 63 |
"normais". Se tudo correr bem, as branches de tópicos são incorporadas ao pull |
| 64 |
request principal do KVM enviado durante a janela de merge de Linus. |
| 65 |
|
| 66 |
A árvore do KVM x86 não possui sua própria janela de merge oficial, mas há um |
| 67 |
"soft close" (fechamento flexível) por volta do rc5 para novos recursos, e um |
| 68 |
"soft close" por volta do rc6 para correções (para o próximo lançamento; veja |
| 69 |
acima para correções destinadas ao lançamento atual). |
| 70 |
|
| 71 |
Cronograma |
| 72 |
---------- |
| 73 |
As submissões são normalmente revisadas e aplicadas em ordem FIFO (primeiro a |
| 74 |
entrar, primeiro a sair), com alguma margem de manobra para o tamanho de uma |
| 75 |
série, patches que estão "cache hot", etc. Correções (fixes), especialmente para |
| 76 |
o lançamento atual e/ou árvores estáveis (stable trees), têm prioridade na fila. |
| 77 |
Patches que serão aceitos através de uma árvore não-KVM (mais frequentemente |
| 78 |
através da árvore "tip") e/ou que possuam outros "acks"/revisões também ganham |
| 79 |
certa prioridade. |
| 80 |
|
| 81 |
Note que a grande maioria das revisões é feita entre o rc1 e o rc6, |
| 82 |
aproximadamente. O período entre o rc6 e o próximo rc1 é usado para colocar |
| 83 |
outras tarefas em dia, ou seja, o "silêncio de rádio" durante este período não é |
| 84 |
incomum. |
| 85 |
|
| 86 |
Pings para obter uma atualização de status são bem-vindos, mas tenha em mente o |
| 87 |
tempo do ciclo de lançamento atual e tenha expectativas realistas. Se você está |
| 88 |
dando um ping para aceitação — ou seja, não apenas para feedback ou uma |
| 89 |
atualização — por favor, faça tudo o que puder, dentro do razoável, para garantir |
| 90 |
que seus patches estejam prontos para o merge! Pings em séries que quebram o |
| 91 |
build ou falham em testes resultam em mantenedores infelizes! |
| 92 |
|
| 93 |
Desenvolvimento |
| 94 |
--------------- |
| 95 |
|
| 96 |
Árvore/Branch Base |
| 97 |
~~~~~~~~~~~~~~~~~~ |
| 98 |
Correções destinadas ao lançamento atual, também conhecido como mainline, devem |
| 99 |
ser baseadas em ``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Note |
| 100 |
que as correções não garantem inclusão automática no lançamento atual. Não |
| 101 |
existe uma regra única, mas tipicamente apenas correções para bugs que sejam |
| 102 |
urgentes, críticos e/ou que tenham sido introduzidos no lançamento atual devem |
| 103 |
ser destinadas ao lançamento atual. |
| 104 |
|
| 105 |
Todo o restante deve ser baseado em ``kvm-x86/next``, ou seja, não há |
| 106 |
necessidade de selecionar uma branch de tópico específica como base. Se houver |
| 107 |
conflitos e/ou dependências entre as branches de tópicos, é trabalho do |
| 108 |
mantenedor resolvê-los. |
| 109 |
|
| 110 |
A única exceção ao uso da ``kvm-x86/next`` como base é se um patch/série for uma |
| 111 |
série multi-arquitetura (multi-arch), ou seja, possuir modificações não triviais |
| 112 |
no código comum do KVM e/ou possuir mudanças mais do que superficiais no código |
| 113 |
de outras arquiteturas. Patches/séries multi-arquitetura devem, em vez disso, |
| 114 |
ser baseados em um ponto comum e estável no histórico do KVM, por exemplo, o |
| 115 |
release candidate no qual a ``kvm-x86 next`` se baseia. Se você não tiver |
| 116 |
certeza se um patch/série é verdadeiramente multi-arquitetura, erre pelo lado da |
| 117 |
cautela e trate-o como tal, ou seja, use uma base comum. |
| 118 |
|
| 119 |
Estilo de Codificação |
| 120 |
~~~~~~~~~~~~~~~~~~~~~ |
| 121 |
Quando se trata de estilo, nomenclatura, padrões, etc., a consistência é a |
| 122 |
prioridade número um no KVM x86. Se tudo mais falhar, siga o que já existe. |
| 123 |
|
| 124 |
Com algumas ressalvas listadas abaixo, siga o estilo de codificação preferido |
| 125 |
dos mantenedores da árvore "tip" (:ref:`maintainer-tip-coding-style`), já que |
| 126 |
patches/séries frequentemente tocam tanto arquivos do KVM quanto arquivos x86 |
| 127 |
não-KVM, ou seja, atraem a atenção de mantenedores do KVM *e* da árvore "tip". |
| 128 |
|
| 129 |
O uso de "reverse fir tree" (árvore de abeto invertida), também conhecido como |
| 130 |
"árvore de Natal invertida", para declarações de variáveis não é estritamente |
| 131 |
obrigatório, embora ainda seja preferido. |
| 132 |
|
| 133 |
Exceto por alguns casos excepcionais, não use comentários kernel-doc para |
| 134 |
funções. A grande maioria das funções "públicas" do KVM não são verdadeiramente |
| 135 |
públicas, pois se destinam apenas ao consumo interno do KVM (há planos para |
| 136 |
privatizar os headers e exports do KVM para reforçar isso). |
| 137 |
|
| 138 |
Comentários |
| 139 |
~~~~~~~~~~~ |
| 140 |
Escreva comentários usando o modo imperativo e evite pronomes. Use comentários |
| 141 |
para fornecer uma visão geral de alto nível do código e/ou para explicar por |
| 142 |
que o código faz o que faz. Não reitere o que o código faz literalmente; deixe |
| 143 |
o código falar por si mesmo. Se o código em si for inescrutável, comentários |
| 144 |
não ajudarão. |
| 145 |
|
| 146 |
Referências ao SDM e ao APM |
| 147 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 148 |
Grande parte da base de código do KVM está diretamente ligada ao comportamento |
| 149 |
arquitetural definido no Manual de Desenvolvimento de Software (SDM) da Intel e |
| 150 |
no Manual do Programador de Arquitetura (APM) da AMD. O uso de "Intel SDM" e |
| 151 |
"AMD APM", ou até mesmo apenas "SDM" ou "APM", sem contexto adicional, é |
| 152 |
perfeitamente aceitável. |
| 153 |
|
| 154 |
Não faça referência a seções, tabelas, figuras, etc., por número, especialmente |
| 155 |
em comentários. Em vez disso, se necessário (veja abaixo), copie e cole o trecho |
| 156 |
relevante e referencie seções/tabelas/figuras pelo nome. Os layouts do SDM e do |
| 157 |
APM mudam constantemente e, portanto, os números/rótulos não são estáveis. |
| 158 |
|
| 159 |
De modo geral, não faça referência explícita nem copie e cole do SDM ou do APM |
| 160 |
em comentários. Com poucas exceções, o KVM *deve* respeitar o comportamento |
| 161 |
arquitetural; portanto, subentende-se que o comportamento do KVM está emulando o |
| 162 |
comportamento do SDM e/ou do APM. Note que fazer referência ao SDM/APM em |
| 163 |
changelogs para justificar a mudança e fornecer contexto é perfeitamente |
| 164 |
aceitável e incentivado. |
| 165 |
|
| 166 |
Shortlog |
| 167 |
~~~~~~~~ |
| 168 |
O formato de prefixo preferencial é ``KVM: <topic>:``, onde ``<topic>`` é um dos |
| 169 |
seguintes:: |
| 170 |
|
| 171 |
- x86 |
| 172 |
- x86/mmu |
| 173 |
- x86/pmu |
| 174 |
- x86/xen |
| 175 |
- selftests |
| 176 |
- SVM |
| 177 |
- nSVM |
| 178 |
- VMX |
| 179 |
- nVMX |
| 180 |
|
| 181 |
**NÃO use x86/kvm!** ``x86/kvm`` é usado exclusivamente para mudanças no Linux |
| 182 |
como convidado (guest) de um KVM, ou seja, para ``arch/x86/kernel/kvm.c``. Não |
| 183 |
use nomes de arquivos ou caminhos completos de arquivos como prefixo do |
| 184 |
assunto/shortlog. |
| 185 |
|
| 186 |
Note que estes não se alinham com as branches de tópicos (as branches de tópicos |
| 187 |
se preocupam muito mais com conflitos de código). |
| 188 |
|
| 189 |
Todos os nomes são sensíveis a maiúsculas e minúsculas! ``KVM: x86:`` é bom, |
| 190 |
``kvm: vmx:`` não é. |
| 191 |
|
| 192 |
Comece com letra maiúscula a primeira palavra da descrição condensada do patch, |
| 193 |
mas omita a pontuação final. Ex.:: |
| 194 |
|
| 195 |
KVM: x86: Fix a null pointer dereference in function_xyz() |
| 196 |
|
| 197 |
e não:: |
| 198 |
|
| 199 |
kvm: x86: fix a null pointer dereference in function_xyz. |
| 200 |
|
| 201 |
Se um patch tocar em múltiplos tópicos, suba na árvore conceitual para encontrar |
| 202 |
o primeiro pai comum (que geralmente é apenas ``x86``). Em caso de dúvida, |
| 203 |
``git log caminho/do/arquivo`` deve fornecer uma dica razoável. |
| 204 |
|
| 205 |
Novos tópicos surgem ocasionalmente, mas, por favor, inicie uma discussão na |
| 206 |
lista se desejar propor a introdução de um novo tópico; ou seja, não aja por |
| 207 |
conta própria. |
| 208 |
|
| 209 |
Veja :ref:`the_canonical_patch_format` para mais informações, com uma ressalva: |
| 210 |
não trate o limite de 70-75 caracteres como um limite absoluto e rígido. Em |
| 211 |
vez disso, use 75 caracteres como um limite firme, mas não rígido, e use 80 |
| 212 |
caracteres como um limite intransponível. Ou seja, permita que o shortlog |
| 213 |
ultrapasse alguns caracteres do limite padrão se você tiver um bom motivo para |
| 214 |
fazê-lo. |
| 215 |
|
| 216 |
Changelog |
| 217 |
~~~~~~~~~ |
| 218 |
O mais importante: escreva os changelogs usando o modo imperativo e evite o uso |
| 219 |
de pronomes. |
| 220 |
|
| 221 |
Veja :ref:`describe_changes` para mais informações, com uma ressalva: comece com |
| 222 |
uma breve descrição das mudanças reais e, em seguida, apresente o contexto e o |
| 223 |
histórico. Note! Esta ordem entra em conflito direto com a abordagem preferida |
| 224 |
da árvore "tip"! Por favor, siga o estilo preferido da árvore "tip" ao enviar |
| 225 |
patches que visam primariamente o código de arch/x86 que _NÃO_ seja código KVM. |
| 226 |
|
| 227 |
Declarar o que um patch faz antes de mergulhar nos detalhes é preferido pelo KVM |
| 228 |
x86 por vários motivos. Primeiro e mais importante, qual código está sendo |
| 229 |
realmente alterado é, reconhecidamente, a informação mais importante e, |
| 230 |
portanto, essa informação deve ser fácil de encontrar. Changelogs que escondem |
| 231 |
"o que está mudando de fato" em uma única linha após 3 ou mais parágrafos de |
| 232 |
histórico tornam muito difícil encontrar essa informação. |
| 233 |
|
| 234 |
Para uma revisão inicial, pode-se argumentar que "o que está quebrado" é mais |
| 235 |
importante, mas para uma leitura rápida de logs e arqueologia do git, os |
| 236 |
detalhes minuciosos importam cada vez menos. Por exemplo, ao fazer uma série de |
| 237 |
"git blame", os detalhes de cada mudança ao longo do caminho são inúteis; os |
| 238 |
detalhes só importam para o culpado. Fornecer "o que mudou" facilita determinar |
| 239 |
rapidamente se um commit pode ou não ser de interesse. |
| 240 |
|
| 241 |
Outro benefício de declarar "o que está mudando" primeiro é que quase sempre é |
| 242 |
possível declarar "o que está mudando" em uma única frase. Por outro lado, |
| 243 |
exceto pelos bugs mais simples, todos exigem várias frases ou parágrafos para |
| 244 |
descrever totalmente o problema. Se tanto "o que está mudando" quanto "qual é o |
| 245 |
bug" forem super curtos, a ordem não importa. Mas se um for mais curto (quase |
| 246 |
sempre o "o que está mudando"), então cobrir o mais curto primeiro é vantajoso |
| 247 |
porque é menos inconveniente para leitores/revisores que têm uma preferência de |
| 248 |
ordenação estrita. Ex: ter que pular uma frase para chegar ao contexto é menos |
| 249 |
doloroso do que ter que pular três parágrafos para chegar ao "o que está |
| 250 |
mudando". |
| 251 |
|
| 252 |
Correções (Fixes) |
| 253 |
~~~~~~~~~~~~~~~~~ |
| 254 |
Se uma mudança corrige um bug do KVM/kernel, adicione uma tag Fixes:, mesmo que |
| 255 |
a mudança não precise ser portada (backported) para kernels estáveis, e mesmo |
| 256 |
que a mudança corrija um bug em uma versão mais antiga. |
| 257 |
|
| 258 |
Por outro lado, se uma correção realmente precisar de backport, marque |
| 259 |
explicitamente o patch com "Cc: [email protected]" (embora o e-mail em si |
| 260 |
não precise enviar cópia para a lista stable); o KVM x86 opta por não realizar |
| 261 |
o backport automático de tags Fixes: por padrão. Alguns patches selecionados |
| 262 |
automaticamente são portados, mas exigem aprovação explícita do mantenedor |
| 263 |
(pesquise por MANUALSEL). |
| 264 |
|
| 265 |
Referências a Funções |
| 266 |
~~~~~~~~~~~~~~~~~~~~~ |
| 267 |
Quando uma função for mencionada em um comentário, changelog ou shortlog (ou em |
| 268 |
qualquer outro lugar, aliás), use o formato ``nome_da_funcao()``. Os parênteses |
| 269 |
fornecem contexto e removem a ambiguidade da referência. |
| 270 |
|
| 271 |
Testes |
| 272 |
------ |
| 273 |
No mínimo, *todos* os patches de uma série devem compilar sem erros para |
| 274 |
KVM_INTEL=m, KVM_AMD=m e KVM_WERROR=y. Compilar cada combinação possível de |
| 275 |
Kconfigs não é viável, mas quanto mais, melhor. KVM_SMM, KVM_XEN, PROVE_LOCKING |
| 276 |
e X86_64 são opções (knobs) particularmente interessantes para se testar. |
| 277 |
|
| 278 |
A execução de KVM selftests e KVM-unit-tests também é obrigatória (e, para |
| 279 |
afirmar o óbvio, os testes precisam passar). A única exceção é para mudanças |
| 280 |
que tenham probabilidade insignificante de afetar o comportamento em tempo de |
| 281 |
execução, por exemplo, patches que apenas modificam comentários. Sempre que |
| 282 |
possível e relevante, o teste tanto em Intel quanto em AMD é fortemente |
| 283 |
preferido. A inicialização de uma VM real é incentivada, mas não obrigatória. |
| 284 |
|
| 285 |
Para mudanças que tocam o código de shadow paging do KVM, executar com o TDP |
| 286 |
(EPT/NPT) desabilitado é obrigatório. Para mudanças que afetam o código comum da |
| 287 |
MMU do KVM, a execução com o TDP desabilitado é fortemente incentivada. Para |
| 288 |
todas as outras mudanças, se o código sendo modificado depender de e/ou |
| 289 |
interagir com um parâmetro de módulo (module param), o teste com as |
| 290 |
configurações relevantes é obrigatório. |
| 291 |
|
| 292 |
Note que o KVM selftests e o KVM-unit-tests possuem falhas conhecidas. Se você |
| 293 |
suspeitar que uma falha não se deve às suas alterações, verifique se a *exata |
| 294 |
mesma* falha ocorre com e sem as suas mudanças. |
| 295 |
|
| 296 |
Mudanças que tocam a documentação em reStructuredText, ou seja, arquivos .rst, |
| 297 |
devem compilar o htmldocs de forma limpa, ou seja, sem novos avisos (warnings) |
| 298 |
ou erros. |
| 299 |
|
| 300 |
Se você não puder testar totalmente uma mudança, por exemplo, devido à falta de |
| 301 |
hardware, declare claramente qual nível de teste você foi capaz de realizar, |
| 302 |
por exemplo, na cover letter (carta de apresentação). |
| 303 |
|
| 304 |
Novos Recursos |
| 305 |
~~~~~~~~~~~~~~ |
| 306 |
Com uma exceção, novos recursos *devem* vir acompanhados de cobertura de testes. |
| 307 |
Testes específicos do KVM não são estritamente obrigatórios, por exemplo, se a |
| 308 |
cobertura for fornecida ao executar uma VM convidada (guest) suficientemente |
| 309 |
habilitada, ou ao executar um selftest de kernel relacionado em uma VM, mas |
| 310 |
testes dedicados do KVM são preferidos em todos os casos. Casos de teste |
| 311 |
negativos, em particular, são obrigatórios para a habilitação de novos recursos |
| 312 |
de hardware, já que fluxos de erro e exceção raramente são exercitados |
| 313 |
simplesmente ao executar uma VM. |
| 314 |
|
| 315 |
A única exceção a esta regra é se o KVM estiver simplesmente anunciando suporte |
| 316 |
para um recurso via KVM_GET_SUPPORTED_CPUID, ou seja, para instruções/recursos |
| 317 |
que o KVM não pode impedir um convidado de usar e para os quais não há uma |
| 318 |
habilitação real. |
| 319 |
|
| 320 |
Note que "novos recursos" não significa apenas "novos recursos de hardware"! |
| 321 |
Novos recursos que não podem ser bem validados usando os KVM selftests e/ou |
| 322 |
KVM-unit-tests existentes devem vir acompanhados de testes. |
| 323 |
|
| 324 |
Enviar o desenvolvimento de novos recursos sem testes para obter feedback |
| 325 |
antecipado é mais do que bem-vindo, mas tais submissões devem ser marcadas como |
| 326 |
RFC, e a carta de apresentação (cover letter) deve declarar claramente que tipo |
| 327 |
de feedback é solicitado/esperado. Não abuse do processo de RFC; as RFCs |
| 328 |
normalmente não receberão uma revisão profunda. |
| 329 |
|
| 330 |
Correções de Bugs |
| 331 |
~~~~~~~~~~~~~~~~~ |
| 332 |
Exceto por bugs "óbvios" encontrados por inspeção, as correções devem vir |
| 333 |
acompanhadas de um reprodutor (reproducer) para o bug que está sendo corrigido. |
| 334 |
Em muitos casos, o reprodutor é implícito, por exemplo, para erros de build e |
| 335 |
falhas de teste, mas ainda assim deve estar claro para os leitores o que está |
| 336 |
quebrado e como verificar a correção. Alguma margem de manobra é dada para |
| 337 |
bugs encontrados através de cargas de trabalho ou testes não públicos, mas a |
| 338 |
disponibilização de testes de regressão para tais bugs é fortemente preferida. |
| 339 |
|
| 340 |
Em geral, testes de regressão são preferidos para qualquer bug que não seja |
| 341 |
trivial de ser atingido. Por exemplo, mesmo que o bug tenha sido originalmente |
| 342 |
encontrado por um fuzzer como o syzkaller, um teste de regressão direcionado |
| 343 |
pode ser justificável se o bug exigir que se atinja uma condição de corrida do |
| 344 |
tipo "uma em um milhão". |
| 345 |
|
| 346 |
Note que os bugs do KVM raramente são urgentes *e* não triviais de reproduzir. |
| 347 |
Pergunte a si mesmo se um bug é realmente o fim do mundo antes de enviar uma |
| 348 |
correção sem um reprodutor. |
| 349 |
|
| 350 |
Postagem |
| 351 |
-------- |
| 352 |
|
| 353 |
Links |
| 354 |
~~~~~ |
| 355 |
Não faça referência explícita a relatórios de bugs, versões anteriores de um |
| 356 |
patch/série, etc., através de cabeçalhos ``In-Reply-To:``. O uso de |
| 357 |
``In-Reply-To:`` torna-se uma bagunça infernal para grandes séries e/ou quando |
| 358 |
o número de versões aumenta, e o ``In-Reply-To:`` é inútil para qualquer |
| 359 |
pessoa que não tenha a mensagem original, por exemplo, se alguém não estava |
| 360 |
em cópia (Cc) no relatório do bug ou se a lista de destinatários mudar entre |
| 361 |
as versões. |
| 362 |
|
| 363 |
Para vincular a um relatório de bug, versão anterior ou qualquer coisa de |
| 364 |
interesse, use links do lore. Para referenciar versão(ões) anterior(es), de modo |
| 365 |
geral, não inclua um Link: no changelog, pois não há necessidade de registrar o |
| 366 |
histórico no git; ou seja, coloque o link na carta de apresentação (cover |
| 367 |
letter) ou na seção que o git ignora. Forneça um Link: formal para relatórios |
| 368 |
de bugs e/ou discussões que levaram ao patch. O contexto de por que uma mudança |
| 369 |
foi feita é altamente valioso para futuros leitores. |
| 370 |
|
| 371 |
Base do Git (Git Base) |
| 372 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 373 |
Se você estiver usando o git versão 2.9.0 ou posterior (Googlers, isso inclui |
| 374 |
todos vocês!), use ``git format-patch`` com a flag ``--base`` para incluir |
| 375 |
automaticamente as informações da árvore base nos patches gerados. |
| 376 |
|
| 377 |
Note que ``--base=auto`` funciona conforme o esperado se, e somente se, o |
| 378 |
upstream de uma branch estiver definido para a branch de tópico base; por |
| 379 |
exemplo, ele fará a coisa errada se o seu upstream estiver definido para o seu |
| 380 |
repositório pessoal para fins de backup. Uma solução "auto" alternativa é |
| 381 |
derivar os nomes das suas branches de desenvolvimento com base no seu tópico |
| 382 |
KVM x86 e alimentar isso no ``--base``. Por exemplo, |
| 383 |
``x86/pmu/minha_branch`` e, em seguida, escrever um pequeno wrapper para |
| 384 |
extrair ``pmu`` do nome da branch atual para resultar em ``--base=x/pmu``, onde |
| 385 |
``x`` é o nome que seu repositório usa para rastrear o remoto do KVM x86. |
| 386 |
|
| 387 |
Postagem Conjunta de Testes |
| 388 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 389 |
KVM selftests que estão associados a mudanças no KVM, por exemplo, testes de |
| 390 |
regressão para correções de bugs, devem ser postados junto com as mudanças do |
| 391 |
KVM como uma única série. As regras padrão do kernel para bissecção (bisection) |
| 392 |
se aplicam, ou seja, mudanças no KVM que resultem em falhas de teste devem ser |
| 393 |
ordenadas após as atualizações dos selftests e, vice-versa, novos testes que |
| 394 |
falhem devido a bugs do KVM devem ser ordenados após as correções do KVM. |
| 395 |
|
| 396 |
KVM-unit-tests devem *sempre* ser postados separadamente. Ferramentas, como o |
| 397 |
b4 am, não sabem que o KVM-unit-tests é um repositório separado e ficam |
| 398 |
confusas quando os patches de uma série se aplicam a árvores diferentes. Para |
| 399 |
vincular os patches do KVM-unit-tests aos patches do KVM, poste primeiro as |
| 400 |
mudanças do KVM e, em seguida, forneça um link do lore para o patch/série do |
| 401 |
KVM no(s) patch(es) do KVM-unit-tests. |
| 402 |
|
| 403 |
Notificações |
| 404 |
------------ |
| 405 |
Quando um patch/série é oficialmente aceito, um e-mail de notificação será |
| 406 |
enviado em resposta à postagem original (carta de apresentação para séries de |
| 407 |
múltiplos patches). A notificação incluirá a árvore e a branch de tópico, |
| 408 |
juntamente com os SHA1s dos commits dos patches aplicados. |
| 409 |
|
| 410 |
Se um subconjunto de patches for aplicado, isso será claramente declarado na |
| 411 |
notificação. A menos que seja dito o contrário, subentende-se que quaisquer |
| 412 |
patches na série que não foram aceitos precisam de mais trabalho e devem ser |
| 413 |
enviados em uma nova versão. |
| 414 |
|
| 415 |
Se, por algum motivo, um patch for descartado após ter sido oficialmente |
| 416 |
aceito, uma resposta será enviada ao e-mail de notificação explicando o porquê |
| 417 |
do descarte, bem como os próximos passos. |
| 418 |
|
| 419 |
Estabilidade de SHA1 |
| 420 |
~~~~~~~~~~~~~~~~~~~~ |
| 421 |
Os SHA1s não têm garantia de serem 100% estáveis até que cheguem na árvore do |
| 422 |
Linus! Um SHA1 é *geralmente* estável uma vez que a notificação tenha sido |
| 423 |
enviada, mas imprevistos acontecem. Na maioria dos casos, uma atualização no |
| 424 |
e-mail de notificação será fornecida se o SHA1 de um patch aplicado mudar. No |
| 425 |
entanto, em alguns cenários, por exemplo, se todas as branches do KVM x86 |
| 426 |
precisarem de rebase, as notificações individuais não serão enviadas. |
| 427 |
|
| 428 |
Vulnerabilidades |
| 429 |
---------------- |
| 430 |
Bugs que podem ser explorados pelo convidado (guest) para atacar o hospedeiro |
| 431 |
(host) (kernel ou espaço do usuário), ou que podem ser explorados por uma VM |
| 432 |
aninhada (nested) contra o *seu* próprio hospedeiro (L2 atacando L1), são de |
| 433 |
interesse particular para o KVM. Por favor, siga o protocolo em |
| 434 |
:ref:`securitybugs` se você suspeitar que um bug possa levar a um escape, |
| 435 |
vazamento de dados, etc. |