Project

General

Profile

Git-maus » History » Version 40

Dobbs, Adam, 24 February 2017 20:54

1 1 Dobbs, Adam
h1. Git-maus
2
3 5 Dobbs, Adam
Besides Launchpad and bazaar MAUS has beta level support for git and"github":https://github.com/mice-software/maus. At the moment code updates for the trunk cannot be accepted from github however, only via Launchpad and bazaar.
4 1 Dobbs, Adam
5 37 Dobbs, Adam
h2. Overview
6 1 Dobbs, Adam
7 28 Dobbs, Adam
This following section will guide you to:
8
9 24 Dobbs, Adam
# Create an account on GitHub
10
# Add an ssh key to your account
11
# Fork the MAUS repository on github into your personal github account
12
# Make a local copy on your computer of your fork of MAUS
13 1 Dobbs, Adam
# Create a new development branch within this repository locally
14 26 Dobbs, Adam
# Make and changes and commit these changes to this branch
15 1 Dobbs, Adam
# Push your development branch and these changes to your github MAUS fork
16 28 Dobbs, Adam
# Create a Jenkins test server job for your development branch
17 1 Dobbs, Adam
# Propose merging your changes back to the MAUS trunk via github
18
# Merge changes from the MAUS trunk into your development branch
19
20 37 Dobbs, Adam
h2. Step-by-step guide
21 2 Dobbs, Adam
22 26 Dobbs, Adam
# Create an account on "github":https://github.com/
23 25 Dobbs, Adam
# "Add an ssh key":https://help.github.com/articles/connecting-to-github-with-ssh/ to your account
24 26 Dobbs, Adam
# Fork the MAUS repository on github into your personal github account
25 25 Dobbs, Adam
## Go to "MAUS github page":https://github.com/mice-software/maus and login into github
26 1 Dobbs, Adam
## Click "Fork" in the top right of the screen, selecting the option to fork to your own account
27 25 Dobbs, Adam
    !http://micewww.pp.rl.ac.uk/attachments/8360/GitHubForkScaled.png!
28 1 Dobbs, Adam
## Select your own account from the options that appear for where to fork MAUS
29 26 Dobbs, Adam
# Make a local copy (clone) on your computer of your fork of MAUS
30
## Copy the address of your new fork from github (something like @git@github.com:jbloggs/maus.git@, where jbloggs is your github username)
31
## Clone your repository:
32 1 Dobbs, Adam
<pre>
33 26 Dobbs, Adam
git clone git@github.com:jbloggs/maus.git
34 1 Dobbs, Adam
</pre>
35 2 Dobbs, Adam
where jbloggs is your github username.
36 26 Dobbs, Adam
# Create a new development branch within this repository locally
37
## cd into the directory created by the clone command (maus by default)
38
## Take a look at the branches present with:
39 2 Dobbs, Adam
<pre>
40 26 Dobbs, Adam
git branch -av
41
</pre>
42
## Pull down the merge branch from your remote github repository into the new local repository:
43
<pre>
44 1 Dobbs, Adam
git checkout merge
45 26 Dobbs, Adam
</pre>
46
## Create a new development branch in the local repository by forking the merge branch:
47
<pre>
48 1 Dobbs, Adam
git checkout -b my-feature-branch
49 27 Dobbs, Adam
</pre>
50 26 Dobbs, Adam
## Observe the new state of your local repository with:
51
<pre>
52
git branch -av
53 2 Dobbs, Adam
</pre>
54 34 Dobbs, Adam
A note on nomenclature: The original repository you fork from on github is usually referred to as the @upstream@ repository. Any repository you clone from is by default named @origin@. Here @upstream@ refers to the central MAUS github repository, and @origin@ refers to your fork of it on github.
55 26 Dobbs, Adam
# Make changes and commit these changes to the local development branch
56
## Edit some files, creating some wonderful new feature for the benefit of mousekind
57
## Stage the changes:
58 2 Dobbs, Adam
<pre>
59 1 Dobbs, Adam
git add AlteredFile1.cc AlteredFile2.cc
60 2 Dobbs, Adam
</pre>
61 26 Dobbs, Adam
## Commit the changes:
62 1 Dobbs, Adam
<pre>
63 2 Dobbs, Adam
git commit -m 'My excellent new feature, closing issue ###'
64 26 Dobbs, Adam
</pre>
65 28 Dobbs, Adam
# Push your development branch and these changes to your github MAUS fork
66 26 Dobbs, Adam
<pre>
67 3 Dobbs, Adam
git push origin my-feature-branch
68 26 Dobbs, Adam
</pre>
69 28 Dobbs, Adam
# Create a Jenkins test server job for your development branch
70
## The MAUS test server can be found at: "http://test.mice.rl.ac.uk":http://test.mice.rl.ac.uk
71 33 Dobbs, Adam
## Either email the head of MAUS requesting a test branch and giving your repository url and development branch id, or go to the test server, create a new item, copying an existing git-based test job, and edit the configuration with your repository url and branch name
72 29 Dobbs, Adam
# Propose merging your changes back to the MAUS trunk via github
73 28 Dobbs, Adam
## Run the Jenkins test server job on your development branch
74 30 Dobbs, Adam
## When Jenkins has passed (and not before), return to your repository page on github and select @my-feature-branch@ from the drop-down menu on the left (below is an example where the feature branch is named "event-selection")
75
    !http://micewww.pp.rl.ac.uk/attachments/8362/GitHubBranchesScaled.png!
