Contribute/Send Patches (pt BR)

Este tutuorial mostra como enviar/submeter patches da maneira correta.

Notação

A palavra desenvolvedor é usada aqui para fazer referência a alguém que tem uma conta no SVN do KDE.

Preliminares

Supomos que você tenha modificado algum código no KDE e que está pronto para ser compartilhado. Primeiro, alguns pontos importantes:

Você deve permitir que a modificação tenha a mesma licença que os arquivos onde a alteração vai ser feita.
Por favor, tenha certeza que o código compila corretamente em uma versão (bastante) recente do software.

O que é um Patch?

Agora você tem um código fonte modificado. Enviar o arquivo de origem não será útil, já que provavelmente alguém já fez outras modificações para o arquivo original no mesmo período. Portanto, o seu arquivo modificado não pode substituí-lo.

É por isso que existem patches. Patches listam as modificações, os números de linha e outras informações úteis para que seja possível incluir essas alterações/correções no código atual. (Este processo é chamado de "patching" ou também "aplicar um patch").

A principal ferramenta para a criação de patches é uma ferramenta chamada diff, que mostra a diferença entre dois arquivos. Esta ferramenta tem um modo chamado “unified diff”, que os desenvolvedores do KDE usam. “Unified diffs” não contém apenas a diferença entre os arquivos, mas também outras alterações relacionadas as diferenças encontradas. Isso permite a aplicação do patch, mesmo que os números de linha não seja mais o mesmo.

Criando um Patch

O patch mais simples é criada entre o arquivo modificado (aqui denominado source.cpp) e a versão não modificada do arquivo (aqui chamado source.cpp.orig).

diff -u -p source.cpp.orig source.cpp

Este lista a diferença entre os dois arquivos no formato “unified diff” (e com a informação do nome da função, se possível.) No entanto, só exibe na tela, o que não é o objetivo. Então, você precisa redirecionar o output.

diff -u -p source.cpp.orig source.cpp > ~/patch.diff

path|~/patch.diff é um exemplo e você pode criar o arquivo onde preferir com o nome que você preferir. (Você vai logo descobrir que provavelmente não é uma boa idéia criar um patch onde o código fonte está.)

O caso mais comum

Mas, normalmente, não é só alterar um arquivo e não manter a versão original para poder fazer o diff mais tarde. Mas para isso, também temos uma solução.

O programa svn, que é utilizado na linha de comando interage com o servidor SVN, também tem a função diff: svn diff.

Você pode executá-lo assim e ele vai te dar a diferença do diretório atual e todos os sub-diretórios abaixo dele. E também aqui, você deve redirecionar o output.

svn diff > ~/patch.diff

Existem algumas variações úteis do comando (mostradas aqui sem redirecionamento)

Para apenas um arquivo: svn diff source.cpp
Para um diretório: svn diff -N

Nota: mesmo que svn possa fazer o diff de um outro diretório (svn diff mydirectory), não é recomendável fazer isso para um patch que possa ser aplicado novamente. (O problema é que a pessoa que vai aplicar o patch terá que ser mais cuidadoso ao fazer isso.)

Nota: para diff simples, como aqueles mostrados acima, o comando svn diff pode ser usado off-line, portanto, sem uma conexão ativa com o servidor SVN do KDE. Isto é possível pois o svn mantém uma cópia dos arquivos originais localmente. (Este recurso faz parte do SVN).

Por padrão, o comando svn diff não tem a opção -p como no diff. Mas o svn permite que um programa diff externo seja chamado, assim você pode chamar diff:

svn diff --diff-cmd diff --extensions "-u -p"

Arquivos não-texto

Os procedimentos descritos acima funcionam muito bem com arquivos de texto, por exemplo, códigos fonte em C + +. No entanto, eles não trabalham com arquivos binários, o diff não foi desenvolvido para comparar esse tipo de arquivo. E mesmo o SVN pode armazenar internamente diferenças binárias, svn diff ainda não está preparado para fazer qualquer coisa semelhante, principalmente porque atualmente usa somente o formato “unified diff”, que não é para dados binários.

Portanto, infelizmente, há poucas opções mas para anexar arquivos binários separados do patch, é claro, anexado no mesmo e-mail.

Novos Arquivos

Primeiro, você precisa fazer svn “ver” os arquivos que você adicionou.

svn add path/to/new/file /path/to/another/new/file

Em seguida, execute o comando svn diff, como antes.

Note que se você fizer o svn revert, por exemplo, os arquivos que você criou não serão excluídos por svn - mas o svn não vai mais se preocupar com eles (assim eles não aparecem quando você faz svn diff, por exemplo). Você terá que remove-los manualmente.

(TODO: existem outros problemas com a adição de novos arquivos, se você não tem acesso de submissão?)

