QESTNET Internal:Developer Git etiquette - Revision history

David.lucas at 07:12, 15 July 2015

2015-07-15T07:12:57Z

←Older revision		Revision as of 07:12, 15 July 2015
Line 129:		Line 129:

	==Git workflow==		==Git workflow==
			===Starting a new bug/change request===
	*Checkout the development branch (e.g. alien) that the bug/change request will be added to.		*Checkout the development branch (e.g. alien) that the bug/change request will be added to.
	**Pull or fetch from github the latest of the branch and ensure that your local copy is at the head (git pull origin alien or git fetch origin alien and git merge --ff-only origin/alien).		**Pull or fetch from github the latest of the branch and ensure that your local copy is at the head (git pull origin alien or git fetch origin alien and git merge --ff-only origin/alien).

David.lucas at 07:12, 15 July 2015

2015-07-15T07:12:21Z

←Older revision		Revision as of 07:12, 15 July 2015
Line 1:		Line 1:
	~~== Initial Setup ==~~
	*Signup for a GitHub account www.github.com. Tell someone your username so they can add you to the appropriate SpectraQEST team
	*Download and install Git from http://git-scm.com/download. Windows has two possible ways to run git: choose msysgit instead of Cygwin. When installing, choose all the options that they recommend for Windows development. Install again to something like “C:\Program Files (x86)\Git”.
	**You will be prompted about line ending conversions at some point. Use the auto-convert option, I think it’s the first option. It should produce the line “autocrlf = true” in the default config: “C:\Program Files (x86)\Git\etc\gitconfig”.
	*You can now:
	**Run the Git console using Git Bash, a shortcut (quotes included): "C:\Program Files (x86)\Git\bin\sh.exe" --login –i
	**Run Git GUI using this entire command (quotes included) in a shortcut: "C:\Program Files (x86)\Git\bin\wish.exe" "C:\Program Files (x86)\Git\libexec\git-core\git-gui"
	**A shortcut for both of these should have been created in the Start Menu automatically.
	*Your global Git configuration file “.gitconfig” is found under “C:\Users\Your.Name\.gitconfig”. Setup your username and email by using the following commands in Git Bash:
	**git config --global user.name “Your name”
	**git config --global user.email your.name@spectraqest.com
	*Download and install KDiff3 (this will be used as the merge tool for changes that can’t be automatically merged. Can maybe make it work with WinMerge, but haven’t tried.) This can be installed to the default location, something like “C:\Program Files (x86)\KDiff3”.
	*Setup Git to use KDiff3 and optionally Notepad++ as your editor instead of Vim by editing the global .gitconfig file. I find it easier to edit manually in Notepad++ than using the console. Here’s an example of a config file:
	~~<nowiki>[core]~~
	~~editor = "'C:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -nosession -noPlugin"~~
	~~autocrlf = true~~
	~~[user]~~
	~~name = John Meegan~~
	~~email = john.meegan@spectraqest.com~~
	~~[merge]~~
	~~tool = kdiff3~~
	~~[mergetool "kdiff3"]~~
	~~path = c:/Program Files (x86)/KDiff3/kdiff3.exe~~
	~~[diff]~~
	~~tool = kdiff3~~
	~~[difftool "kdiff3"]~~
	~~path = c:/Program Files (x86)/KDiff3/kdiff3.exe</nowiki>~~
	*Set up your public key: http://github.com/guides/providing-your-ssh-key . Note that the ~ directory in Git Bash corresponds to “C:\Users\Your.Name\”, so your SSH public key can be found in “C:\users\Your.Name\.ssh\id_rsa.pub” after you’ve generated it.
	**By this point you will have a GitHub account and password, a private and public SSH key, and a password to access your private SSH key. This last password is just in case someone steals your computer, they cannot access your private key without a password. This prevents them from accessing anything you use your key for, such as GitHub, once you have added your public SSH key to GitHub.
	*Make the folder “C:\dev\” on your C Drive for development work.
	*Get a Git repository from GitHub via something like the following (note the URL comes from GitHub and changes depending on the project):
	**cd /c/dev/
	**git clone git@github.com:spectraqest/qestnet.upgrade.git
	*That’s pretty much it. There are plenty of tools you can try out to assist with using Git if you wish. Two of the most popular are:
	**GitHub for Windows: https://windows.github.com
	**Atlassian SourceTree: http://www.sourcetreeapp.com/

	== How to "git" started ==		== How to "git" started ==
	===Understanding Git===		===Understanding Git===

