Sobak/phpdoc-svn-git-checklist.md

## phpdoc-svn-git-checklist.md

      
    Raw
  

              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:

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
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
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
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.
The one repository for one language (+ doc-base) will be kept
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


doc.php.net [ALMOST DONE - implemented with option c]

Update the revcheck.php script (includes internal conjobs/shell scripts etc)

providing diff for the files

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
git.php.net - gitweb can display a comparision for the single file
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


Update the tutorial


doc-base repository [DONE]

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


Migrate current svn:ignore to .gitignore


PhD [DONE - it seems no modifications are required]

Review the code to make sure it has no dependencies on the SVN, update if needed
Update the documentation


edit.php.net [HOLDING OUT FOR A HERO]

Decision needed: do we want to have edit.php.net ported before the migrations happens?


rsync box/systems repository

Switch fetching documentation sources from Git


web-php

Switch "edit" links in the documentation to GitHub edits or add it besides edit.php.net
links - depends on the decision regards the editor


PHP Manual

Look for pages mentioning SVN and update accordingly
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?


Create .gitignore for each of the repositories to reflect current svn:ignore
Can we somehow benefit from .gitattributes?


Windows CHM box

Probably needs an update to fetch files from Git


Mailing lists

Probably php.doc.cvs needs some switch to deliver emails based on Git repository
Same for all php.doc.LANG lists
Setting up pull request notifications[?]


Announcements

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
Announcement on php.doc and each of php.doc.LANG mailing lists


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)