Como compartilhar o patch?

Agora você está pronto para compartilhar o patch. Se o seu patch corrige um bug do KDE Bugs, então a maneira mais fácil é anexar lá mesmo, veja a próxima seção.

A principal forma de compartilhar um patch é enviar um e-mail para uma lista de discussão. Mas cuidado para não enviar grandes patches para uma lista de e-mails, uns 10KB é o limite.

Alguns projetos utilizam o KDE reviewboard para submeter o patch. Se um projeto está usando o reviewboard, que normalmente é a maneira preferida de receber patches. Consulte a seção abaixo para mais detalhes.

Se você achar que o patch é muito grande para enviar para uma lista de e-mails, o melhor é criar um bug report no KDE Bugs e anexar o patch nele.

Outra possibilidade, porém, raramente usada, é postar o patch em um servidor Web (seja por HTTP ou FTP) e enviar um email para a lista de discussão, dizendo que o patch está lá.

Também é possível perguntar na lista de e-mails que desenvolvedor pode pegar um patch grande. (Tente dar o tamanho do arquivo e pergunte se você deve enviá-lo compactado).

Como última opção, se você sabe exatamente qual desenvolvedor irá aplicar o patch e que você sabe/acha que ele tem tempo, é enviar o patch diretamente ele. (Mas aqui também, tenha cuidado se o seu patch é grande).

Patches para KDE Bugs

Nesta seção, vamos supor que você tenha escolhido adicionar o seu patch em um bug já existente no KDE bugtracker ou que você tenha criado um relatório de bug apenas para sua correção.

Mesmo que este tutoria fale bastante em enviar patches para uma lista de e-mails, a maioria dos patches pode ser adicionado no KDE Bugs.

Você tem duas maneiras de fazer isso:

Online, selecionando o relatório de erro, usando a interface web para adicionar os anexos.
Offline, enviar um e-mail ao relatório de erros.

Para enviar um email com um relatório de erros, você pode usar um endereço de e-mail do [email protected] formulário onde 12345 é o número do bug. Por favor, certifique-se de anexar o patch e não tê-lo no meio do seu texto. (se estiver, poderia chegar corrompido no KDE bugs, já que o HTML não respeita espaços).

Nota: se você enviar um e-mail para o KDE Bugs, tenha cuidado para usar como remetente o mesmo endereço de email que o seu endereço de e-mail de login do KDE Bugtracker. Caso contrário o KDE bugtracker vai rejeitar o seu e-mail.

Note: se você criar um novo bug apenas para sua correção, seja cuidadoso pois você não pode anexar um patch diretamente na criação de um novo bug. No entanto, logo que o bug é criado, você pode anexar arquivos, um por um, e os patches também.

Atenção: às vezes o seu patch poderá ser esquecido, porque os desenvolvedores nem sempre acompanham de perto o banco de dados de bugs. Neste caso, tente enviar o patch por e-mail como descrito abaixo. Se isso também não ajudar, você sempre pode falar com os desenvolvedores no IRC. IRC

Qual lista de e-mail?

Supondo que você tenha optado por enviar o patch para uma mailing list, você pode se perguntar: para qual lista?

O melhor destino para os patchs é uma lista de discussão de desenvolvedores correspondente ao programa que o seu patch se aplica.

Em caso de dúvida, você pode enviar o patch para o KDE para a lista de e-mail kde-devel. (No entanto, você corre o risco de esquecer do desenvolvedor certo.)

Claro, se você sabe exatamente qual desenvolvedor irá aplicar o patch e você acha que ele tem tempo, então você pode enviar o patch diretamente para ele.

Preparando o E-mail

Agora você tem um patch redirecionado para um arquivo (por exemplo patch.diff chamada), você está pronto para enviá-la por e-mail. Mas a primeira pergunta: para onde?

Agora que você já tem um endereço de e-mail, uma boa prática é anexar o patch para o seu arquivo antes de escrever qualquer outra coisa no e-mail. Então você não vai esquecer de anexá-lo.

Uma pequena nota aqui: sim, no KDE (ao contrário do Kernel do Linux por exemplo), nós preferimos ter os patches enviados como anexos.

Agora você está pronto para escrever o resto do e-mail. Por favor, pense em um título que corresponda ao seu patch. (Pense em ter que procura-lo novamente nos e-mails em alguns meses ou mesmo anos.) Um bom hábito é a preceder o título por [PATCH]. Assim, por exemplo, um título pode ser [PATCH] Fix arquivos de backup.

Quanto ao corpo do e-mail, por favor avise para qual arquivo ou diretório que o patch se aplica. Por exemplo, para um arquivo: O patch em anexo aplica-se ao koffice arquivo / kword / kwdoc.cpp ou para um diretório: O patch em anexo aplica-se ao koffice diretório / kword. Isso ajuda os desenvolvedores a ter uma visão geral de que código foi modificado. Também para dizer qual o ramo que se destina, por exemplo, para o trunk.

