Archive:Webteam/Git proposal

=Abstract= Our use of SVN for control of webteam code and data is limiting developer involvement and complicating maintenance. This document proposes using Git to simplify administration and contribution. Herein, 'code' refers to the contents of the website revision control system, which is both code and other documents.

=Target Architecture= Git's architecture does not enforce any one repository as a master, although usage in software projects typically relies on a "blessed" repository administered by the project team. This repository has nothing special about it other than people refer to it as the standard.

We can put the blessed repository somewhere public and allow a select set of users to manipulate it directly. Other developers can still clone it and make edits, but would need to push to their own public repository and issue a merge request, which would be served by one of the authorized developers. This is more open than our current model, which does not allow non-authorized developers to commit code at all. (With our svn setup, anyone can do a checkout.) Ideally, each merge consists of a single feature/bugfix which allows for fairly simple handling by administrators.

The server's running code is simply a local repository that tracks the blessed one. It can update itself from the blessed repository whenever necessary, either chronologically, manually, or perhaps by a trigger in the site's admin interface. If we decide to allow edits to the code from the admin interface, such edits can be committed to the local repository and pushed back up to the master without issue, and, with some effort to write the scripts, could even keep such changes live, and update from the master without pushing back if we want to do that.

Free (and also libre) services exist to host public repositories like the blessed repository that we'll need. Notably Gitorious (libre) and Github (only free, but has more features), which both allow users to host their own private repositories and issue merge/pull requests (the two are synonymous). They also both allow users to handle their ssh keys for uploading to their public repositories, which means that we don't have to do that on our own server, and allow the repository owner to mark specific other users as contributors to their repository (here, the blessed repository) without having to know anything about their ssh keys.

We do _not_ need to run a git daemon on the server if we go with external hosting. External hosting also gives us a web view of the code.

Ultimately, it would be ideal that a checkout of the repository would give you a runnable instance of the fc.o site that you could play with, just like checking out Diaspora gives you a runnable instance of Diaspora. This is a far-term goal and not the goal of this design document.

Sample Authorized Developer Workflow

 * 1) git checkout master point to the master branch locally, which typically is used to track upstream without edits
 * 2) git pull upstream to get changes from the master repository
 * 3) git checkout -b hot_new_feature to create a feature branch and check it out.  All the edits go in this branch.
 * 4) hack
 * 5) git add [files]; git commit to commit changes.  This and the preceding step may be repeated any number of times.
 * 6) if new edits have occurred upstream,  git pull upstream master; git rebase master  will pull them into master and re-apply the existing commits in our branch on top of those changes, offering the chance to fix any conflicts along the way.
 * 7) with the feature completed, git checkout master; git merge hot_new_feature; git branch -d hot_new_feature to pull the changes into master and delete the branch.  This should not cause conflicts because master never contains any commits that the branch does not.
 * 8) git push upstream master to push the changes to the blessed repository
 * 9) If we want to commit those changes to the server now, log in to the server, navigate to its repository and git pull origin to fetch the changes and apply them.

Sample Unauthorized Developer Workflow
Steps 1-6 as above. Unauthorized developer also maintains a public repository, here referred to as origin</tt>(authorized developers can too!).
 * 1) git push origin hot_new_feature</tt> to push specifically this branch.
 * 2) Contact an authorized developer via merge request or email, telling them the location of their public repository and the branch to merge

The authorized user then pulls the branch from the public repository, vets it, merges it with his master and pushes it to the blessed repository.

=Migration Plan= Migration is pretty simple, but we need to create a file to map svn users to git users (email addresses, make sure your git is configured well!). This is further explained at

We migrate the repository to a local copy, upload the copy to our chosen host, and then clone it down onto the server, and away we go.

=Potential Problems= We probably shouldn't track the database in the repository because non-text files are handled poorly.

Git may be confusing to users new to dvcs. This is a major problem, actually, but I'm not sure svn is really much easier.

There are many sub-projects currently. Splitting them out of git is obnoxious because history needs to be re-written.