Serge NOEL
312 lines
17 KiB
Plaintext
312 lines
17 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: Using GitHub Desktop</title>
|
|
<meta name="keywords" content="JMRI Git Github desktop"><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI: Using GitHub Desktop</h1>
|
|
First some useful definitions:
|
|
<dl>
|
|
<dt>Git:</dt>
|
|
|
|
<dd>A version control system, used by the developers of JMRI</dd>
|
|
|
|
<dt>GitHub:</dt>
|
|
|
|
<dd>A website and a host for projects using Git</dd>
|
|
|
|
<dt>GitHub Desktop:</dt>
|
|
|
|
<dd>A graphical front end for Git.</dd>
|
|
</dl>
|
|
Before using GitHub Desktop, we need to fork the JMRI repository to our own repository. For
|
|
this, we log in to https://github.com/ , go to the JMRI repository
|
|
https://github.com/JMRI/JMRI and click the button "Fork" on the top right side of the GitHub
|
|
website.
|
|
<p>We then start GitHub Desktop. We now need to clone our JMRI repository to the local
|
|
computer.</p>
|
|
<div class="flex-container"><!-- flex is a set for responsive positioning on different screen sizes -->
|
|
<div class="flex-item-50">
|
|
<a href="images/GHD_Image_1_Clone.png"><img src="images/GHD_Image_1_Clone.png"
|
|
alt="GhD Clone step 1"></a>
|
|
</div>
|
|
<div class="flex-item-50">
|
|
<a href="images/GHD_Image_2_Clone.png"><img src="images/GHD_Image_2_Clone.png"
|
|
alt="GhD Clone step 1"></a>
|
|
</div>
|
|
</div>
|
|
<p>This tutorial was created by GitHub user <code>danielb987</code> so the JMRI repository is
|
|
<code>danielb987/JMRI</code>.</p>
|
|
|
|
<p>Depending on the speed of the Internet connection, cloning the JMRI repository to your
|
|
computer may take a while. It's about two gigabyte of data to download. Be patient!</p>
|
|
|
|
<h3>GitHub Desktop user interface</h3>
|
|
<br>
|
|
<a href="images/GHD_Image_3_GitHubDesktop.png"><img src=
|
|
"images/GHD_Image_3_GitHubDesktop.png" alt="The GithubDesktop screen"></a><br>
|
|
The GitHub Desktop application has on the top a menu. It can also be accessed by pressing the
|
|
"Alt" key, which is useful if GitHub Desktop is in full screen mode and the menu is
|
|
invisible.
|
|
<p>Below the menu, there is three "buttons": Current repository, current branch and the
|
|
Fetch-button. The button "Current branch" is used to select another branch or to create a new
|
|
branch. Note that branches are cheap, so there is no problem creating new ones as needed.</p>
|
|
|
|
<p>The last button, "Fetch origin", sends data to and from the GitHub web server. When it
|
|
says "Fetch origin", it only syncs the computer with the server, but once there is commits to
|
|
either download from the GitHub server to the local computer, or commits to upload from the
|
|
local computer to the server, this button will tell you about it and once you press the
|
|
button, the commits will be downloaded or uploaded to the server.</p>
|
|
|
|
<h3>Keeping our branches up to date with JMRI</h3>
|
|
There are several developers on the JMRI project, adding and changing code all the time. We
|
|
therefore need to keep our local branches up to date with the JMRI master branch.
|
|
<p>First, select the "master" branch to keep it up to date with the JMRI master branch. Then
|
|
go to the main menu, click on "Branch" and "Merge into current branch".<br>
|
|
<a href="images/GHD_Image_4_MergeInto.png"><img src="images/GHD_Image_4_MergeInto.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
Then select the upstream/master branch. It's at the bottom of the list.<br>
|
|
<a href="images/GHD_Image_5_MergeInto.png"><img src="images/GHD_Image_5_MergeInto.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
The text "20 hours ago" tells you when the last change was made to the upstream/master
|
|
branch. The text "This will merge 14 commits from upstream/master into master" tells you how
|
|
many commits that are to be merged, from which branch and to which branch. Ensure you have
|
|
chosen the correct branches!</p>
|
|
|
|
<p>Click on the button "Merge upstream/master into master" to do the merge. When it's finished,
|
|
you will see this:<br>
|
|
<a href="images/GHD_Image_6_MergeIntoDone.png"><img src=
|
|
"images/GHD_Image_6_MergeIntoDone.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
The button "Fetch origin" has now changed its name to "Push origin". The number 14 tells that
|
|
there are 14 commits to upload to the server.</p>
|
|
|
|
<p>But wait! Why do we want to _upload_ the commits? Haven't we just downloaded them from
|
|
JMRI?</p>
|
|
|
|
<p>Yes, we downloaded the commits from upstream/master into our local master on the
|
|
local computer. It's now time to upload these commits to our repository on the GitHub
|
|
server.</p>
|
|
|
|
<p>This is what happened: We are working with three different repositories. For me, my
|
|
username on GitHub is <code>danielb987</code>, so I'm working with these three repositories:</p>
|
|
|
|
<ul>
|
|
<li><code>JMRI/JMRI</code> - The main repository for the JMRI project on the GitHub server</li>
|
|
|
|
<li><code>danielb987/JMRI</code> - My repository on the GitHub server</li>
|
|
|
|
<li>The repository on the local computer</li>
|
|
</ul>
|
|
<p>What has happened is that we merged "upstream/master" from JMRI/JMRI to our "master" branch in
|
|
our repository on our local computer. So we still need to upload these changes to our "master"
|
|
branch on our local computer to our GitHub repository on the GitHub server, which for me is
|
|
"danielb987/JMRI".</p>
|
|
|
|
<h3>The workflow of JMRI development</h3>
|
|
<p>We use the workflow:</p>
|
|
|
|
<ol>
|
|
<li>Select the branch "master"</li>
|
|
|
|
<li>Ensure "master" is up-to-date with upstream/master. If it hasn't been merged yet, we
|
|
merge branch "upstream/master" into "master" as previously described.</li>
|
|
|
|
<li>Create a new branch. Please use only english letters, digits and underscore for the
|
|
name of the branch. GitHub Desktop can handle international characters, but if you need
|
|
help from one of the maintainers, it can be tricky for them to handle the branch if it has
|
|
international characters. Note that "branches" are cheap. It's no problem to have many of
|
|
them.</li>
|
|
|
|
<li>Do a commit then a part of the work is finished. It's often better to have many small
|
|
commits than one big commit. But it's good if the project at least can compile each
|
|
commit.</li>
|
|
|
|
<li>Do the work you need. If it takes a long time, we highly recommend merging
|
|
upstream/master into the branch once a week.</li>
|
|
|
|
<li>Once the work is done, a "Pull Request" is created. A Pull Request, or PR, is a way to
|
|
tell the maintainers of JMRI that you have done this work, and you want it included into
|
|
JMRI.</li>
|
|
|
|
<li>Then a Pull Request, PR, is created, some automatic tools, for example Travis and Code
|
|
Climate, will start to compile the code and run a big number of tests against it. Most, but
|
|
not all, of these tools must succeed for the maintainers to be able to merge your work into
|
|
JMRI.</li>
|
|
|
|
<li>Once the automatic tools are finished, the maintainers will look at the Pull Request
|
|
and check it, and if everything seems OK they will merge your work into JMRI.</li>
|
|
</ol>
|
|
|
|
<h3>Creating a new branch to work with</h3>
|
|
First select the master branch and ensure it's up-to-date. If it's not, please merge
|
|
upstream/master into master. Se above.
|
|
<p>Click on the button "Current branch" and then click on the button "New branch" and give
|
|
the new branch a name.<br>
|
|
<a href="images/GHD_Image_7_NewBranch.png"><img src="images/GHD_Image_7_NewBranch.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
<br>
|
|
<a href="images/GHD_Image_8_NewBranchName.png"><img src=
|
|
"images/GHD_Image_8_NewBranchName.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
Prevent using international characters or spaces in the branch name as it may
|
|
cause problems for the maintainers later.</p>
|
|
|
|
<p>You can create the branch from another branch than the master branch. For
|
|
example, JMRI may use the branch "development" as the branch to base development on. If this
|
|
is the case, you select the development branch, then merge the branch "upstream/development"
|
|
into the branch "development" and then create the branch from development. Note that if you
|
|
do this, GitHub desktop will warn you and ask if you really want to start from the
|
|
development branch or start from the master branch. Select the "development" branch in this
|
|
case.<br>
|
|
<a href="images/GHD_Image_9_NewBranch_Development.png"><img src=
|
|
"images/GHD_Image_9_NewBranch_Development.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
When a new branch is created, it only exists on your local computer. In order to push it to
|
|
the server, we click on the button "Publish branch".<br>
|
|
<a href="images/GHD_Image_10_PublishBranch.png"><img src=
|
|
"images/GHD_Image_10_PublishBranch.png" height="50%" width="50%" alt="screenshot"></a><br></p>
|
|
|
|
<h3>Do a commit</h3>
|
|
Using your favourite development tool, for example Eclipse or NetBeans, do the changes you
|
|
want. For the purpose of this text, we create a simple class HelloWord.java.<br>
|
|
<a href="images/GHD_Image_11_NewClass.png"><img src="images/GHD_Image_11_NewClass.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
GitHub Desktop will now show the changes we have done, in this case added a new class. We add
|
|
a description for the commit that describes what this commit does and then click on the
|
|
button "Commit to ...". The branch we are committing to is "hello_world" so the button shows
|
|
"Commit to hello_world".<br>
|
|
<a href="images/GHD_Image_12_CreateCommit.png"><img src=
|
|
"images/GHD_Image_12_CreateCommit.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
We then click the button "Push origin" to upload our commit to the GitHub server. Note that
|
|
this sends the commit to my repository, not the JMRI repository.
|
|
<h3>Create a Pull Request, PR</h3>
|
|
When we have done the commits we want, it is time to do a Pull Request, or PR. It tells the
|
|
maintainers of JMRI that you want this code to be included into JMRI.
|
|
<p>In order to do that, we click on the button "Create Pull Request".<br>
|
|
<a href="images/GHD_Image_13_CreatePullRequest.png"><img src=
|
|
"images/GHD_Image_13_CreatePullRequest.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
This will open a web browser. If you are not logged in to GitHub, you need to log in. When
|
|
you have logged in, you will see the web page for creation of a Pull Request.<br>
|
|
<a href="images/GHD_Image_14_CreatePullRequest.png"><img src=
|
|
"images/GHD_Image_14_CreatePullRequest.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
Fill in a title and a description of the Pull Request and click on the button "Create Pull
|
|
Request".</p>
|
|
|
|
<p>Sometimes you may want to do some more work on the Pull Request before it's merged, or you
|
|
may want somebody else to look at it. In these cases, you can mark the Pull Request as "Work
|
|
In Progress" by writing the letters WIP in the title.<br>
|
|
<a href="images/GHD_Image_15_CreatePullRequest.png"><img src=
|
|
"images/GHD_Image_15_CreatePullRequest.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
After the Pull Request is created, the following page is shown.<br>
|
|
<a href="images/GHD_Image_16_CreatePullRequestDone.png"><img src=
|
|
"images/GHD_Image_16_CreatePullRequestDone.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
Below "Some checks haven't completed yet" is a list of tools that runs a lot of automatic
|
|
tests. These tools compile the code, run the tests and checks that everything is correct. If
|
|
a check is successful, it will have a green check mark, otherwise it will have a red
|
|
cross.</p>
|
|
|
|
<p>Not all tests need to be successful for the Pull Request to be merged, only the ones
|
|
marked with "Required", but it's good if all tests are successful.</p>
|
|
|
|
<p>After that, you will have to wait for one of the maintainers to take a look at your Pull
|
|
Request and hopefully merge it into JMRI.</p>
|
|
|
|
<h3>Handling a conflict</h3>
|
|
There are many programmers working on JMRI simultaneously. This means that it happens that
|
|
two persons are working at the same piece of code the same time. Most often, Git will be able
|
|
to handle that, but in some cases conflicts appears that needs to be handled manually.
|
|
<p>In our example, we have the method <code>hello()</code>:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
public void hello() {
|
|
System.out.print("Hello");
|
|
System.out.println("World");
|
|
}
|
|
</pre>
|
|
<p>Lets add a row:</p>
|
|
<pre>
|
|
public void hello() {
|
|
System.out.print("Hello");
|
|
System.out.print(" my ");
|
|
System.out.println("World");
|
|
}
|
|
</pre>
|
|
<br>
|
|
<a href="images/GHD_Image_17_Conflict.png"><img src="images/GHD_Image_17_Conflict.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
On the right side, you will now see that a new line has been added at row 14. We do a commit
|
|
and upload it to the server.
|
|
<p>Now we want to keep up with upstream/master, so we merge "upstream/master" into "master",
|
|
and then "master" into our branch "hello_world". We select the branch "master" and merge
|
|
"upstream/master" into our "master" branch and then select the branch "hello_world" and merge
|
|
the branch "master" into "hello_world".</p>
|
|
|
|
<p>(For the case of demonstration, I use the branch hello_world2 to show a conflict).</p>
|
|
|
|
<p>We now have a problem! Some other guy has made a change in the same code as we, and there
|
|
is a conflict! GitHub tells that there is one conflicting file between the two branches we
|
|
want to merge.</p>
|
|
|
|
<p>In order to solve that, we click on the button "Merge ...".<br>
|
|
<a href="images/GHD_Image_19_Conflict.png"><img src="images/GHD_Image_19_Conflict.png"
|
|
height="50%" width="50%" alt="screenshot"></a><br>
|
|
GitHub now protects us from doing too much damage by requiring us to fix the conflict before
|
|
we can commit the merge. We have to solve the conflict or abort the merge.</p>
|
|
|
|
<p>To solve the conflict, we open the conflicting file in our editor, for example
|
|
NetBeans.<br>
|
|
<a href="images/GHD_Image_20_ConflictSolving.png"><img src=
|
|
"images/GHD_Image_20_ConflictSolving.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
The strange code in the file shows there is a conflict, or in some cases there may
|
|
even be several conflicts in the file.</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
public void hello() {
|
|
System.out.print("Hello");
|
|
<<<<<<< HEAD
|
|
System.out.print(" my ");
|
|
=======
|
|
System.out.print(" your ");
|
|
>>>>>>> hello_world2
|
|
System.out.println("World");
|
|
}
|
|
</pre>
|
|
<p>There is two parts here. First, beginning with <code><<<<<<< HEAD</code>
|
|
is the code we added. This code goes down to the line <code>=======</code>.<br>
|
|
Below that are the lines of code that someone else wants to have, and that code goes down to
|
|
<code>>>>>>>> hello_world2</code>.<br>
|
|
In this case, I have used the branch "hello_world2" to get a conflict, but most often you will have
|
|
merged master into your branch so this line will be ">>>>>>> master".</p>
|
|
<p>We need to decide if we should keep the original code, replace it with our
|
|
own, or do something else. The key is to understand what the code does and to make a
|
|
good decision. If in question, please ask the JMRI developer mailing list.</p>
|
|
|
|
<p>In this case, we resolve this by changing the line to:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
System.out.print(" our ");
|
|
</pre>
|
|
<p>
|
|
<a href="images/GHD_Image_21_ConflictSolving.png"><img src=
|
|
"images/GHD_Image_21_ConflictSolving.png" height="50%" width="50%" alt="screenshot"></a><br>
|
|
Then we go back to GitHub Desktop, we see that the conflict is solved, so we can now merge
|
|
the commit.<br>
|
|
<a href="images/GHD_Image_22_ConflictSolving.png"><img src=
|
|
"images/GHD_Image_22_ConflictSolving.png" height="50%" width="50%" alt="screenshot"></a>
|
|
</p>
|
|
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|