Moving the documentation to git: Current status

Andreas Heigl <[email protected]> Mon, 23 Dec 2019 19:03:05 +0100
Newsgroups	gmane.comp.php.documentation.general
Message-ID	<[email protected]>
Hi everyone.

I have been a bit quiet lately due to work and family as well as
wrapping my head around different issues with the current approach to
moving the docs from SVN to git.

But it looks like the first hurdle is done!

What happened so far:

The process has been established to move the documentation continuously
from SVN to git. For that Rasmus has set up a DO-Dropplet that every 2
hours fetches the latest Changes from the SVN repository and rebases
them into a git-repo using git-svn rebase. That is currently done for
all languages that have been changed within the last 2 years (which
means (in alphabetical order): de, en, es, fr, it, ja, pl, pt_BR, ro,
ru, tr, uk and zh).

During that process a file is created and then updated that contains the
revision of the english base-file that each file is based on. That
information so far is kept inside the translated file in a comment with
the content "en-revision: [revision-number]". The first tries to replace
this revision number inside the file with the commit-hash were not
working as that meant modifying the file so that in a future rebase the
change was not known to git-svn and a rebase could not be done.
Therefore I moved that information out into a separate file. The
advantage is now, that the process of generating the statistics about
the translation status now only needs to read this single file instead
of each single file to retrieve the hash (or revision number) of the
english base-file.

The next step would now be to automatically push those changes to the
corresponding repo at git.php.net. For that to work though there are two
things to be solved:

1. The git-repos for the languages es, fr, it, ja, pl, pt_BR, ro, ru,
tr, uk and zh need to be created.
2. We need to decide how to continue with the repos for en and de. As
far as I understood Peter has created a shallow clone of the english
repository there. That repos master-branch would need to be overwritten
in the process as the git push would need to do a force-push as changes
to the branch can not automatically be merged. That would become far too
complex. Also the german repo seems to be updated somehow... How will
the process be here?

As soon as that is solved and done, the background processes need to be
modified so that they use the git-repos as the single source of truth
and not the SVN repo. That means two different things mainly: The
building of the actual documentation and the creation of the meta-docs
that contain the information about the status of the different documents
in relation to the base-document.

I will be working on those modifications in parallel so that – once the
todos are resolved – the process of moving the background processes can
be started ASAP.

Once the background processes are modified and deployed, the SVN can be
switched to ReadOnly and all changes can go in via git.

The workflow with git would change a bit in several ways from the
current workflow:

* Every language lives in its own repository. So you would need to clone
two repositories: the english one and the one you want to translate.
Drawback, you need to clone multiple repositories if you want to
contribute to multiple languages, Advantage though is, that you only
need to clone one repository if you want to contribute to one language.
* The reference to the english base-file is not kept inside the
translated file any more but in a separate file. Remembering to modify
that file might be the most challenging part. Perhaps having a pre-push
hook, that checks that this special file is modified according to the
modified files can make sense.
* The new process uses git, so that contributions via a github mirror
are now possible so that the same processes can be used for
contributions via github PRs that are currently used for the
PHP-Sourcecode. So contributions from non-regulars need to be handled
differently. This raises the question who will create those processes when?

Did I forget anything? Feel free to ask!

Looking forward to your feedback.

Cheers

Andreas

PS: The process is documented at
https://github.com/phpdoctest/meta/wiki/Current_Ideas
PPS: salathe: I'd be especially grateful for your feedback

-- 
                                                              ,,,
                                                             (o o)
+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl                                                       |
| mailto:[email protected]                  N 50°22'59.5" E 08°23'58" |
| http://andreas.heigl.org                       http://hei.gl/wiFKy7 |
+---------------------------------------------------------------------+
| http://hei.gl/root-ca                                               |
+---------------------------------------------------------------------+
signature.asc (application/pgp-signature, 833 B)