What do we do?

We create on GitHub an automated mirror of the Web3D SVN repository from SourceForge. More precisely, mirror the subdirectory of SVN called www.web3d.org (so we omit the legacy subdirectory from SourceForge), visible on https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/ .

The resulting mirror will be public on GitHub (just like it is public on SourceForge already). It will be available under the https://github.com/x3d/www.web3d.org/ address. Web3D already has https://github.com/x3d/ organization for public GitHub projects.

The repository on GitHub will remain read-only for now. The commits will still be done to SourceForge SVN.

Why? What are the immediate benefits?

Even when GitHub serves only as a read-only mirror, we still get some advantages of GitHub (over SourceForge):

• GitHub seems more popular and respected than SourceForge now.

• Khronos, X3DOM, X_ITE, Castle Game Engine and view3dscene, and many other big projects are already on GitHub.

• We have more ways to access the repository on GitHub (you can download it using GIT client, SVN client, or just as a ZIP).

• We can search in repo using GitHub, we can integrate with GitHub tools for Continuous Integration.

What are the long-term benefits?

In the long-run, the "read-only mirror on GitHub" is only a 1st step in what Michalis is proposing. My long-term proposition is to actually use GitHub for development. That is, commit to GitHub using GIT, use pull requests, and so on. In this sense, the discussed "read-only mirror on GitHub" is only a "demo" for the existing Web3D committers, to see how it would all look like on GitHub.

At that (potential future) time, the repository on SourceForge would change to be a read-only mirror of the GitHub contents.

And then we get the big benefit of GitHub, and the reason why it became so popular:

• We could use GitHub "pull requests", which are a great way to contribute code to projects, much better than sending SVN/GIT patches IMHO. "Pull requests" allow external contributors (that do not have write access to the main repo) to contribute non-trivial changes comforably, by making commits in their own fork. It's a new workflow, and it really makes a huge difference in my opinion -- both in my experience as contributor to projects, and in my experience as author of open-source projects that looks for contributions from other people.

  I very encourage everyone to familiarize with the "pull request", if you've never done it yet. Read about it, GitHub docs, search the Internet, and finally: actually try it out. You're welcome to create testing pull requests to my X3D test files on https://github.com/michaliskambi/x3d-tests/ . You're also free to create your own repositories on GitHub for test purposes.

• And we get other GitHub tools, mostly build on top of the "pull request" mechanics:

  • GitHub proposed edits (which are really just a fancy way to make pull requests without leaving your WWW browser),

  • GitHub web editor (commit directly using your browser, for people who have commit access to repo),

  • GitHub reviews during pull request (which allow to put comments at commits or inline, allow to define a set of reviewers whose input is requested, allow to communicate which changes are required before acceptance and which are neutral comments etc.).

Details about the synchronization

The commits will be synchronized using an automated script https://github.com/michaliskambi/sync2git , which in turn uses git2svn, which is a reliable way to synchronize commits between SVN and GIT. The sync2git script run as a simple cron job. Michalis would run it on his own https://michalis.ii.uni.wroc.pl/ server (it's just private Michalis server, that I maintain for various private and Castle Game Engine-related stuff). It's a simple shell script, and could be set up / moved to any Linux server in the future.

The sync2git script observes SourceForge SVN (as anonymous user), and when it sees a change -- commits it to GitHub (so it has write access to GitHub GIT).

At the first run, all the SourceForge SVN commits are synchronized with GitHub GIT. All the history and authors is preserved, you can browse historical versions, you can run "git blame" etc. The resulting GitHub repository has exactly the same contents (files) as the SourceForge repository.

• Note that SVN "ignore properties" are translated into GIT .gitignore files. They serve the same purpose.

• Note that SVN and GIT have a bit different ideas how to represent a "tag" and a "branch". But this difference doesn't matter, since you never used tags or branches in the current SVN repository.

Any new commits to SourceForge SVN will be automatically synchronized (with max 15-minute delay) to GitHub too.

Note that we also synchronize the commit authors. So e.g. this commit by Don: https://sourceforge.net/p/x3d/code/27615/ is correctly attributed to the account associated with [email protected] on GitHub.

• To do this, Michalis maintains a text file (part of sync2git configuration) that has a mapping SourceForge username => preferred GitHub email address.
• I'll send the contents of this file (for all people that contributed to SVN repo) once the synchronization is done, so you can double-check it.
• If I put the wrong email address there, the commits you did on SourceForge will not be associated with your GitHub account. But that's trivially fixable (including historic commits). Just send to Michalis ([email protected]) your 1. SourceForge username 2. email address of your GitHub account, and I'll add it to the configuration, rerun the import script, and all your commits (past and future) will be associated with your account.

Who/when is going to do this?

Michalis is going to do it once everyone (including Don :) ) accepts.

It's really a quick job. I estimate it will take me ~30 minutes of human work. (Yes, much quicker than writing, or reading, this document :) ). After this, an automated script finishes the 1st synchronization, which may take a couple of hours. For technical details what I'm going to do, see sync2git docs.

I'm going to maintain the sync2git script, and I'm going to maintain the GitHub mirror -- if someone submits an issue, or a pull request, I can redirect him to the Web3D "spec comment" form.

Risks?

None, in my eyes.

The SourceForge SVN is read-only for the sync2git/git2svn operation. We just create a new repository on GitHub.

If you do not find the result useful, you can simply ignore the GitHub repo. It is synchronized automatically with SourceForge SVN. Michalis will watch the GitHub repo for any user submissions (issues, pull requests) and redirect them to Web3D "spec comment" form.

If we decide we don't want this, the repo can be simply removed. If we decide we want to configure it differently, the repo can be recreated using different sync2git/git2svn settings. The "authoritative" repo remains on SourceForge (at least for now).

The end?

I openly admit that my dreams go further :) See the wiki page allow to propose the specification improvements publicly, using something like GitHub pull requests. But that's a discussion for another day, for a more distant future :)