Changes between Initial Version and Version 1 of UsingGitForDevelopment


Ignore:
Timestamp:
05/09/13 09:36:03 (9 years ago)
Author:
sc
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UsingGitForDevelopment

    v1 v1  
     1= Using Git for Puzzlebox Orbit software development = 
     2 
     3== Git Workflow == 
     4 
     5[http://git-scm.com/ Git] is a popular [http://en.wikipedia.org/wiki/Revision_control revision control] system, written by [http://en.wikipedia.org/wiki/Linus_Torvalds Linus Torvalds] when he decided no existing solutions (such as [http://subversion.apache.org/ Subversion], also popular with Open Source developers) were suitable for maintaining the Linux kernel. 
     6 
     7The basic purpose of any versioning system is to allow specific points in ongoing development to be recorded and stored, with brief notes describing what was changed. If it was later discovered that some of the changes resulted in breaking another function of the program, each change which was "committed" could be rolled-back one by one until it was found and fixed. Several individual commits are expected in the course of developing any major new feature. This sequence also provides an "undo" capability to a developer if they find they have reached a dead-end and want to go back to an earlier "clean" version of their code. 
     8 
     9Another key feature of Git and its brethren is the ability to create "branches" from a specific point or software version. A branch arranges all of their work to be isolated from the main repository, permitting them to work on their code and test their progress without affecting other developers who are working on their own features simultaneously. Individual changes can be committed to their branch and no one else will see it until the branch is finally "merged" back into the main tree. This "merging" process will require that any conflicts be resolved before it is accepted, meaning that if two people have been working on the same file or especially same section of code, the last one to commit (or merge) their changes would have to review and adjust for the latest version in the repository. 
     10 
     11All of these features are present in other systems, however the unique benefit of using Git is that individual commits can happen on the developer's local computer. They are only uploaded and inserted back into the central repository when the "push" command is used. This permits more flexible independent development, including the ability to commit changes while offline. 
     12 
     13 
     14== Example Use == 
     15 
     16Let's consider a developer wishing to implement the "Hover Mode" feature from the Puzzlebox Orbit Roadmap: 
     17 
     18[http://orbit.puzzlebox.info/tracker/milestone/Hover%20Mode Hover Mode] 
     19 
     20 
     21The first step would be to "clone" the Git repository for the Puzzlebox Orbit source code. (Other systems such as Subversion use the term "checkout") 
     22 
     23Next, since this is a new major feature, the developer should create a new branch, perhaps calling it "Hover Mode" to match the roadmap name. Once created they will need to update their local working copy to use the new branch. 
     24 
     25The developer would then begin about making changes to the code, specific to this feature. They might start by creating a new "Hover" button in the GUI and link it to a dummy routine which prints to log or reports to the screen when it has been successfully activated. Once this simple change is working, that would be a good point to commit changes to their branch. As soon as the "commit" command is issued, a text editor will appear asking the user to log what was changed. Good practice would be to describe what was changed in each file, with only one line per summarized change. These messages become crucial later when trying to trace where an error might have been made, especially for future developers trying to understand one another's code. 
     26 
     27At any given point in the process, the developer may wish to "push" their changes back up to the server. This might be when they are preparing to change which computer or environment they are working from, or if they simply wish to have a backup copy made of their changes. Because they are working on their own branch, there is no drawback to "pushing" code back to the central server and this is recommended if connectivity is available. 
     28 
     29Finally, when the feature is finished and working, and the developer has both "committed" and "pushed" all changes back into their branch on the central server, they should begin the "merge" process. If no one else has been working on the same components at the same time, there should be no complications to this process. However if someone else has made changes to any of the same files, and especially to the same sections of code, it will be necessary for the developer to review all of the new changes and adjust their code before the conflicts will be resolved and the merge can be completed. This is another point where having good commit logs is beneficial to all. 
     30 
     31 
     32== Git Commands == 
     33 
     34 * [http://cworth.org/hgbook-git/tour/ Introductory Guide] 
     35 
     36 * Checkout source from Puzzlebox repository 
     37{{{ 
     38git clone ssh://<username>@puzzlebox.info/repo/orbit 
     39}}} 
     40 
     41* Get information about git repostiory 
     42{{{ 
     43git remote show origin 
     44git remote -v. 
     45}}} 
     46 
     47 * [http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Branching] 
     48 
     49 * Create new branch 
     50{{{ 
     51git branch "<new branch name>" 
     52}}} 
     53 
     54 * Change to new branch 
     55{{{ 
     56git checkout "<branch name>" 
     57}}} 
     58 
     59 * Commit changes 
     60{{{ 
     61git commit 
     62}}} 
     63 
     64 * Change back to master branch 
     65{{{ 
     66git checkout master 
     67}}} 
     68 
     69 * Merge branch 
     70{{{ 
     71git merge "<branch name>" 
     72}}} 
     73 
     74 * Remove branch 
     75{{{ 
     76git branch -d "<branch name>" 
     77}}} 
     78 
     79 * Push changes to server 
     80{{{ 
     81git push 
     82}}}