David.lucas at 07:03, 15 July 2015

2015-07-15T07:03:22Z

←Older revision		Revision as of 07:03, 15 July 2015
Line 148:		Line 148:

	===Merge vs Rebase:===		===Merge vs Rebase:===
	~~<nowiki>~~
	Merge joins 2 branches together:		Merge joins 2 branches together:
			<nowiki>
	A---B---C branch 2		A---B---C branch 2
	/ \		/ \
	D---E---F---G---H--- branch 1		D---E---F---G---H--- branch 1
			</nowiki>

	Rebase (based on the above) applies the changes for one branch on top of another:		Rebase (based on the above) applies the changes for one branch on top of another:
			<nowiki>
	D---E---F---G---H---A---B---C--- branch 1, branch 2		D---E---F---G---H---A---B---C--- branch 1, branch 2
	</nowiki>		</nowiki>

David.lucas at 07:01, 15 July 2015

2015-07-15T07:01:23Z

@@ Line 50: / Line 50: @@
 <br><br>
 The main non-intuitive thing at first with Git Bash is that path names would be described like /c/dev/ and not “c:\dev\”.
 ===How do I check out a file? (and branching)===
 Two major points of difference with VSS here. One, individual files are not checked out, rather the entire tree is. Two, “checking out” really means switching to another branch. Though Git has a “checkout” command, it is not really like the VSS checkout at all.

David.lucas at 06:59, 15 July 2015

2015-07-15T06:59:35Z

←Older revision		Revision as of 06:59, 15 July 2015
Line 58:		Line 58:
	<br>		<br>
	Don’t ever work directly on the stable branch, for the obvious reason that it means you’re whacking new stuff directly into a branch that is supposed to be stable. Instead make your own branches under the dev branches as required and then, when you’re happy with it, merge it into the dev branches. More on the workflow later.		Don’t ever work directly on the stable branch, for the obvious reason that it means you’re whacking new stuff directly into a branch that is supposed to be stable. Instead make your own branches under the dev branches as required and then, when you’re happy with it, merge it into the dev branches. More on the workflow later.
	~~<br><br>~~
	===App.config / web.config files===		===App.config / web.config files===
	As suggested by Lief a while ago, there’s also a better way to separate our app.config files, which I thought would go well with new source control. The technique is shown in the test-repository-net application on GitHub, though it’ll take a little bit of work to do it in Hive and I won’t worry about doing it in the 0.7 branch.		As suggested by Lief a while ago, there’s also a better way to separate our app.config files, which I thought would go well with new source control. The technique is shown in the test-repository-net application on GitHub, though it’ll take a little bit of work to do it in Hive and I won’t worry about doing it in the 0.7 branch.
	<br><br>		<br><br>
	Basically, it allows us to store prod / test versions of configuration in source control, but allows our local development environment to use config that’s not in source control.		Basically, it allows us to store prod / test versions of configuration in source control, but allows our local development environment to use config that’s not in source control.
	~~<br><br>~~
	===How do I check out a file? (and branching)===		===How do I check out a file? (and branching)===
	Two major points of difference with VSS here. One, individual files are not checked out, rather the entire tree is. Two, “checking out” really means switching to another branch. Though Git has a “checkout” command, it is not really like the VSS checkout at all.		Two major points of difference with VSS here. One, individual files are not checked out, rather the entire tree is. Two, “checking out” really means switching to another branch. Though Git has a “checkout” command, it is not really like the VSS checkout at all.
Line 72:		Line 70:
	<br><br>		<br><br>
	Let’s say you’re working on a change to Program.cs, issue #5000. You might checkout a new branch just for working on that:		Let’s say you’re working on a change to Program.cs, issue #5000. You might checkout a new branch just for working on that:
	~~<br><br>~~
	git branch 5000_program_fix		git branch 5000_program_fix
	git checkout 5000_program_fix		git checkout 5000_program_fix
	~~<br><br>~~
	(The above two commands can also be done with git checkout –b 5000_program_fix)		(The above two commands can also be done with git checkout –b 5000_program_fix)
	<br><br>		<br><br>
