Difference between revisions of "Projects/MoveToGit/UsingSvn2Git (pt BR)"

Jump to: navigation, search
(Created page with '{{Template:I18n/Language Navigation Bar|Projects/MoveToGit/UsingSvn2Git}} This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010. ==...')
 
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Projects/MoveToGit/UsingSvn2Git}}
 
  
 
This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010.
 
This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010.
  
=== Servers to use for all developers ===
+
=== Servidores para todos os desenvolvedores ===
  
KDE Sysadmin provides 3 servers which are fully setup for writing rules. You can find more information about that on: http://community.kde.org/Sysadmin/DeveloperAccessForRuleWriting.
+
KDE Sysadmin dispõe de 3 servidores que estão configurados para escrever regras. Você pode encontrar mais informações sobre isso em: http://community.kde.org/Sysadmin/DeveloperAccessForRuleWriting.
  
All registered KDE developers have access to these machines. The rest of this document assumes a setup on your local computer, you are free to set it up on your local computer, but there is no need to. You can use the servers provided by KDE Sysadmin.
+
Todos os desenvolvedores do KDE registados têm acesso a essas máquinas. O restante deste documento assume uma configuração no seu computador local, você está livre para configurá-lo em seu computador local, mas não há nenhuma necessidade. Você pode usar os servidores fornecidos pelo KDE Sysadmin.
  
=== Getting the tools ===
+
=== Obtendo as ferramentas ===
  
