Editing Github Migration
From BRL-CAD
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
| Latest revision | Your text | ||
| Line 66: | Line 66: | ||
* no-diff commits result in no commit in git | * no-diff commits result in no commit in git | ||
** for example 66607 merged from branch, no-op changes to include/bu/defines.h | ** for example 66607 merged from branch, no-op changes to include/bu/defines.h | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Version Control History == | == 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.) | * 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.) | ||
| Line 93: | Line 81: | ||
* Test checkout from the new repositories on github. | * Test checkout from the new repositories on github. | ||
* Announce the change on the email list and update the website links. | * 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. | + | * Ensure any testing infrastructure is updated to connect to the new git repository rather than the (now static) SVN repository. |
| − | + | IMPORTANT: We need to set up protections for the historical branches in Github: https://docs.github.com/en/github/administering-a-repository/configuring-protected-branches - without this, we can lose history if anyone accidentally deletes old branches whose commits are not referenced by any undeleted branches. (Unfortunately Github doesn't yet support protecting tags (https://github.community/t/feature-request-protected-tags) but if/when that feature is added we will also want to use it.) | |
| + | 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 == | == 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: | |
* <s>README, INSTALL and HACKING - some of the HACKING procedures may need to be updated to reflect github's workflow.</s> | * <s>README, INSTALL and HACKING - some of the HACKING procedures may need to be updated to reflect github's workflow.</s> | ||
| Line 106: | Line 99: | ||
* <s>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.</s> | * <s>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.</s> | ||
| − | + | We'll want to put together some usage notes on how to work with Git+BRL-CAD. Following history past renames is a problem (See https://marc.info/?l=git&m=123333586414420 and https://marc.info/?l=git&m=123333626615117) and ideally we'd like devs to move files first and commit the move before making any changes to allow us to follow local file history more easily. Git philosophically does not track per-file history, which is unfortunate given BRL-CAD's historical practices - there are often situations where following a file's individual history is the most efficient way to understand why a subset of the code base is the way it is today. We have dealt with this in the conversion by automatically inserting preliminary move commits to allow git log --follow to work with maximal efficiency, but there isn't a practical way to enforce this once we start using git itself - there's no option to explicitly track file moves and without it it is up to individual developers to remember to rename, commit, and then edit. This is especially hard since renames without file editing often break the build, and the reflex is to fix the build before committing... | |
== User Workflow Updates == | == 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: | |
* <s>UPDATE - after discussion, good reasons not to do this, skipping. Add a .gitattributes file to the repository to establish default behavior for various file types - a prototype is at misc/repoconv/gitattributes.</s> | * <s>UPDATE - after discussion, good reasons not to do this, skipping. Add a .gitattributes file to the repository to establish default behavior for various file types - a prototype is at misc/repoconv/gitattributes.</s> | ||
* <s>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.</s> | * <s>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.</s> | ||
* <s>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.</s> | * <s>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.</s> | ||
| + | |||
| + | 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/ | ||