Line 135:		Line 131:
	I need some cutting edge code that someone else is developing but which they haven’t pushed to the main repository. Can I get it?		I need some cutting edge code that someone else is developing but which they haven’t pushed to the main repository. Can I get it?
	Yes, you can pull from anyone’s repository, but I’m still working on the details of what’s required to allow our repositories to access each other. In the meantime, you could get the other person to push their branch up to the GitHub server and then you can pull from it.		Yes, you can pull from anyone’s repository, but I’m still working on the details of what’s required to allow our repositories to access each other. In the meantime, you could get the other person to push their branch up to the GitHub server and then you can pull from it.
	~~===Git workflow===~~
	~~The basic workflow I’d suggest for now is:~~
	~~#Get the latest code if you think you need it. (git pull)~~
	~~#Make sure you’re in the appropriate stable / dev branch (git checkout dev)~~
	~~#Create a new branch (git branch fix_name)~~
	~~#Checkout the new branch (git checkout fix_name)~~
	~~#Make the required changes and test. Feel free to commit as you go.~~
	~~#Review the files that you’ve changed, using git status and git diff.~~
	~~#Add the modified files to the index and commit with a good message. (git commit –a –m ‘Commit message.’)~~
	~~#Merge the fix into the development stream. (git checkout dev / git merge fix_name)~~
	~~#Resolve any merge issues.~~
	~~#Push the dev stream to the github repository. (git push origin dev)~~

	There’s a huge amount of flexibility in how we can do the workflow, so what I’ve proposed is just a start. Later, once we’re used to the basic workflow, we can do things to ensure a nice commit history (using git rebase and/or git commit --squash) and other things that I’m not all that familiar with yet.
	===Where’s my Tools > Options menu?===		===Where’s my Tools > Options menu?===
	You have Git configuration options at the individual repository level, or at a global level (i.e. applies to all repositories). These are stored in configuration files, but are most easily accessible via the command line. For example to see all settings applying to the current repository:		You have Git configuration options at the individual repository level, or at a global level (i.e. applies to all repositories). These are stored in configuration files, but are most easily accessible via the command line. For example to see all settings applying to the current repository:
Line 195:		Line 177:
	This is most useful when you do a “git fetch” and discover someone else has pushed work up before you have. You then reapply your changes to the end of the history before pushing to GitHub.		This is most useful when you do a “git fetch” and discover someone else has pushed work up before you have. You then reapply your changes to the end of the history before pushing to GitHub.

	== ~~Starting on a new bug/change request~~ ==		==Git workflow==
	*New branch		*Checkout the development branch (e.g. alien) that the bug/change request will be added to.
	**Checkout the development branch (e.g. alien) that the bug/change request will be added to.		**Pull or fetch from github the latest of the branch and ensure that your local copy is at the head (git pull origin alien or git fetch origin alien and git merge --ff-only origin/alien).
	**Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.
	**Create a new branch using the bug/cr and some form of descriptor as the name (e.g. cr4321-tv-map or bug1234-tv-map-ucs).		**Create a new branch using the bug/cr and some form of descriptor as the name (e.g. cr4321-tv-map or bug1234-tv-map-ucs).
	*~~Development~~		**Checkout the new branch (git checkout cr4321-tv-map).
	**Make regular commits to this branch as you are developing.		*Make regular commits to this branch as you are developing (git commit -a -m 'Commit message.').
	**Once initial development is complete rebase the bug/cr branch to a single commit.		**Once initial development is complete rebase the bug/cr branch to a single commit (git rebase -i origin/cr4321-tv-map).
	**The bug/cr branch can now be pushed to github for testing.		**Review the files that you’ve changed, using git status and git diff to ensure there are no unexpected changes.
	*Testing		**The bug/cr branch can now be pushed to github for testing (git push origin cr4321-tv-map).
	**The tester will fetch and checkout the cr/bug branch to test it and give feedback.		*The tester will fetch and checkout the cr/bug branch to test it and give feedback.
	**At this point make any required changes on the branch. Commit and push to github so that the tester can re-test.		**At this point make any required changes on the branch. Commit and push to github so that the tester can re-test.
	**Once all development is complete, checkout the development branch again. Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.		**Once all development is complete, checkout the development branch again (git checkout alien). Pull or fetch from github the latest of the branch and ensure that your local copy is at the head (git pull origin alien).
	**Merge the bug/cr branch into the development branch, resolving any conflicts.		**Merge the bug/cr branch into the development branch, resolving any conflicts (git merge cr4321-tv-map).
	**The development branch can now be pushed to github for integration testing.		**The development branch can now be pushed to github for integration testing (git push origin alien).
	*~~Integration Testing~~		*The tester will fetch and checkout the development branch to test it and give feedback.
	**Minor fixes required from integration testing can be made directly on the development branch. ~~Any~~ major problems ~~development can revert back to~~ the bug/cr branch.		**Minor fixes required from integration testing can be made directly on the development branch. These should be no major problems but if there are the fixes should be made on the bug/cr branch and tested there first. This should be done with priority as the development branch may be "broken" until these changes are merged.
	**Once integration testing is complete or if it is not required the bug/cr branch can be deleted locally and on github.		**Once integration testing is complete or if it is not required the bug/cr branch can be deleted locally and on github.

