OpenHatch wiki

Open Source Comes to Campus/Curriculum/Directory: Difference between revisions

Page Discussion

Open Source Comes to Campus/Curriculum/Directory (view source)

Revision as of 21:35, 14 July 2015

2,229 bytes added ,  8 years ago
→‎Commit and push
imported>Shauna
(Created page with "Hi! This is a guide to help you follow along with the "introduction to git" activity - or, if you're not at an event with a mentor, to do it on your own. == Overview (ie T...")
 
 
(26 intermediate revisions by one other user not shown)
Line 1:
Hi! This is a guide to help you follow along with the "introduction to git" activity - or, if you're not at an event with a mentor, to do it on your own.
 
== Overview (ie The Plan) ==
 
There's [https://github.com/FOSSdirectory/FOSSdirectory.github.io a repository] sitting on [http://en.wikipedia.org/wiki/GitHub Github] which contains a blanklist profileof pagecool people in open source - a directory, if you will. You're going to make a copy of the directory, edit it, and use it as your own! (For now, at least. You can delete it later if you're shy.) The repository also contains a "directory" page which will let you link to everyone else at the event.
 
Some of the changes you make will be just for your copies of the repository. Other changes you'll want to "push back" to [https://github.com/FOSSdirectory/FOSSdirectory.github.io the original repository]. We'll talk about how you can do that below.
 
Let's get started!
 
= The Activity =
== Visiting the project on the web ==
 
== Visit the project on the web ==
 
Since this project is a website, we've specially configured the repository so that whenever there is a push to it, it is made visible on the web. Github allows you to do this with repositories that have the following name scheme:
<code>$user-or-organization-name.github.io</code>
 
So for the organization FOSSdirectory, we call the repository: [https://github.com/FOSSdirectory/FOSSdirectory.github.io FOSSdirectory.github.io] And we can see the site live at [http://fossdirectory.github.io/ http://fossdirectory.github.io/].
Since this project is a website, we've specially configured the repository so that whenever there is a push to it, it is made visible on the web.
 
You should have already signed up for Github and created a user account. (If not, [https://github.com/join do so now]!) When you make your repository, you will eventually name it {your username}.github.io.
If your group's repository is called e.g. ''waffle-castle.github.io'', then you can see that the shared version is visible on the web at http://waffle-castle.github.io/. (This is just an example. Your group's repository page should be at schoolname-#.github.io (for example, princeton-1.github.io or princeton-2.github.io.)
 
== Fork a project on Github ==
But note that any changes in your ''fork'' won't show up there until the maintainer of the project merges those changes in.
 
To "fork" a project means to make a copy of it. You can't edit the original - somebody else owns it. But you can edit your "fork".
== To fork a project on Github ==
 
* Start out logged in to Github
Line 29 ⟶ 32:
* Notice that your browser is now visiting a copy of the project in your personal space, rather than the old, group-owned one. You should also see a "forked from..." remark in the top-left.
 
* Now it's time to rename the repository. You don't have to do this every time you fork a project, but you'll need to in order to make your site viewable on the web. To edit the repository name, go to "Settings", which is towards the bottom of the toolbar on the righthand side of your page. The top option should be the rename option. Change the repository so it's name follows the format: '''{your username}.github.io'''.
== Now, clone to it to your computer ==
 
Your webpage will not show up immediately. It usually takes 10-20 minutes for Github to put new x.github.io pages online.
 
== Now, clone the repository to your computer ==
 
You have a personal copy, but it's on Github (what git calls "a remote"), and not a local copy you can easily edit. We call the process of making a local copy "cloning".
 
* On the right side, look for the clone URL
Line 44 ⟶ 53:
 
== Make sure you have the project properly set up ==
 
 
* Open index.html in your favorite text editor -- it should look like a regular HTML page
 
* Open index.html in your favorite web browser -- it should render basically the same as http://purduefossdirectory.openhatchgithub.orgio/
 
* Make a test change in index.html, save, and reload in the browser. Make sure what you see in the the browser reflects that change.
Line 53 ⟶ 63:
* Undo that change, with your editor, save, and then reload in the browser. Make sure what you see in the browser reflects that change.
 
<blockquote>Here's a completely optional but neat trick: you can see the changes you've made by typing <code>git diff</code>. If you've fully undone your change, entering <code>git diff</code> should return nothing.</blockquote>
== Find a task ==
 
== Add yourself to the directory ==
 
The first thing we're going to do is make a simple change: you're going to add your username to the directory itself.
Now, find a bug on the project's issue tracker that you will work on, and claim it by leaving a comment on the issue saying so.
 
To do this, open up index.html. Find the list of links to users. If you're familiar with HTML, it should be easy enough for you to find. If you're not familiar with html, the line you're looking for looks like this:
(Before you do that, make sure to refresh the page and check that no one else has claimed it while you were reading and deciding.)
<a href="./profiles/" class="list-group-item">A person!</a> <!-- Copy this line and add your info. Don't forget the http:// -->
 
You want to add two piece of information. First, replace "A person!" with your name. Then, between the quote marks after "a href", add a link to your profile page. Your profile will be named <code>$your-github-username.html</code>.
== Resolve the task ==
 
HowThe yousecond dothing thisyou're dependsgoing onto thedo issueis you'vemake chosen.your own Ifprofile youpage runso intothat athe problemlink you can'tjust seemmade togoes solve,somewhere! try askingTo thedo studentthis, nextyou'll want to youmake ora onecopy of the mentors.template:
cp template.html profiles/$your-github-username.html
 
You can then open up the new file and edit it to your heart's content! You can add information about yourself, the projects you want to learn about, the skills you want to contribute, and more.
Make sure to open up index.html and check that your solution works.
 
== Commit and push ==
 
Once you'reve finishedmade makingyour changeschange, you can use the following command to get a list of files you've changed:
 
git status
 
You can commitmake sure git is tracking your changes by typing "git add" followed by the files you've changed, for instance:
 
git add index.html
Line 77 ⟶ 91:
Once you've added the changes, you can "commit" them with a message specifying what you've changed.
 
git commit -m "ExplanationI ofadded mymyself changesto the directory!"
 
(What's the difference between add and commit, you might ask? "add" let's you specify which specific files you want to include in a commit. If you want to include all the files you've changed you can smoosh these two steps together with <code>git commit -a -m "I added myself to the directory!"</code>)
 
Now, publish those changes on Github by typing:
Line 91 ⟶ 107:
== Create pull request ==
 
Now you want to send your change back to the original repository so it can keep track of all the cool new people making profiles. To do this, you'll want to create what's called a "pull request".
Visit your personal fork and click the "Pull requests" button on the right. This will offer you the chance to make a new pull request by clicking on "New pull request". Explain what you did, and make sure to include a comment stating which issues it addresses, so that it automatically closes the issue. (You can see [https://help.github.com/articles/closing-issues-via-commit-messages here] for details on how to do that.)
 
Visit your personal fork and click the "Pull requests" button on the right. This will offer you the chance to make a new pull request by clicking on "New pull request". Explain what you did, to make it easier for the repository's maintainer.
Now, get feedback from the project's maintainer (the mentor leading your group) and eagerly await your pull request getting merged!
 
When the changes are accepted back into the original, it is called "merging".
 
== Once merged, visit your changes on the web ==
 
When your changes are merged into the main project repository, ourthe specially configured repositorywebsite will updatebe the group websiteupdated with the merged files.
 
Sometimes your changes will not show because of caching. To get around this problem, add "?" to the end of the url.
This is a special trick that we do during the Website editing with git exercise, using Github Pages. It demonstrates that when the merge happens, it can programmatically cause a different event; this is often called ''hooks''.
 
== You can keep editing your profile ==
Sometimes your changes will not show because of caching. To get around this problem, add "/?" to the end of the url.
 
You can continue to edit and add to your profile. You should also feel free to make changes to the HTML and CSS, or to add additional images, code, etc as you desire.
== Advanced/Optional Commands ==
 
Once you've made your changes, you can follow [[Open_Source_Comes_to_Campus/Curriculum/Directory#Commit_and_push | the steps above]] to push the changes to your website.
(This section is in progress.)
 
Congrats! You've made yourself a profile - and successfully used git!
=== Setting multiple remotes ===
 
= The Follow Up =
 
You might say "Wait! I want a recent copy of the directory with all the new profiles people have added. How do I do that?"
 
There's totally a way to do it, but it's kind of complicated. If your mind is already full with the above activity, you should take a break, and come back to this later if you want to.
 
Alright. Ready?
 
== Setting multiple remotes ==
 
The copy of the repository you have on your computer is called your "local" copy. The copy on Github is a "remote". You can see what remotes are associated with your local repository by typing the command:
Line 114 ⟶ 142:
 
You should see something like this:
 
origin https://github.com/$yourusername/$your-repository-name (fetch)
origin https://github.com/$yourusername/$your-repository-name (push)
Line 119 ⟶ 148:
Origin is the default name for your remote repository. The urls you see should correspond to the urls used in the "git clone" command above. Right now your only remote is your personal copy of the repository. That's fine for pushing changes, since you need to go through the personal copy to submit pull requests. But what if you want to get an up to date version of the main repository? To do this, you'll need to add the main repository as a remote.
 
Below, replace $name with whatever you want to label the remote, and $url with the github url for the main repository (that is, <code>https://github.com/FOSSdirectory/FOSSdirectory.github.io.git</code>). Execute this command.
To do this, type:
 
git remote add $name $url
 
When you do the "git remote -v" command, you should see that you now have two sets of fetch/push listings.
Replace $name with whatever you want to label the remote, and $url with the github url for the main repository.
When you do the "git remote -v" command, you should see that you now have two sets of fetch/push listings. To get an updated version of the main repository, you can type:
 
git fetch $name
git merge $name/master
 
To update your remote personal repository, you can type:
Line 142 ⟶ 166:
That's it! You can add as many remotes as you'd like, although for the most part people stick to one or two.
 
== Pulling from the original repository ==
=== Resolving Merge Conflicts ===
 
You want to get the most up to date version of index.html from the original repository. To get an updated version of the main repository, you can type:
Your instructor should have showed you what she sees when you submit a pull request. Probably you saw a message from Github saying that the pull request could be "merged automatically". That means that you managed to avoid changing a part of the project that someone else also changed. Yay! That's how we designed this activity. But what happens if you ''do'' change the same part of a project as someone else? It generates what we call a "merge conflict".
 
git fetch $name
(A brief thought experiment to explain merge conflicts: let's say there's a repository with a single file that says, '''Hello [celestial object]!''' If you change that to '''Hello world!''' and submit a pull request, you're creating a diff which says: ''change "[celestial object]" to "world"''. If someone else copied the repository at the same time as you and changed the same line, they might create a diff which says ''change "[celestial object]" to "galaxy"''. If you make your changes to the repository first, it now says '''Hello world!''', so when the other person says ''change "[celestial object]" to "galaxy"'' the repository does not see '''[celestial object]''', and flags that there's a conflict.)
git merge $name/master
 
In our case, though, this may cause a merge conflict. A merge conflict happens when two people (or the same person, at two different points in time) edit the same part of the same file.
To induce a merge conflict in this activity, go to the main github repository and find a change that has been made since the last time you copied the repository ("git clone" gets a copy, as does "git fetch" and "git pull"). Make a change, locally, to the same line. Add and commit those changes.
 
<blockquote>If a merge conflict didn't happen this time, you can force it to happen by checking to see the [https://github.com/FOSSdirectory/FOSSdirectory.github.io/commits/master the most recent change] in the original repository. Then, you can make a random edit on the same line as that change. Make sure to add and commit your change before continuing.</blockquote>
There's two ways that this merge conflict can be solved. You could push your changes to your remote copy, then submit a pull request to your instructor. When viewing the pull request, they would be warned that changes could not be merged automatically:
 
So now there are two different index.htmls, your local copy and the origin. How do you reconcile the two?
[[File:Merge1.png]]
 
== Option A: Discard/keep within files ==
And would follow the instructions github helpfully provides to merge the changes:
 
There are a number of tools you can use to help visualize merge conflicts. For simple conflicts, though, I like to use a basic editor, such as nano, vim, emacs, or whatever you're most comfortable with. To view the merge conflict, open the file that the merge conflict is in. In basic text view, it looks like this:
[[File:Merge2.png]]
 
[[File:merge3.png]]
This involves some concepts like branching, which we haven't gotten to yet.
 
To resolve the conflict, scroll through the document until you find sections with these markings. The "========" line separates the two options that are in conflict. Choose which one you want to keep by deleting the other. Then delete all of the markings. Do this for each conflict and then save and exit the file.
Alternatively, you could fix the merge conflict yourself. To do this, you'd need to get an up-to-date copy of the remote repository. To do this, type:
 
You will then need to [[Open_Source_Comes_to_Campus/Curriculum/Directory#Commit_and_push | add and commit]] your changes.
git fetch [url of main project]
 
== Option B: Discard/keep whole files ==
(If you do not have the main project as one of your remotes, see the above section on multiple remotes.)
 
Dealing with merge conflicts can get messy, especially when there are a lot of changes and you want to keep things from both versions of the file.
This gets a copy of that repository. Now you need to merge that with your local changes.
 
In our case, though, we don't want to take things from each version of the file. We just want to update one file, index.html.
git merge
 
Luckily, there's a way to to this at the file level:
This should result in a conflict. There are a number of tools you can use to help visualize merge conflicts. For simple conflicts, though, I like to use a basic editor, such as nano, vim, emacs, or whatever you're most comfortable with. In basic text view, a merge conflict looks like this:
 
git checkout --theirs index.html
[[File:merge3.png]]
 
Again, once you have done this you will need to [[Open_Source_Comes_to_Campus/Curriculum/Directory#Commit_and_push | add and commit]] your changes.
To resolve the conflict, scroll through the document until you find sections with these markings. The "========" line separates the two options that are in conflict. Choose which one you want to keep by deleting the other. Then delete all of the markings. Do this for each conflict and then save and exit the file.
 
= Further Study =
 
There's a lot more we haven't covered - though the above should be more than enough to get you contributing to new projects.
 
Here are some additional resources for learning about git and Github:
 
* [http://git-scm.com/ Git manual]
Congrats! You've resolved the conflict! You can commit your changes by:
* Atlassian's [https://www.atlassian.com/git/tutorial git tutorials] (I especially recommend the tutorials for [https://www.atlassian.com/git/tutorial/git-branches branching].
* [https://help.github.com/ Github's help section]
* [http://gitimmersion.com/ Git Immersion ] - Covers some of the same stuff this tutorial does, possibly helpful if you're still confused.
* [http://try.github.io/levels/1/challenges/1 Try Git] - More tutorials. :)
Anonymous user
Retrieved from "https://wiki.openhatch.org/wiki/Special:MobileDiff/13855...13882"