Editing Github Migration

== Migrating from Sourceforge to Github ==

As BRL-CAD migrates its hosting platform from Sourceforge to Github, there are a number of complex steps that will need to play out.

Currently we are in the preliminary stages, exploring available tools, conversion techniques and identifying the necessary steps.  Once we are ready, a series of events will occur in succession to finalize the move.  This page is intended to identify and organize those steps so the migration can proceed in an orderly manner.

== Version Control History ==

The most difficult and important of the conversion steps is the migration of BRL-CAD's version control based source code history from Subversion to Git.  The process as it is finalizing (documented in detail in the BRL-CAD repository itself in the misc/repoconv sub-directory) will take a number of weeks to run, and will proceed roughly as follows:

* Finalize the email addresses and names used to map Subversion accounts to Github accounts.  (Once the final conversion begins, these user identities are "locked in" to the git history and cannot easily be changed - they must be fully ready before the process begins.)
* Perform the initial Subversion -> Git process as outlined in misc/repoconv.  (Est. 2-3 weeks to complete, once begun.)
* Lock the Sourceforge Subversion repository into read-only mode.
* Run a final update to pick up any commits made during the initial conversion process.
* Run the svn-fast-export process to generate the secondary git repositories for projects (geomcore, rt^3, etc.) other than the primary BRL-CAD repo in the Subversion repository on sourceforge.net/p/brlcad.  (This process is much faster than the main conversion, and shouldn't take more than a few hours.)
* Upload all of the repositories to the github BRL-CAD project.
** See the NOTES file in misc/repoconv for more details on this process.
** In particular, the git notes with SVN repository conversion information will need a separate upload step. 
** Once "live", we can no longer alter the git history without potential impact to other developers - a git history rewrite (which any change will require) is guaranteed (unlike SVN) to be user visible and disruptive.
* Test checkout from the new repositories on github.
* Announce the change on the email list and update the website links.
* Ensure any testing infrastructure is updated to connect to the new git repository rather than the (now static) SVN repository.

For completeness, the plan is to create a Git repository that preserves the CVS and SVN repository contents in their final states.  The original CVS history proved important when doing the Git conversion, and should another attempt be made someday to migrate BRL-CAD's history to a new VCS it may well prove useful to have the original early data available, as opposed to the (inevitably) lossy Git conversion of that data.  (A quick test indicates such a repository would be about 1.7G in size.)  For best behavior the repo should probably have a .gitattributes file identifying all file types as binary files.

== Secondary Information ==

Sourceforge also stores user reported issues, patches, and other secondary data we would like to migrate.  This migration has been less thoroughly explored, but it appears https://github.com/cmungall/gosf2github may be a good starting point.

== In-Repository Updates ==

Once the primary VCS migration is complete, there are a number of features and instruction files in BRL-CAD itself that will need to be updated to reflect the new location and tools.  In particular:

* README, INSTALL and HACKING - some of the HACKING procedures may need to be updated to reflect github's workflow.
* The distcheck repository check target has some awareness of subversion in its verification steps.  Preliminary work has been done to shift this logic to use Git - that work must be finalized and tested.
* Once the VCS conversion is complete, remove the misc/repoconv directory - it will no longer be needed and the information it encodes will be preserved in the VCS history itself.

== User Workflow Updates ==

Over the years a number of convenience setups have been worked out for Subversion, such as the mime type defaults.  Once we convert to git, we want to establish similar defaults and standards in Git.  This will be ongoing, but already known:

* Add a .gitattributes file to the repository to establish default behavior for various file types - a prototype is at misc/repoconv/gitattributes.
* Utilize github workflows to set up cross platform CI using github's infrastructure.  Some preliminary testing has been done in throw-away repositories, and once a working setup has been identified we will enable it in the main repository.
* Set up a recommended user git config that will establish some semi-standard convenience aliases - in particular, for working with the historical information encoded in the git notes.

We need to investigate available hooks in git for enforcing standards, procedures, etc for pull requests and commits.

== Email lists ==

Email is currently hosted on sourceforge - need to decide what to do about migrating it (or not...).  CMake recently switched to discourse - https://discourse.cmake.org/