David.lucas at 06:41, 15 July 2015

2015-07-15T06:41:52Z

Show changes

David.lucas at 06:01, 15 July 2015

2015-07-15T06:01:03Z

@@ Line 1: / Line 1: @@
-===Starting on a new bug/change request.
+== Initial Setup ==
-*Checkout the development branch (e.g. alien) that the bug/change request will be added to.
+#Signup for a GitHub account www.github.com. Tell someone your username so they can add you to the appropriate SpectraQEST team
-*Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.
+#Download and install Git from http://git-scm.com/download. Windows has two possible ways to run git: choose msysgit instead of Cygwin. When installing, choose all the options that they recommend for Windows development. Install again to something like “C:\Program Files (x86)\Git”.
-*Create a new branch using the bug/cr and some form of descriptor as the name (e.g. cr4321-tv-map or bug1234-tv-map-ucs).
+*You will be prompted about line ending conversions at some point. Use the auto-convert option, I think it’s the first option. It should produce the line “autocrlf = true” in the default config: “C:\Program Files (x86)\Git\etc\gitconfig”.
-*Make regular commits to this branch as you are developing.
+#You can now:
-*Once initial development is complete rebase the bug/cr branch to a single commit.
+*Run the Git console using Git Bash, a shortcut (quotes included): "C:\Program Files (x86)\Git\bin\sh.exe" --login –i
-*The bug/cr branch can now be pushed to github for testing.
+*Run Git GUI using this entire command (quotes included) in a shortcut: "C:\Program Files (x86)\Git\bin\wish.exe" "C:\Program Files (x86)\Git\libexec\git-core\git-gui"
-*The tester will fetch and checkout the cr/bug branch to test it and give feedback.
+*A shortcut for both of these should have been created in the Start Menu automatically.
-*At this point make any required changes on the branch. Commit and push to github so that the tester can re-test.
+#Your global Git configuration file “.gitconfig” is found under “C:\Users\Your.Name\.gitconfig”. Setup your username and email by using the following commands in Git Bash:
-*Once all development is complete, checkout the development branch again. Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.
+*git config --global user.name “Your name”
-*Merge the bug/cr branch into the development branch, resolving any conflicts.
+*git config --global user.email your.name@spectraqest.com
-*The development branch can now be pushed to github for integration testing.
+#Download and install KDiff3 (this will be used as the merge tool for changes that can’t be automatically merged. Can maybe make it work with WinMerge, but haven’t tried.) This can be installed to the default location, something like “C:\Program Files (x86)\KDiff3”.
-*Minor fixes required from integration testing can be made directly on the development branch. Any major problems development can revert back to the bug/cr branch.
+#Setup Git to use KDiff3 and optionally Notepad++ as your editor instead of Vim by editing the global .gitconfig file. I find it easier to edit manually in Notepad++ than using the console. Here’s an example of a config file:
-*Once integration testing is complete or if it is not required the bug/cr branch can be deleted locally and on github.

David.lucas at 05:55, 15 July 2015

2015-07-15T05:55:26Z

New page

===Starting on a new bug/change request.
*Checkout the development branch (e.g. alien) that the bug/change request will be added to.
*Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.
*Create a new branch using the bug/cr and some form of descriptor as the name (e.g. cr4321-tv-map or bug1234-tv-map-ucs).
*Make regular commits to this branch as you are developing.
*Once initial development is complete rebase the bug/cr branch to a single commit.
*The bug/cr branch can now be pushed to github for testing.
*The tester will fetch and checkout the cr/bug branch to test it and give feedback.
*At this point make any required changes on the branch. Commit and push to github so that the tester can re-test.
*Once all development is complete, checkout the development branch again. Pull or fetch from github the latest of the branch and ensure that your local copy is at the head.
*Merge the bug/cr branch into the development branch, resolving any conflicts.
*The development branch can now be pushed to github for integration testing.
*Minor fixes required from integration testing can be made directly on the development branch. Any major problems development can revert back to the bug/cr branch.
*Once integration testing is complete or if it is not required the bug/cr branch can be deleted locally and on github.