Basic checklist for migrating the PHP Manual from SVN to Git

phpdoc-svn-git-checklist.md

PHP Manual's SVN->Git transition status

Theory/assumptions

Most of the current workflow remains unchanged. The notable changes include:

1. Switching from SVN sequential revision number in EN-Revision to Git hashes. It means we need to run the migration script on each of the translations to port that EN-Revision value and make it understandable for the tooling
2. Dropping the use of $Revision$ (so whole top XML comments) in the English documentation sources. All the tools get that information from git log -1 and it wouldn't make sense to keep it in file if it no longer updates itself
3. Checking whether file is up to date is still easy. We just check rev == en-rev. Comparing sequential SVN revisions gave us no benefits over that because (contrary to CVS where those were all updated manually) how big the difference is mean nothing
4. Calculating how big is the difference can be thus done using same methods as now (e.g. comparing size like on doc.php.net). Other options for that include counting days distance between the commits or the commit count itself.
5. The one repository for one language (+ doc-base) will be kept
6. However, we cannot use SVN externals anymore. It means that in order to set up actual environment for translating, one will need to clone a few repositories separately. My [sobak's] suggestion is to provide some setup.php script in the doc-base repository and advising to use that after one simple clone.
   • The other issue I can see is missing doc-all. Because of that it's hard to download all the translations. For me, the easiest option would be to create some meta-file listing all translations inside the doc-base repository. Then scripts like setup.php (or some others e.g. on doc.php.net) could iterate over that list and process all of the translations. The obvious disadvantage is one more place to keep in sync, though.

Hopefully definitive todo

1. doc.php.net [ALMOST DONE - implemented with option c]
   1. Update the revcheck.php script (includes internal conjobs/shell scripts etc)
      • providing diff for the files
        1. GitHub - displays complete comparision between two commits, which cannot be limited to the single file view. We can of course create a link to the specific file on such page but that page can be very big and sometimes file diff will not be loaded without confirming
        2. git.php.net - gitweb can display a comparision for the single file
        3. custom solution - we can build simple script on the doc.php.net (which already needs Git repos in place anyways) in case git.php.net's design will be limiting; I think translators could benefit even from that simple changes like dropping actual +/- on the beginning of each line (personally I very often wanted to just copy-paste something from such diff and work on that in the editor)
      • implementation details: the one disadvantage of current implementation is considerably longer time needed to regenerate doc.php.net's revcheck database; even though according to my tests it takes up to 10x longer, it will not be that much of a difference - the reason is because it's mostly caused by the need of calling git log -1 on each of English files and I'm currently testing just on en + de langs - thus the final difference will be smaller (affecting only one of many languages, not the half like now); also, a link for code review will be provided before the switch
   2. Update the tutorial
2. doc-base repository [DONE]
   1. Review all the scripts, one by one, and either migrate to Git where needed or drop where keeping does not make sense anymore
      • implementation details: depending on the actual migration path we'll take this will be either a branch on PHP.net's Git doc-base repository or branch created on our own fork which will be then used to generate a patch to be applied on doc-base when migrated; a link for code review will be provided before the switch
   2. Migrate current svn:ignore to .gitignore
3. PhD [DONE - it seems no modifications are required]
   1. Review the code to make sure it has no dependencies on the SVN, update if needed
   2. Update the documentation
4. edit.php.net [HOLDING OUT FOR A HERO]
   1. Decision needed: do we want to have edit.php.net ported before the migrations happens?
5. rsync box/systems repository
   1. Switch fetching documentation sources from Git
6. web-php
   1. Switch "edit" links in the documentation to GitHub edits or add it besides edit.php.net links - depends on the decision regards the editor
7. PHP Manual
   1. Look for pages mentioning SVN and update accordingly
   2. Drop <!-- Revision: $Revision$ --> comments in English sources
      • or maybe we don't want to do this, as it would require to re-check EN-Revision tags for every single translated files and bumping it where appropriate?
   3. Create .gitignore for each of the repositories to reflect current svn:ignore
   4. Can we somehow benefit from .gitattributes?
8. Windows CHM box
   1. Probably needs an update to fetch files from Git
9. Mailing lists
   1. Probably php.doc.cvs needs some switch to deliver emails based on Git repository
   2. Same for all php.doc.LANG lists
   3. Setting up pull request notifications[?]
10. Announcements
    1. PHP.net homepage - I know we rarely post such internal upgrades there but I think it is worth sharing; can also engage some new contributors
    2. Announcement on php.doc and each of php.doc.LANG mailing lists
11. more?

Side notes

• adding Travis CI with configure.php to each of documentation repos seems like a natural and benefical future scope
• can/should we kill very outdated translations? This would give us the benefit of removing some really old hacks on doc.php.net and other tooling for solutions that we no longer use (like /functions directory at the translation root or <file /> entries in translation.xml)

Theory.5: before we create a setup.php script, we need a detailed instruction on how to get startet. That should go into each repos README like https://github.com/phpdoctest/doc-base/blob/master/README.md . Putting that then into code is easy.

I definitely agree. However, I'd like to put it on doc.php.net/tutorial and link it from there. My thought when reworking this tutorial back then was to finally have one place containing all the informations related to documentation environment etc.

Todo.2 is also done. I reviewed all the scripts and tried to port them from SVN to git. Though I would definitely like a second set of eyes on that!

Awesome! I'll change the doc

Apart from that I'd say we need to find a day for the switch. I'D rather have a clean cut and that is best done on one day (or a weekend…) So during that day no Repo-Access is possible and after that day SVN should be read only. And before that I'D like to have a test-run. Christmas is coming but I'm not sure we'll manage to do it in that short amount of time…

IMO, we can safely run git-svn svn2git first, as well as create branches in all of the repos for the review. Then, however, I agree that we need a clean cut, like you said (e.g. for running SVN-Rev to git hashes conversion on translations). The thing I'm worried about the most is that we'll need a bunch of people coordinated that day. For example, I have an access to doc.php.net/docs.php.net box but creating GitHub repos, switching mailing list noficitations/switching CHM generation on Windows box is out of my possibilities. We should try to gather a team for that day, choose some instant communication channel (probably some IRC) and get to work

Thanks for the input!