76 1 Dobbs, Adam
## Click the "Pull request" button to propose merging into the trunk
77 31 Dobbs, Adam
## Make sure your branch is comfortable for merging, that is it does not lead to any conflicts when github attempts a mock merge into the central MAUS merge branch. If your branch is not comfortable for merging, edit some more until it is, commit and push, then try again
78 32 Dobbs, Adam
## Creating a pull request will alter the MAUS maintainers you want your code added to the trunk, and begin a conversation between you and them if any changes are required first
79 31 Dobbs, Adam
# Merge changes from the MAUS trunk into your development branch
80 1 Dobbs, Adam
## One reason your development branch may not automatically be comfortable for merging back in the central MAUS merge branch is if someone has pushed changes there since you forked your repository. This can be dealt with by merging the changes from the central MAUS repository into your repository.
81 34 Dobbs, Adam
## First, we must tell your local copy of your repository about the central MAUS repository on github. This is called adding are remote. Note your local repository already has one remote, your repository on github - it has the default name @origin@. Add the central MAUS repository on github as a new remote called @upstream@ with:
82 31 Dobbs, Adam
<pre>
83 34 Dobbs, Adam
git remote add upstream git@github.com:mice-software/maus.git
84 31 Dobbs, Adam
</pre>
85
## Look at your repository structure again with:
86
<pre>
87
git branch -av
88
</pre>
89
## Make sure we are in our feature branch:
90
<pre>
91
git checkout my-feature-branch
92
</pre>
93
## Now merge from the central MAUS merge branch into your feature branch with:
94
<pre>
95 38 Dobbs, Adam
git pull upstream merge
96 31 Dobbs, Adam
</pre>
97
## If there are any conflicts listed, examine each file in turn, make the changes needed, and then resolve the conflicts with:
98 1 Dobbs, Adam
<pre>
99
git add MyFixedFile.cc
100 34 Dobbs, Adam
</pre>
101
Commit the changes made if you resolved conflicts with:
102
<pre>
103 31 Dobbs, Adam
git commit -m 'Merged from the trunk'
104
</pre>
105
## Now push the changes back to your github repository with:
106
<pre>
107
git push origin my-feature-branch
108
</pre>
109 39 Dobbs, Adam
110
h2. Useful git commands
111 40 Dobbs, Adam
112
See "https://www.git-tower.com/blog/git-cheat-sheet/":https://www.git-tower.com/blog/git-cheat-sheet/