The necessary tools are hosted at [http://www.gitorious.org/svn2git http://www.gitorious.org/svn2git]. To get started do:
+
As ferramentas necessárias estão hospedadas na [http://www.gitorious.org/svn2git http://www.gitorious.org/svn2git]. Para começar, faça:
  
<code bash>
+
<syntaxhighlight lang="bash">
 
git clone git://gitorious.org/svn2git/svn2git.git
 
git clone git://gitorious.org/svn2git/svn2git.git
 
git clone git://git.kde.org/kde-ruleset.git
 
git clone git://git.kde.org/kde-ruleset.git
</code>
+
</syntaxhighlight>
  
And then install the libsvn-dev package.
+
Então instale o pacote libsvn-dev.
  
This will get you the source code to build svn2git and the KDE ruleset files as they currently exist. Build the svn2git tool before moving on to the next step.
+
Isso vai te dar o código-fonte para dar um build no svn2git e nos arquivos de conjunto de regras do KDE como ele estão atualmente. Dê um build na ferramenta svn2git antes de passar para a próxima etapa.
  
 
==== Building svn2git ====
 
==== Building svn2git ====
Make sure you have Qt4 installed, then simply issue
+
Verifique se você tem Qt4 instalado, então use os comandos
<nowiki>qmake && make</nowiki> to build the executable called "svn-all-fast-export"
+
<nowiki>qmake && make</nowiki> para dar um no build the executável chamado "svn-all-fast-export"
  
=== How rulesets work ===
+
 
The format for the svn2git rules is pretty simple. First and foremost you
+
=== Como o conjuntos de regras funcionam ===
have to declare some repositories:
+
O formato das regras svn2git é bastante simples. Em primeiro lugar você tem que declarar alguns repositórios:
  
 
<pre>
 
<pre>
Line 35: Line 34:
 
</pre>
 
</pre>
  
This tells svn2git that it should create a git repository called "kdelibs" that we can later on use to put commits into it.
+
Isto diz svn2git que deve criar um repositório git chamado "kdelibs" que mais tarde, podemos usar para dar commits nele.
 +
 
 +
O resto do arquivo são regras de correspondência para patches específicos no Subversion, cada regra especifica o que fazer com o commit que aparecer no path especificado. As possíveis ações possíveis são ignorá-los ou adicioná-las a uma determinado branch ou a um repositório específico.  '''Nota:''' Ignorar é feito simplesmente por deixar de fora as informações sobre o repositório e do branch.
  
The rest of the file are rules matching specific paths in Subversion, each rule
+
Como exemplos são mais explicativos, a regra a seguir coloca todos os commits do 123453 até 456789 do path / trunk / KDE / kdelibs para o branch master do kdelibs:
specifies what to do with the commits that appeared at the given path. The
+
possible actions are ignoring them or adding them to a particular branch in a particular repository. '''Note:''' Ignoring is done by simply leaving out the information about the repository and the branch.
+
  
As examples are more explanatory, the following rule would put all commits from 123453 to 456789 from the path /trunk/KDE/kdelibs into the master branch of
 
the kdelibs repository:
 
 
<pre>
 
<pre>
 
match /trunk/KDE/kdelibs/
 
match /trunk/KDE/kdelibs/
Line 52: Line 49:
 
</pre>
 
</pre>
  
The min and max revision are useful in cases where the same path in SVN contains
+
A revisão min e max são úteis nos casos em que o mesmo path no SVN contém código para diferentes branchs. Um exemplo seria KDevelop3, onde 3,3 KDevelop foi colocado com o KDE 3.5 até 3.5.7, 3.5.8 contendo  KDevelop 3.4 e 3.5.9 contendo KDevelop 3.5 e todas as versões do kdevelop agora estão sob a / branches/KDE/3.5/kdevelop.
code for different branches. An example would be KDevelop3, where KDevelop 3.3 was shipped with KDE 3.5 until 3.5.7, 3.5.8 contained KDevelop 3.4 and 3.5.9 contained KDevelop 3.5 and all of those kdevelop versions are now under /branches/KDE/3.5/kdevelop.
+
  
The two revision parameters are however not mandatory, if they're left out, then all commits that went to the given matching path in SVN are taken over into the specified branch.
+
Os dois parâmetros de revisão não são obrigatórios, se eles são deixados de fora, então todas os commits para o path dado no SVN são retomadas no branch especificada.  
  
To generate tags with git you use a special format for the branch parameter: refs/tags/<tagname>. So to put all commits from /tags/KDE/4.4.0/kdelibs into the v4.4.0 tag in the kdelibs git repository the rule would be like this:
+
Para gerar tags com o git você usa um formato especial para o parâmetro do branch: refs / tags / <tagname>. Então, para colocar todos os commits de  /tags/KDE/4.4.0/kdelibs para a tag v4.4.0 no repositório git do kdelibs a regra seria a seguinte:
  
 
<pre>
 
<pre>
Line 66: Line 62:
 
</pre>
 
</pre>
  
For more examples see the svn2git/samples/ directory and the rules in the kde-ruleset repository.
+
Para mais exemplos ver o diretório  svn2git/samples/ e as regras no repositório kde-ruleset. A ação é um hack para dizer svn2git recurse em um diretório que acabou copiado ou que existia, porque é de interesse.
  
The recurse action is a hack to tell svn2git to recurse into a directory it
+
Exemplo: Se estamos importando kdelibs, existe em {{path|trunk/KDE/kdelibs}}. No branch, alguém fez: <syntaxhighlight lang="bash">svn cp $SVNROOT/trunk/KDE $SVNROOT/branches/KDE/4.4</syntaxhighlight>
has just copied or that existed because it is of interest. Example: if we are importing kdelibs, it exists in {{path|trunk/KDE/kdelibs}}. At branching, someone did: <code bash>svn cp $SVNROOT/trunk/KDE $SVNROOT/branches/KDE/4.4</code>
+
  
SVN recorded in that commit that branches/KDE/4.4 was the only path changed.  
+
SVN gravado naquele commit no branches/KDE/4.4 que era o único path mudado.
That means the rule <pre>branches/KDE/[^/]+/kdelibs/</pre> will not match.
+
Isso significa que a regra <pre>branches/KDE/[^/]+/kdelibs/</pre> não vai corresponder.
  
We need to tell the tool that something interesting happened inside and it
+
Nós precisamos dizer a ferramenta que algo interessante aconteceu e deveria ser aplicado. Em seguida, ele irá solicitar novamente todas as regras para os arquivos que existem nesse ponto, ponto em que as regras irão coincidir.
should recurse. Then it will apply again all rules to the files that exist at
+
that point, at which point the rules will match.
+
  
==== Important Details ====
+
==== Detalhes Importantes ====
  
* All matching rules need to end with a '/', else the tool will crash at some point. This is a known bug. The only exception are the rules using the recurse-action.
+
* Todas as regras de correspondência precisam terminar com uma '/', ou então a ferramenta irá falhar em algum ponto. Este é um bug conhecido. A única exceção são as regras usando o recurso de ação.
  
* Matching rules can use Regular Expressions (according to the QRegExp syntax) in the match line and can use backreferences in the repository and branch parameters using \n (n=1,2,3,...) to reduce the amount of rules.
+
* Regras de correspondência podem usar expressões regulares (de acordo com a sintaxe QRegExp) na linha de partida e pode usar backreferences nos parâmetros repositório e filiais usando \n (n = 1,2,3 ,...) para reduzir a quantidade de regras.
  
* The rules form an ordered list that the tool goes through while matching the changed paths for each commit. So if two rules match the same path and neither of the two has more matching criteria, then the rule that is written further up in the file wins. This is useful to exclude certain commits from the extraction process, if you look at the existing kde ruleset  you'll notice that at the top some revisions are ignored.
+
* As regras formam uma lista ordenada que a ferramenta percorre preenchendo os patches correspondentes em cada commit. Portanto, se duas regras correspondem ao mesmo path e nenhum dos dois tem mais critérios de correspondência, a regra que está escrita mais acima no arquivo tem prioridade. Isso é útil para excluir certos commits a partir do processo de extração, se você olhar para o conjunto de regras existentes você vai notar que no topo algumas revisões são ignoradas.
  
 
=== Setting up your system ===
 
=== Setting up your system ===
  
You will need ~65GB of disk space to get started, as the process requires a copy of the KDE svn database. There is a script that will download this for you (and which can be used to update it periodically using rsync) in kde-ruleset/bin/startSync.
+
Você vai precisar de ~ 65GB de espaço em disco para começar, pois o processo requer uma cópia do banco de dados CVS do KDE. Existe um script que irá transferir este para você (e que pode ser usado para atualizá-lo periodicamente com o rsync) na kde-ruleset/bin/startSync.
  
 
more stuff goes here ...
 
more stuff goes here ...
  
=== Step-by-Step on writing rules for a module ===
+
=== Passo-a-passo para escrever regras para um módulo ===
  
==== Analyzing Subversion history to write rules ====
+
==== Analisando o histórico do Subversion para escrever regras ====
First of all you should check whether there are already rules for this module in the kde-ruleset repository. If there are rules already please go down to "Running svn2git"
+
Primeiro de tudo você deve verificar se já existem regras para este módulo no repositório kde-regras. Se já existir alguma regra, por favor vá em "Running svn2git".
  
If there are no rules yet, lets start with the master (aka trunk) branch. The easiest way to find out history with svn is executing:
+
Se não há regras, no entanto, vamos começar com a brunch master (aka trunk). A maneira mais fácil de descobrir o histórico com o SVN é executando:
 
<pre>svn log -v --stop-on-copy file:///path/to/kde_svn/trunk/KDE/module</pre>
 
<pre>svn log -v --stop-on-copy file:///path/to/kde_svn/trunk/KDE/module</pre>
  
Please note that '/path/to/kde_svn/' is the path to the 65GB you downloaded, and the 'trunk/KDE/module' is the module you want to write rules for, but those two put together is *not* a path that physically exists on your disk. svn log is smart enough to do what you want.
+
Por favor, note que '/path/to/kde_svn/' é o path para o 65GB você baixou, e o 'trunk/KDE/module' é o módulo que você quer escrever as regras, mas aqueles colocados dois juntos *não* é um caminho que existe fisicamente no disco. svn log é inteligente o suficiente para fazer o que quiser.
  
This will give you a history of the given module in trunk, it'll stop on the first commit that copied the code from somewhere else. The verbose output will allow you to see where this copy came from.
+
Isto lhe dará uma história do dado módulo no porta-malas, ele vai parar na primeira cometer o código que copiou de outro lugar. A saída detalhada permitirá que você veja onde esta cópia veio.
 +
 
 +
Agora temos um ponto de partida para escrever uma regra, queremos que todos os commits a deste path em nosso repositório no branch master:
  
Now we have a starting point to write a rule, we want all commits from this path in our module repository in the master branch:
 
 
<pre>
 
<pre>
 
match /trunk/KDE/module/
 
match /trunk/KDE/module/
Line 111: Line 105:
 
end match
 
end match
 
</pre>
 
</pre>
If the log stops at a commit that copied the module from somewhere, we need to
+
 
follow this to also get the history imported from the "old" place the module resided. The same svn command can be used with slightly different path argument:
+
 
 +
Se o log pára em uma confirmação de que copiou o módulo de algum lugar, precisamos acompanhar este também terá a história importada a partir do local "velho" o módulo residia. O comando svn mesmo pode ser usado com o argumento de path um pouco diferente:
  
 
<pre>svn log -v --stop-on-copy file:///path/to/kde_svn/some/other/path@revision</pre>
 
<pre>svn log -v --stop-on-copy file:///path/to/kde_svn/some/other/path@revision</pre>
The @revision is important as the original path usually doesn't exist anymore. With this we can write the next rule to the rules file and repeat until we've finally reached the point where the code was initially imported into svn (or probably cvs in the old days)
 
  
Now we can take care of the branches, this is a bit more involved as there may be multiple branches scattered over the /branches directory in svn. You can use the same commands as before to find out the history of a branch if you know the path. This time however you can stop following the source of copy-operations once you've found a source that you've already matched in a rule. That way your branch will be connected to the branch it originated from (which is often trunk aka master) in git.
+
A @revision é importante, pois o path original geralmente não existe mais. Com isso podemos escrever a próxima regra para o arquivo de regras e repetir até que tenhamos finalmente chegado ao ponto em que o código foi inicialmente importado para o svn (ou CVS, provavelmente, nos velhos tempos)
  
A useful help with finding branches is svn ls in combination with the path@revision syntax, that way you can view the content of a particular svn directory as it was in an older revision. With this you can even find branches that are not visible (have been deleted) in the current revision.
+
Agora nós podemos cuidar das branches, isto é um pouco mais complicado já que pode haver várias branches espalhadas pelo diretório /branches no svn. Você pode usar os mesmos comandos de antes de descobrir o histórico de um branch, se você sabe o path. Desta vez, porém você pode parar de seguir o código da copy-operations, uma vez que você encontrou um código que já foram encontrados em uma regra. Dessa forma, seu ramo estarão ligados ao ramo que o originou (que geralmente é conhecido como trunk aka master) no git.
 +
 
 +
Uma ajuda útil em encontrar branches é svn ls em combinação com o path@revision sintaxe, dessa forma você pode visualizar o conteúdo de um diretório específico svn como era em uma versão antiga. Com isso, você pode até encontrar ramos que não são visíveis (foram excluídos) na versão atual.
 +
 +
A regra para colocar compromete-se em um ramo no repositório git final só é um pouco diferente (o exemplo é de um módulo central):
  
The rule for putting commits into a git branch in the final repository is only slightly different (the example is for a core module):
 
 
<pre>
 
<pre>
 
match /branches/KDE/4.4/module
 
match /branches/KDE/4.4/module
Line 129: Line 126:
 
</pre>
 
</pre>
  
And last are the tags, this works the same as branches and trunk, except for using branch refs/tags/v<tag-version> for the branch parameter.
+
E por último, estão as tags, este funciona da mesma forma como as branches e trunk, exceto usando o branch refs/tags/v<tag-version> para o parâmetro do branch.
 +
 
 +
==== Executando svn2git ====
 +
Este é o mais fácil, mas que consome mais tempo. Como exemplo, vamos dizer que em nosso diretório de trabalho atual, temos as regras no repositório kde-ruleset subdir, a ferramenta svn2git na subdir svn2git e o repositório  do KDE do no subdir kde_svn:
  
==== Running svn2git ====
 
This is the easiest, but most time-consuming part. As example lets say that in our current working directory we have the kde rules repository in kde-ruleset subdir, the svn2git tool in the svn2git subdir and the KDE repository in the kde_svn subdir:
 
 
<pre>
 
<pre>
 
svn2git/svn-all-fast-export --identity-map kde-ruleset/account-map --rules kde-ruleset/module kde_svn
 
svn2git/svn-all-fast-export --identity-map kde-ruleset/account-map --rules kde-ruleset/module kde_svn
 
</pre>
 
</pre>
  
This will take a few hours usually, but it'll spit out the progress. The tool also writes a logfile to module.log, so in case something goes wrong you can find more details in there.
+
Isso irá levar algumas horas normalmente, mas ele vai mostrar o progresso. A ferramenta também escreve um log em module.log, caso algo dê errado, você pode encontrar mais detalhes lá.
  
Once its done you should have a new "module" git repository in your current working directory.  
+
Tendo isso feito, você deve ter um novo "módulo" de repositório git no seu diretório de trabalho atual.
  
==== Checking for proper history in the new git repository ====
+
==== Verificando um histórico adequado no novo respositório git ====
A very easy way to check whether the history was imported properly is to use the gitk tool from git. It shows you a graphical representation of the history in the git repository which makes it easy to identify where something is wrong.
+
  
The tool should be run with the --all switch so it shows all branches.
+
Uma maneira muito fácil de verificar se o histórico foi importado corretamente é usar a ferramenta gitk do git. Ele mostra uma representação gráfica da história no repositório git que torna fácil identificar onde algo está errado.
  
You can now scroll through the history to check whether things have been imported correctly.
+
A ferramenta deve ser executada com a - todas as chaves para que ele mostre todos as branches.  
  
First and foremost there should be the master branch starting at the top with the most recent commit to trunk/ and ending in the oldest commit that imported the code into KDE's svn or cvs repository.  
+
Agora você pode percorrer o histórico para verificar se as coisas foram importadas corretamente.  
  
From the master branch there should be several branches going away for each branch you imported. And eventually also branches that start from another non-master branch.
+
Em primeiro lugar deve haver o branch master, começando no topo com o mais recente commit para o trunk/ e terminando no mais antigo commit que importado o código no SVN do KDE ou o repositório cvs.
  
Things that you should look out for are branches that start "nowhere", that is the first commit in the branch has no parent in another branch or master. This means that svn2git didn't see a commit that created this branch from another using a svn cp command. That can mean that you may have forgotton to add a match rule for some path or that the same path was used for different branches in different revisions. The same applies to tags which have a commit without any parent.
 
  
This can usually be fixed by using svn log and svn ls to follow the history of the branch. Eventually you might need to apply the min/max revision paramters.
+
A partir do branch master deve haver várias branches para cada branch importada. E eventualmente também branches que partem de uma outra non-master branch.
  
You'll notice that some tags are looking like this:
+
Coisas que você deve checar são branchs que começam "em lugar nenhum", que é o primeiro commit no ramo não tem nenhum pai em outro ramo ou mestre. Isso significa que svn2git não vêum commit que criou este branch de outro usando o comando svn cp. Isso pode significar que você pode ter esquecido de adicionar uma regra para algum path ou que o mesmo  path foi usado para diferentes branches em revisões diferentes. O mesmo se aplica a tags que tenham um commit sem parent.
 +
 
 +
Isto normalmente pode ser corrigido usando svn log e svn ls para acompanhar o histórico do branch. Eventualmente você pode precisar aplicar os parâmetros min / max da revisão.
 +
 
 +
Você perceberá que algumas marcas estão procurando desta forma:
  
 
<pre>
 
<pre>
Line 167: Line 167:
 
</pre>
 
</pre>
  
Thats normal for our tags even if a bit ugly. The reason is that often compile-fixes are done in trunk/ after the tag has been created and then the commit has been merged over to the tag.
+
Isso é normal para nossas tags, mesmo que um pouco feio. A razão é que, muitas vezes de compile-fixes são feitas no trunk/ após o tag ter sido criada e, em seguida, o commit foi mesclar (merge) com a tag. Outra coisa, porém, são as tags que são nomeados vx.y.z_124321. Estas são as tags que foram apagadas e recriadas depois.  
  
Another thing however are tags that are named vx.y.z_124321. These are tags that have been deleted and re-created later. You can usually see that in the svn log history, these tags can either be manually deleted after the repository creation using git tag or you can add rules that ignore certain revisions of the tag-path before the one putting the commits into the git repository:
+
Normalmente você pode ver que, no log do histórico do svn, essas tags podem ser excluídas manualmente após a criação do repositório usando git tag ou você pode adicionar regras que ignorem certas revisões do tag-path antes de o colocar os commits no repositório git:
  
 
<pre>
 
<pre>
Line 182: Line 182:
 
</pre>
 
</pre>
  
If you choose to delete them manually please make sure to document this with a textfile or inside the rule file so if someone else does the conversion later again he'll know what manual steps you did.
+
Se você optar por excluí-los manualmente, por favor certifique-se de documentar com um arquivo texto ou dentro do arquivo de regras, caso alguém faça a conversão novamente mais tarde ele vai saber os passos que você fez.
  
Before publishing the newly created git repository make sure to repack it. This can greatly reduce it's size (i.e. Phonon's git repository could be shrunken from 18 MB to 5.2 MB)
+
Antes de publicar o recém criado repositório git certifique-se de empacotá-lo. Isso pode reduzir muito o seu tamanho (por exemplo, Phonon do repositório git poderia ser compactado de 18 MB para 5,2 MB)
  
==== How to update the account-map file ====
+
==== Como atualizar o arquivo account-map ====
  
Currently, account-map file is being generated with 'generateAccountMap'[http://gitorious.org/svn2git/kde-ruleset/blobs/master/bin/generateAccountMap] script which parses kde-common/accounts[http://websvn.kde.org/trunk/kde-common/accounts?view=log] and kde-common/disabled-accounts[http://websvn.kde.org/trunk/kde-common/disabled-accounts?view=log] from SVN.
+
No momento, o arquivo account-map está sendo gerado com script 'generateAccountMap' [http://gitorious.org/svn2git/kde-ruleset/blobs/master/bin/generateAccountMap] que analisa kde-common/accounts [http://websvn.kde.org/trunk/kde-common/accounts?view=log] e kde-common/disabled-accounts [http://websvn.kde.org/trunk/kde-common/disabled-accounts?view=log] do SVN.
  
Once you have your git repository you should check if there are accounts not listed in account-map file (you can use checkMissingAccounts[http://gitorious.org/svn2git/kde-ruleset/blobs/master/bin/checkMissingAccounts]), if that is the case, check if the missing accounts are listed in kde-common/accounts or kde-common/disabled-accounts, if it's not there file a sysadmin bug report[https://bugs.kde.org/enter_sysadmin_request.cgi] to get your missing account included in disabled-accounts. Once you get your missing accounts included in disabled accounts, you could generate the account-map file running 'bin/generateAccountMap', then run svn-all-fast-export again. Do not edit account-map file directly!
+
Depois de ter seu repositório git, você deve verificar se há contas não listadas  no arquivo account-map (você pode usar checkMissingAccounts [http://gitorious.org/svn2git/kde-ruleset/blobs/master/bin/checkMissingAccounts]), se for o caso, verifique se as contas que faltam estão listadas no kde-common/accounts ou kde-common/disabled-accounts, se ele não tem um sysadmin bug report [https://bugs.kde.org/enter_sysadmin_request.cgi] para ter a sua conta excluída em incluída nas disabled-accounts. Depois de ter suas contas em falta incluídas nas disabled-accounts, você poderia gerar o arquivo account-map executando 'bin/generateAccountMap', em seguida, execute svn-all-fast-export novamente. Não editar o  arquivo account-map diretamente!
  
 
=== Troubleshooting ===
 
=== Troubleshooting ===
  
==== Recurse action doesn't work with cvs2svn tag commits ====
+
==== Ação Recurse não funciona com cvs2svn tag commit ====
 +
 
 +
Você pode ter que lidar com um commit feito por cvs2svn para criar uma tag, por exemplo:
  
You may have to deal with a commit done by cvs2svn to create a tag, for example:
 
 
<pre>
 
<pre>
 
r386536 | (no author) | 2005-02-05 22:16:00 +0100 (Sat, 05 Feb 2005) | 2 lines
 
r386536 | (no author) | 2005-02-05 22:16:00 +0100 (Sat, 05 Feb 2005) | 2 lines
Line 321: Line 322:
 
</pre>
 
</pre>
  
=== Getting Help ===
+
=== Pedindo Ajuda ===
If you run into strange things or can't find a rule for something you can reach the KDE Git migration team on IRC: irc.freenode.org, #kde-git or on the [https://mail.kde.org/mailman/listinfo/kde-scm-interest kde-scm-interest mailinglist]
+
Se você topar com coisas estranhas ou não consegue encontrar uma regra para algo que você precisa, você pode falar com a equipe de migração do KDE Git no IRC: irc.freenode.org, #kde-git ou na [https://mail.kde.org/mailman/listinfo/kde-scm-interest kde-scm-interest mailinglist]

Latest revision as of 16:30, 19 July 2012

This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010.

Contents

[edit] Servidores para todos os desenvolvedores

KDE Sysadmin dispõe de 3 servidores que estão configurados para escrever regras. Você pode encontrar mais informações sobre isso em: http://community.kde.org/Sysadmin/DeveloperAccessForRuleWriting.

Todos os desenvolvedores do KDE registados têm acesso a essas máquinas. O restante deste documento assume uma configuração no seu computador local, você está livre para configurá-lo em seu computador local, mas não há nenhuma necessidade. Você pode usar os servidores fornecidos pelo KDE Sysadmin.

[edit] Obtendo as ferramentas

As ferramentas necessárias estão hospedadas na http://www.gitorious.org/svn2git. Para começar, faça:

git clone git://gitorious.org/svn2git/svn2git.git
git clone git://git.kde.org/kde-ruleset.git

Então instale o pacote libsvn-dev.

Isso vai te dar o código-fonte para dar um build no svn2git e nos arquivos de conjunto de regras do KDE como ele estão atualmente. Dê um build na ferramenta svn2git antes de passar para a próxima etapa.

[edit] Building svn2git

Verifique se você tem Qt4 instalado, então use os comandos qmake && make para dar um no build the executável chamado "svn-all-fast-export"


[edit] Como o conjuntos de regras funcionam

O formato das regras svn2git é bastante simples. Em primeiro lugar você tem que declarar alguns repositórios:

create repository kdelibs
end repository

Isto diz svn2git que deve criar um repositório git chamado "kdelibs" que mais tarde, podemos usar para dar commits nele.

O resto do arquivo são regras de correspondência para patches específicos no Subversion, cada regra especifica o que fazer com o commit que aparecer no path especificado. As possíveis ações possíveis são ignorá-los ou adicioná-las a uma determinado branch ou a um repositório específico. Nota: Ignorar é feito simplesmente por deixar de fora as informações sobre o repositório e do branch.

Como exemplos são mais explicativos, a regra a seguir coloca todos os commits do 123453 até 456789 do path / trunk / KDE / kdelibs para o branch master do kdelibs:

match /trunk/KDE/kdelibs/
  min revision 123453
  max revision 456789
  repository kdelibs
  branch master
end match

A revisão min e max são úteis nos casos em que o mesmo path no SVN contém código para diferentes branchs. Um exemplo seria KDevelop3, onde 3,3 KDevelop foi colocado com o KDE 3.5 até 3.5.7, 3.5.8 contendo KDevelop 3.4 e 3.5.9 contendo KDevelop 3.5 e todas as versões do kdevelop agora estão sob a / branches/KDE/3.5/kdevelop.

Os dois parâmetros de revisão não são obrigatórios, se eles são deixados de fora, então todas os commits para o path dado no SVN são retomadas no branch especificada.

Para gerar tags com o git você usa um formato especial para o parâmetro do branch: refs / tags / <tagname>. Então, para colocar todos os commits de /tags/KDE/4.4.0/kdelibs para a tag v4.4.0 no repositório git do kdelibs a regra seria a seguinte:

match /tags/KDE/4.4.0/kdelibs/
  repository kdelibs
  branch refs/tags/v4.4.0
end match

Para mais exemplos ver o diretório svn2git/samples/ e as regras no repositório kde-ruleset. A ação é um hack para dizer svn2git recurse em um diretório que acabou copiado ou que existia, porque é de interesse.

Exemplo: Se estamos importando kdelibs, existe em trunk/KDE/kdelibs. No branch, alguém fez:
svn cp $SVNROOT/trunk/KDE $SVNROOT/branches/KDE/4.4

SVN gravado naquele commit no branches/KDE/4.4 que era o único path mudado.

Isso significa que a regra
branches/KDE/[^/]+/kdelibs/
não vai corresponder.

Nós precisamos dizer a ferramenta que algo interessante aconteceu e deveria ser aplicado. Em seguida, ele irá solicitar novamente todas as regras para os arquivos que existem nesse ponto, ponto em que as regras irão coincidir.

[edit] Detalhes Importantes

  • Todas as regras de correspondência precisam terminar com uma '/', ou então a ferramenta irá falhar em algum ponto. Este é um bug conhecido. A única exceção são as regras usando o recurso de ação.
  • Regras de correspondência podem usar expressões regulares (de acordo com a sintaxe QRegExp) na linha de partida e pode usar backreferences nos parâmetros repositório e filiais usando \n (n = 1,2,3 ,...) para reduzir a quantidade de regras.
  • As regras formam uma lista ordenada que a ferramenta percorre preenchendo os patches correspondentes em cada commit. Portanto, se duas regras correspondem ao mesmo path e nenhum dos dois tem mais critérios de correspondência, a regra que está escrita mais acima no arquivo tem prioridade. Isso é útil para excluir certos commits a partir do processo de extração, se você olhar para o conjunto de regras existentes você vai notar que no topo algumas revisões são ignoradas.

[edit] Setting up your system

Você vai precisar de ~ 65GB de espaço em disco para começar, pois o processo requer uma cópia do banco de dados CVS do KDE. Existe um script que irá transferir este para você (e que pode ser usado para atualizá-lo periodicamente com o rsync) na kde-ruleset/bin/startSync.

more stuff goes here ...

[edit] Passo-a-passo para escrever regras para um módulo

[edit] Analisando o histórico do Subversion para escrever regras

Primeiro de tudo você deve verificar se já existem regras para este módulo no repositório kde-regras. Se já existir alguma regra, por favor vá em "Running svn2git".

Se não há regras, no entanto, vamos começar com a brunch master (aka trunk). A maneira mais fácil de descobrir o histórico com o SVN é executando:

svn log -v --stop-on-copy file:///path/to/kde_svn/trunk/KDE/module

Por favor, note que '/path/to/kde_svn/' é o path para o 65GB você baixou, e o 'trunk/KDE/module' é o módulo que você quer escrever as regras, mas aqueles colocados dois juntos *não* é um caminho que existe fisicamente no disco. svn log é inteligente o suficiente para fazer o que quiser.

Isto lhe dará uma história do dado módulo no porta-malas, ele vai parar na primeira cometer o código que copiou de outro lugar. A saída detalhada permitirá que você veja onde esta cópia veio.

Agora temos um ponto de partida para escrever uma regra, queremos que todos os commits a deste path em nosso repositório no branch master:

match /trunk/KDE/module/
  repository module
  branch master
end match


Se o log pára em uma confirmação de que copiou o módulo de algum lugar, precisamos acompanhar este também terá a história importada a partir do local "velho" o módulo residia. O comando svn mesmo pode ser usado com o argumento de path um pouco diferente:

svn log -v --stop-on-copy file:///path/to/kde_svn/some/other/path@revision

A @revision é importante, pois o path original geralmente não existe mais. Com isso podemos escrever a próxima regra para o arquivo de regras e repetir até que tenhamos finalmente chegado ao ponto em que o código foi inicialmente importado para o svn (ou CVS, provavelmente, nos velhos tempos)

Agora nós podemos cuidar das branches, isto é um pouco mais complicado já que pode haver várias branches espalhadas pelo diretório /branches no svn. Você pode usar os mesmos comandos de antes de descobrir o histórico de um branch, se você sabe o path. Desta vez, porém você pode parar de seguir o código da copy-operations, uma vez que você encontrou um código que já foram encontrados em uma regra. Dessa forma, seu ramo estarão ligados ao ramo que o originou (que geralmente é conhecido como trunk aka master) no git.

Uma ajuda útil em encontrar branches é svn ls em combinação com o path@revision sintaxe, dessa forma você pode visualizar o conteúdo de um diretório específico svn como era em uma versão antiga. Com isso, você pode até encontrar ramos que não são visíveis (foram excluídos) na versão atual.

A regra para colocar compromete-se em um ramo no repositório git final só é um pouco diferente (o exemplo é de um módulo central):

match /branches/KDE/4.4/module
  repository module
  branch 4.4
end match

E por último, estão as tags, este funciona da mesma forma como as branches e trunk, exceto usando o branch refs/tags/v<tag-version> para o parâmetro do branch.

[edit] Executando svn2git

Este é o mais fácil, mas que consome mais tempo. Como exemplo, vamos dizer que em nosso diretório de trabalho atual, temos as regras no repositório kde-ruleset subdir, a ferramenta svn2git na subdir svn2git e o repositório do KDE do no subdir kde_svn:

svn2git/svn-all-fast-export --identity-map kde-ruleset/account-map --rules kde-ruleset/module kde_svn

Isso irá levar algumas horas normalmente, mas ele vai mostrar o progresso. A ferramenta também escreve um log em module.log, caso algo dê errado, você pode encontrar mais detalhes lá.

Tendo isso feito, você deve ter um novo "módulo" de repositório git no seu diretório de trabalho atual.

[edit] Verificando um histórico adequado no novo respositório git

Uma maneira muito fácil de verificar se o histórico foi importado corretamente é usar a ferramenta gitk do git. Ele mostra uma representação gráfica da história no repositório git que torna fácil identificar onde algo está errado.

A ferramenta deve ser executada com a - todas as chaves para que ele mostre todos as branches.

Agora você pode percorrer o histórico para verificar se as coisas foram importadas corretamente.

Em primeiro lugar deve haver o branch master, começando no topo com o mais recente commit para o trunk/ e terminando no mais antigo commit que importado o código no SVN do KDE ou o repositório cvs.


A partir do branch master deve haver várias branches para cada branch importada. E eventualmente também branches que partem de uma outra non-master branch.

Coisas que você deve checar são branchs que começam "em lugar nenhum", que é o primeiro commit no ramo não tem nenhum pai em outro ramo ou mestre. Isso significa que svn2git não vêum commit que criou este branch de outro usando o comando svn cp. Isso pode significar que você pode ter esquecido de adicionar uma regra para algum path ou que o mesmo path foi usado para diferentes branches em revisões diferentes. O mesmo se aplica a tags que tenham um commit sem parent.

Isto normalmente pode ser corrigido usando svn log e svn ls para acompanhar o histórico do branch. Eventualmente você pode precisar aplicar os parâmetros min / max da revisão.

Você perceberá que algumas marcas estão procurando desta forma:

|
* * <v1.2.3>
| |
* *
| /
*

Isso é normal para nossas tags, mesmo que um pouco feio. A razão é que, muitas vezes de compile-fixes são feitas no trunk/ após o tag ter sido criada e, em seguida, o commit foi mesclar (merge) com a tag. Outra coisa, porém, são as tags que são nomeados vx.y.z_124321. Estas são as tags que foram apagadas e recriadas depois.

Normalmente você pode ver que, no log do histórico do svn, essas tags podem ser excluídas manualmente após a criação do repositório usando git tag ou você pode adicionar regras que ignorem certas revisões do tag-path antes de o colocar os commits no repositório git:

match /tags/KDE/3.3.2/kdelibs
  min revision 424234
  max revision 424236
end match
match /tags/KDE/3.3.2/kdelibs
  repository kdelibs
  branch refs/tags/3.3.2
end match

Se você optar por excluí-los manualmente, por favor certifique-se de documentar com um arquivo texto ou dentro do arquivo de regras, caso alguém faça a conversão novamente mais tarde ele vai saber os passos que você fez.

Antes de publicar o recém criado repositório git certifique-se de empacotá-lo. Isso pode reduzir muito o seu tamanho (por exemplo, Phonon do repositório git poderia ser compactado de 18 MB para 5,2 MB)

[edit] Como atualizar o arquivo account-map

No momento, o arquivo account-map está sendo gerado com script 'generateAccountMap' [1] que analisa kde-common/accounts [2] e kde-common/disabled-accounts [3] do SVN.

Depois de ter seu repositório git, você deve verificar se há contas não listadas no arquivo account-map (você pode usar checkMissingAccounts [4]), se for o caso, verifique se as contas que faltam estão listadas no kde-common/accounts ou kde-common/disabled-accounts, se ele não tem um sysadmin bug report [5] para ter a sua conta excluída em incluída nas disabled-accounts. Depois de ter suas contas em falta incluídas nas disabled-accounts, você poderia gerar o arquivo account-map executando 'bin/generateAccountMap', em seguida, execute svn-all-fast-export novamente. Não editar o arquivo account-map diretamente!

[edit] Troubleshooting

[edit] Ação Recurse não funciona com cvs2svn tag commit

Você pode ter que lidar com um commit feito por cvs2svn para criar uma tag, por exemplo:

r386536 | (no author) | 2005-02-05 22:16:00 +0100 (Sat, 05 Feb 2005) | 2 lines
Changed paths:
   A /branches/beta_0_7_branch (from /trunk:386535)
   D /branches/beta_0_7_branch/art-devel
   D /branches/beta_0_7_branch/arts
   D /branches/beta_0_7_branch/bugs
   D /branches/beta_0_7_branch/devel-home
   D /branches/beta_0_7_branch/developer.kde.org
   D /branches/beta_0_7_branch/enterprise.kde.org
   D /branches/beta_0_7_branch/events.kde.org
   D /branches/beta_0_7_branch/foundation
   D /branches/beta_0_7_branch/kckde
   D /branches/beta_0_7_branch/kde-common
   D /branches/beta_0_7_branch/kde-i18n
   D /branches/beta_0_7_branch/kde-qt-addon
   D /branches/beta_0_7_branch/kde-women.kde.org
   D /branches/beta_0_7_branch/kdeaccessibility
   D /branches/beta_0_7_branch/kdeaddons
   D /branches/beta_0_7_branch/kdeadmin
   D /branches/beta_0_7_branch/kdeartwork
   D /branches/beta_0_7_branch/kdebase
   D /branches/beta_0_7_branch/kdebindings
   D /branches/beta_0_7_branch/kdeedu
   D /branches/beta_0_7_branch/kdeextragear-1
   D /branches/beta_0_7_branch/kdeextragear-2
   M /branches/beta_0_7_branch/kdeextragear-3
   D /branches/beta_0_7_branch/kdeextragear-3/Makefile.am.in
   D /branches/beta_0_7_branch/kdeextragear-3/Makefile.cvs
   D /branches/beta_0_7_branch/kdeextragear-3/README
   D /branches/beta_0_7_branch/kdeextragear-3/configure.in.bot
   D /branches/beta_0_7_branch/kdeextragear-3/configure.in.in
   D /branches/beta_0_7_branch/kdeextragear-3/digikam
   D /branches/beta_0_7_branch/kdeextragear-3/digikamimageplugins
   D /branches/beta_0_7_branch/kdeextragear-3/doc
   D /branches/beta_0_7_branch/kdeextragear-3/filelight
   D /branches/beta_0_7_branch/kdeextragear-3/kcfgcreator
   D /branches/beta_0_7_branch/kdeextragear-3/kconfigeditor
   D /branches/beta_0_7_branch/kdeextragear-3/kdebluetooth
   D /branches/beta_0_7_branch/kdeextragear-3/kdetv
   D /branches/beta_0_7_branch/kdeextragear-3/keurocalc
   D /branches/beta_0_7_branch/kdeextragear-3/kiosktool
   D /branches/beta_0_7_branch/kdeextragear-3/klicker
   D /branches/beta_0_7_branch/kdeextragear-3/kplayer
   D /branches/beta_0_7_branch/kdeextragear-3/pwmanager
   D /branches/beta_0_7_branch/kdeextragear-libs-1
   D /branches/beta_0_7_branch/kdegames
   D /branches/beta_0_7_branch/kdegraphics
   D /branches/beta_0_7_branch/kdeinstaller
   D /branches/beta_0_7_branch/kdejava
   D /branches/beta_0_7_branch/kdekiosk
   D /branches/beta_0_7_branch/kdelibs
   D /branches/beta_0_7_branch/kdemultimedia
   D /branches/beta_0_7_branch/kdenetwork
   D /branches/beta_0_7_branch/kdenonbeta
   D /branches/beta_0_7_branch/kdenox
   D /branches/beta_0_7_branch/kdepim
   D /branches/beta_0_7_branch/kdeplayground-artwork
   D /branches/beta_0_7_branch/kdeplayground-base
   D /branches/beta_0_7_branch/kdeplayground-edu
   D /branches/beta_0_7_branch/kdeplayground-games
   D /branches/beta_0_7_branch/kdeplayground-ioslaves
   D /branches/beta_0_7_branch/kdeplayground-multimedia
   D /branches/beta_0_7_branch/kdeplayground-network
   D /branches/beta_0_7_branch/kdeplayground-pim
   D /branches/beta_0_7_branch/kdeplayground-utils
   D /branches/beta_0_7_branch/kdereview
   D /branches/beta_0_7_branch/kdesdk
   D /branches/beta_0_7_branch/kdesecurity
   D /branches/beta_0_7_branch/kdesupport
   D /branches/beta_0_7_branch/kdetoys
   D /branches/beta_0_7_branch/kdeutils
   D /branches/beta_0_7_branch/kdevelop
   D /branches/beta_0_7_branch/kdewebdev
   D /branches/beta_0_7_branch/kdoc
   D /branches/beta_0_7_branch/kfte
   D /branches/beta_0_7_branch/khtmltests
   D /branches/beta_0_7_branch/klyx
   D /branches/beta_0_7_branch/kmusic
   D /branches/beta_0_7_branch/koffice
   D /branches/beta_0_7_branch/kofficetests
   D /branches/beta_0_7_branch/konstruct
   D /branches/beta_0_7_branch/qt-copy
   D /branches/beta_0_7_branch/quanta
   D /branches/beta_0_7_branch/sysconfig
   D /branches/beta_0_7_branch/valgrind
   D /branches/beta_0_7_branch/www

This commit was manufactured by cvs2svn to create branch
'beta_0_7_branch'.

If you do this

match /branches/beta_0_7_branch/kdeextragear-3/krecipes/
  repository krecipes
  branch 0.7
end match

match /branches/beta_0_7_branch/
  min revision 386536
  max revision 386536
  action recurse
end match

svn-all-fast-export will fail, you'll get an error sayining that '/foo/bar/path' was not found where '/foo/bar/path' is one of the deleted paths in the cvs2svn commit. This is because some paths were deleted in the same commit where you want to do an 'action recurse'. Therefore, to avoid matching the deleted paths you should do an action recurse on each intermediate directory from '/branches/beta_0_7_branch/' to '/branches/beta_0_7_branch/kdeextragear-3/krecipes/' and you should use a final '$' to make sure that the deleted paths will not be considered, thusly:

match /branches/beta_0_7_branch/kdeextragear-3/krecipes/
  repository krecipes
  branch 0.7
end match

match /branches/beta_0_7_branch/kdeextragear-3/$
  min revision 386536
  max revision 386536
  action recurse
end match

match /branches/beta_0_7_branch/$
  min revision 386536
  max revision 386536
  action recurse
end match

[edit] Pedindo Ajuda

Se você topar com coisas estranhas ou não consegue encontrar uma regra para algo que você precisa, você pode falar com a equipe de migração do KDE Git no IRC: irc.freenode.org, #kde-git ou na kde-scm-interest mailinglist


This page was last modified on 19 July 2012, at 16:30. This page has been accessed 1,706 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal