Project

General

Profile

Git-maus » History » Version 41

Dobbs, Adam, 24 February 2017 20:55

1 41 Dobbs, Adam
h1. Git-MAUS
2
3
{{>toc}}
4 1 Dobbs, Adam
5 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.
6 1 Dobbs, Adam
7 37 Dobbs, Adam
h2. Overview
8 1 Dobbs, Adam
9 28 Dobbs, Adam
This following section will guide you to:
10
11 24 Dobbs, Adam
# Create an account on GitHub
12
# Add an ssh key to your account
13
# Fork the MAUS repository on github into your personal github account
14
# Make a local copy on your computer of your fork of MAUS
15 1 Dobbs, Adam
# Create a new development branch within this repository locally
16 26 Dobbs, Adam
# Make and changes and commit these changes to this branch
17 1 Dobbs, Adam
# Push your development branch and these changes to your github MAUS fork
18 28 Dobbs, Adam
# Create a Jenkins test server job for your development branch
19 1 Dobbs, Adam
# Propose merging your changes back to the MAUS trunk via github
20
# Merge changes from the MAUS trunk into your development branch
21
22 37 Dobbs, Adam
h2. Step-by-step guide
23 2 Dobbs, Adam
24 26 Dobbs, Adam
# Create an account on "github":https://github.com/
25 25 Dobbs, Adam
# "Add an ssh key":https://help.github.com/articles/connecting-to-github-with-ssh/ to your account
26 26 Dobbs, Adam
# Fork the MAUS repository on github into your personal github account
27 25 Dobbs, Adam
## Go to "MAUS github page":https://github.com/mice-software/maus and login into github
28 1 Dobbs, Adam
## Click "Fork" in the top right of the screen, selecting the option to fork to your own account
29 25 Dobbs, Adam
    !http://micewww.pp.rl.ac.uk/attachments/8360/GitHubForkScaled.png!
30 1 Dobbs, Adam
## Select your own account from the options that appear for where to fork MAUS
31 26 Dobbs, Adam
# Make a local copy (clone) on your computer of your fork of MAUS
32
## Copy the address of your new fork from github (something like @git@github.com:jbloggs/maus.git@, where jbloggs is your github username)
33
## Clone your repository:
34 1 Dobbs, Adam
<pre>
35 26 Dobbs, Adam
git clone git@github.com:jbloggs/maus.git
36 1 Dobbs, Adam
</pre>
37 2 Dobbs, Adam
where jbloggs is your github username.
38 26 Dobbs, Adam
# Create a new development branch within this repository locally
39
## cd into the directory created by the clone command (maus by default)
40
## Take a look at the branches present with:
41 2 Dobbs, Adam
<pre>
42 26 Dobbs, Adam
git branch -av
43
</pre>
44
## Pull down the merge branch from your remote github repository into the new local repository:
45
<pre>
46 1 Dobbs, Adam
git checkout merge
47 26 Dobbs, Adam
</pre>
48
## Create a new development branch in the local repository by forking the merge branch:
49
<pre>
50 1 Dobbs, Adam
git checkout -b my-feature-branch
51 27 Dobbs, Adam
</pre>
52 26 Dobbs, Adam
## Observe the new state of your local repository with:
53
<pre>
54
git branch -av
55 2 Dobbs, Adam
</pre>
56 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.
57 26 Dobbs, Adam
# Make changes and commit these changes to the local development branch
58
## Edit some files, creating some wonderful new feature for the benefit of mousekind
59
## Stage the changes:
60 2 Dobbs, Adam
<pre>
61 1 Dobbs, Adam
git add AlteredFile1.cc AlteredFile2.cc
62 2 Dobbs, Adam
</pre>
63 26 Dobbs, Adam
## Commit the changes:
64 1 Dobbs, Adam
<pre>
65 2 Dobbs, Adam
git commit -m 'My excellent new feature, closing issue ###'
66 26 Dobbs, Adam
</pre>
67 28 Dobbs, Adam
# Push your development branch and these changes to your github MAUS fork
68 26 Dobbs, Adam
<pre>
69 3 Dobbs, Adam
git push origin my-feature-branch
70 26 Dobbs, Adam
</pre>
71 28 Dobbs, Adam
# Create a Jenkins test server job for your development branch
72
## The MAUS test server can be found at: "http://test.mice.rl.ac.uk":http://test.mice.rl.ac.uk
73 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
74 29 Dobbs, Adam
# Propose merging your changes back to the MAUS trunk via github
75 28 Dobbs, Adam
## Run the Jenkins test server job on your development branch
76 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")
77
    !http://micewww.pp.rl.ac.uk/attachments/8362/GitHubBranchesScaled.png!
78 1 Dobbs, Adam
## Click the "Pull request" button to propose merging into the trunk
79 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
80 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
81 31 Dobbs, Adam
# Merge changes from the MAUS trunk into your development branch
82 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.
83 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:
84 31 Dobbs, Adam
<pre>
85 34 Dobbs, Adam
git remote add upstream git@github.com:mice-software/maus.git
86 31 Dobbs, Adam
</pre>
87
## Look at your repository structure again with:
88
<pre>
89
git branch -av
90
</pre>
91
## Make sure we are in our feature branch:
92
<pre>
93
git checkout my-feature-branch
94
</pre>
95
## Now merge from the central MAUS merge branch into your feature branch with:
96
<pre>
97 38 Dobbs, Adam
git pull upstream merge
98 31 Dobbs, Adam
</pre>
99
## If there are any conflicts listed, examine each file in turn, make the changes needed, and then resolve the conflicts with:
100 1 Dobbs, Adam
<pre>
101
git add MyFixedFile.cc
102 34 Dobbs, Adam
</pre>
103
Commit the changes made if you resolved conflicts with:
104
<pre>
105 31 Dobbs, Adam
git commit -m 'Merged from the trunk'
106
</pre>
107
## Now push the changes back to your github repository with:
108
<pre>
109
git push origin my-feature-branch
110
</pre>
111 39 Dobbs, Adam
112
h2. Useful git commands
113 40 Dobbs, Adam
114
See "https://www.git-tower.com/blog/git-cheat-sheet/":https://www.git-tower.com/blog/git-cheat-sheet/