Então explique o que seus patches fazem. Se corrige um bug, então por favor dê o número do erro também. Se o erro não foi registrado no KDE Bugs, então por favor descreva o que você corrigiu. Da mesma forma, se você sabe que o patch corrige um bug encontrado a partir de uma revisão do SVN, adicione o número de revisão.

Diga também o que poderia ser útil para os desenvolvedores, por exemplo, se você não poderia completamente testar o patch (e porque), se precisar de ajuda para terminar, ou se é uma solução quick&dirty que poderia ser melhor corrigida a longo prazo .

Agora verifique o email novamente para ver se você não se esqueceu de alguma coisa (especialmente de anexar o patch) e então envie o e-mail.

Reviewboard

Uma maneira popular de comum patches é Reviewboard do KDE. Uma grande vantagem em relação ao uso do bugtracker do KDE é que os patches são menos propensos a serem esquecidos. Além disso, o Reviewboard permite uma revisão de linhas dos diffs e outros truques.

Primeiro você precisa verificar se o projeto para o qual você criou o patch está realmente usando o Reviewboard. Para isso, vá para a seção de projetos e confira se o grupo do projeto está listado lá. Se ele estiver listado lá, você deve usar o Reviewboard, senão envie o patch por outros meios.

Para enviar um patch, você precisa primeiro se registrar. Em seguida, clique em New Review Request e preencha o formulário. As partes mais importantes do formulário são:

The actual patch. Você precisa fazer o upload do patch que você criou anteriormente.

The SVN base path. Isso é necessário para a visualização inline patch para o trabalho. Isso pode ser um pouco complicado, se você não estiver familiarizado com o layout do KDE SVN, veja WebSVN. Por exemplo, se você está svn diff'ing de / caminho / para / a sua cópia / / de / kdelibs cmake / modules, o caminho de base deve ser / trunk / KDE / kdelibs / cmake / modules. Se você ainda não conhece o caminho correto de base, pergunte a um desenvolvedor no IRC. Você também pode editar o pedido de revisão posterior.

A summary of the patch. Este deve ser curto, ele vai aparecer como sujeito da e-mails de notificação.

A description of the patch. Isso pode ser mais longo.
The group(s). Verifique se você digitou o ID do grupo correto aqui, como visto anteriormente na página de grupos.

Depois de preenchido o formulário, um e-mail de notificação será enviado para os desenvolvedores e eles vão te responder.

/! \ Você precisa usar o svn diff em Inglês, se o sistema não é o Inglês, por favor, LC_ALL = C svn diff

E agora?

Agora você tem que esperar que um desenvolvedor reage sobre o seu adesivo. (Se você não está inscrito em listas de discussão onde você enviou o patch, em seguida, monitorar a lista de e-mail para tal mensagem.)

A reação é normalmente um dos seguintes procedimentos:

Não há respostas desenvolvedor. (Infelizmente, acontece de vez em quando.)
O desenvolvedor não quer o seu patch, pois ele está trabalhando no mesmo código.
O desenvolvedor não gosta do seu patch.
O desenvolvedor acha que você deveria mudar algumas coisas.
O desenvolvedor acha que o patch é bom e diz que irá trabalhar nele.
O desenvolvedor aceita o seu patch como ele é.

O primeiro caso é quando ninguém respondeu. Isso talvez signifique que você tenha escolhido a lista de discussão errada. Talvez você não tenha explicado corretamente o que o patch corrige ou você deu um título que não é suficientemente preciso. Se isso acontecer, o desenvolvedor pode ter deixado passar o seu patch. Talvez o desenvolvedor que deveria ter respondido não tem tempo para isso no momento. (Isso também acontece, infelizmente.) O melhor é tentar trabalhar um pouco mais sobre o patch, fazer uma descrição melhor e tentar novamente, talvez para uma outra lista de discussão ou para usar o KDE Bugs.

Se o desenvolvedor diz que o seu patch conflita com as mudanças que estão sendo feitas atualmente, você provavelmente não poderá fazer muita coisa a respeito. Talvez você possa discutir com ele como você pode trabalhar efetivamente com ele neste pedaço de código.

Se o patch não foi aceito, você poderá trabalhar mais nele. Você poderá discutir o problema na lista de discussão para saber que direção você deve trabalhar mais.

Se um desenvolvedor quer algumas alterações, trabalhe no código para fazer as mudanças de acordo com o solicitado. Se precisar de ajuda, porque você não entende como fazer as mudanças necessárias, então peça ajuda na lista de discussão.

E se o patch foi aceito, parabéns! :)