Re: AudioGame Collaboration: Should We Do It?
Alright. So this reply is going to contain some information for how you can get started with Git and Github. If you're a Git or Github expert, I want to appologize ahead of time. Some of this will be oversimplified for the sake of explaining this to newcomers. If you are somewhat familiar with Git or github, this might still be helpful because it will have some cut and paste commands. I've written this over a span of a couple of days, so it might be a little unorganized in some parts.
First, here is how I think about Git and Github. If you don't know the difference, this might help.
Git is the program used to manage, create, clone, and contribute to repositories. A repository is basically just a code project. The advantage of using Git is that you have the ability to view the history of files, revert to files whose contents have changed over time, and isolate changes that you make to code to work on separate features and issues at the same time as other contributors.
Github, on the other hand, is, in its simplist form, a place where these projects can be stored, viewed, and from where latest code changes can be retrieved. It's like a dropbox for code. lol Normally, Git projects are only stored on your computer, and contributions of the simplist kind can be made. Having an area where things can be centrally stored, such as Github, allows other developers to see and contribute to it.
The Git program runs on Mac, Windows, and Linux/Unix systems. It can be downloaded at the Git downloads page. Most users run the Git program on the command line. There are GUIs, but I can't speak as to their accessibility. In my opinion, it's much more accessible to run commands in command line environments anyway. The only challenge most beginners experience is the fact that there are so many commands. This can become overwhelming. But no worries, if you're confused, you're not the only one. Even experienced developers have to look up commands from time to time. That, and the fact that books just for git have been written can tell you how complex this system can be. My aim here is to write just enough to get a collaborator to my project up and running. I'm certainly not going to write a whole book about it. lol
So, the first exercise is to get this project onto your computer. Here is where I want to introduce two words of Git/Github terminology: cloning and forking.
Cloning a project is to essentially grab the repository from the web and making a copy of it on your computer. Forking a project is to essentially grab a copy of a person's repository, associated to a particular Github user, and making a copy of it on your own Github account. There is a difference! You need an account on Github to do both.
You might ask, why would someone fork a project? Well, Github is full of open source libraries and projects. When cloning, although you do have a copy of the project on your computer, the repository is still associated to the location on the web that corresponds to the user that originally created it. So when you make contributions, the only location it can go to is that on the original owner's reserved project location. The original owner might have even restricted others from collaborating directly to their project on this dedicated space. However, when forking, you get a copy of the project, and you reserve a separate location on your account for changes to be made. You can also think about it in terms of URLs. When forking, you get a different URL that you can use to host and retrieve your copy of the repository. There is a bit more to it than that, but I'll introduce it as the concepts come up.
Note: I will use the dollar sign ($) to denote that these are commands to be typed into the command line. I am assuming Git was installed on your computer. I am also assuming you have created a Github account. That part should be easy.
So, there are two ways to get my project onto your computer:
Cloning my repository. This would only be used for viewing the code because I don't have people as collaborators explicitly stated in the repository settings (which is required for allowing direct contribution via my web location). The command to achieve this is:
$ git clone https://github.com/EdgarLozano185519/Au … Pyglet.git
When you press enter, because this is https, it will ask you for your Github username and password. Just enter that information, and a copy of the code is created in its own automatically-created directory.The second way is to fork a version of my repository onto your account and clone that fork.
If you go to my repository URL (found in the first post), then you should see a "fork a copy of this repository" button. This should direct you to adding a repository with a similar name to your Github account. Once this is finished, the forked repository should appear in your account. You then want to take the url from your version, found as a collapsed button that says something like "clone or download", and paste it into your command line. Do the same thing as the first method, but replace my repo URL with the URL just obtained.
Now you have a copy of my repository on your computer. I now want to take you through a set of steps that you can do to make a change to the code. But before that, I want to introduce a few more things.
A commit is something you want to be recorded. Almost like saving the changes you made to a file. When you commit something to the repository, you are telling the program to remember this change or changes to a file, or even multiple files, and save the current state. Almost like bookmarking a state in the code.
A branch is a step beyond that. It's basically a way to tell the program, "Hey. I want to make a few changes from this point on. But these changes should be identified with this name." The changes made from this point on can be 1 or more commits you decide to make under this name. Now, the beauty of this is that each branch can be considered a feature, issue fix, or any contribution of any sort! And you can call it almost anything. This also allows for multiple people to work on multiple things (contributions) at the same time.
The important thing to remember, or know as I am just now introducing it, is that usually, you have a main branch into which, most of the time, all code is eventually added. This branch is called master. And the process of putting the code of one branch onto another is known as merging. So, most commonly, people will merge all of their branches onto the master branch. You can also make commits directly on the master branch if you don't want to go through the hassle of creating a branch for a simple change to the code (like a single spelling mistake correction).
Something I tend to do is to make a single branch, and once I finish with my changes on that branch, I merge into master. Sometimes you will have things such as merge conflicts. But I won't take the time to explain them here. You can read about them. I also want to let you know that there is more than one way to do something in Git. You just have to know the commands to get it done.
Another thing you should be aware of is pulling and pushing. Essentially, pulling is the process of retrieving latest code changes from the online repository. Pushing is the process of telling your program to add code changes you want to the storage place for your code, in our case, Github. Fetching is similar to pulling. However pulling does a few more extra steps than fetching. For our purposes, we are going to stick to fetching instead of pulling. Fetching will just retrieve branches from the place on the web where your repo is stored. If you want them to sync to your local branches, you will have to do some manual merging, which is the extra bit that pull does.
Another thing to be aware of is Pull Requests. A pull request is a way to let the original owner of a project know, "Hey! I just made a change to the code. Can you come check it out? If you like it, please add it to your repository." Then, the owner of the original repository, that would be me, can go check out your code. If I like it, I can then merge it to my repository's master branch.
One final thing you want to know about is the fact that you can have multiple repository URLs associated to a repository. I hope this part isn't too confusing. But why would you have more than one URL associated to your repository? Well, you might want one url from which latest code changes can be retrieved, and the other to be used for pushing changes. How is this applicable to our situation? Well, we will have two URLs: 1 URL is my main repository URL from which all changes are going to be stored (the place where I am planning to do the merging that serves as the central repository), and the other URL for your fork (the place you will use to store your changes and if you follow the pull request process, I can get changes from your fork and put them on my repo). If you try to push directly to my repo, I think it will give you an error.
So, this next part is important if you want to contribute to this project and we are to maintain some order.
If you already cloned my project, and you are planning to contribute, you want to follow above method to make a fork of my repository. Instead of cloning, you want to use the url normally used for this purpose to add it to the list of remote URLs associated to the already-cloned repo. To do this, run the following command:
$ git remote add upstream https://myforkurl.gitYou can replace upstream with a more meaningful name so that you can keep track of your repo url. Also, if not obvious, replace https://myforkurl.git with the actual url to your clone url retrieved from your forked repo.
However, if you want to start off by forking your own copy, that's fine too. You first fork and clone your repo, and add my repo url with the same command above, but replace the url with the clone url associated to my repository. It just depends how you want to start. Either way, you can keep track of your URLs with this command:
$ git remote -vOK. Now let's go through an example of how you would make a change to the code. Let's assume you wanted to add a sentence to the readme.md file (which Github uses as the main text displayed on the frontpage of your repository). Here's just one way to make this change and make me aware of the change.
Note: I'm assuming you began by cloning my repo first, and then added your fork url later. The name for the main cloned repo is usually "origin". But you can assign a name to the other urls via the command to add a remote above. Usually, a common name is "upstream". So I'll use upstream as the fork URL. Also, the commands listed will have to be executed form within the repository directory. I hope this is obvious by now.
Here is the flow:
A good practice is to always fetch latest stuff from main repo where collaborations are being done before making a change or changes. This is just to make sure you have latest branches and changes. Then merge remote changes just retrieved into master. These are the commands I would use:
$ git fetch origin
$ git checkout master
$ git merge origin/master
Note: Remember, in this example, "origin" is the main repo where the code is located, the central location which is my repo.You decide you want to make a change. If it's a significant change, you create a branch. If it's something small like a spelling mistake fix or something, you don't have to go through this step. So, let's assume you want to make a huge change. You run this command, replacing stuff in between less than and greater than signs, and omitting the less than and greater than signs when actually writing this command out:
$ git checkout -b <new_branch> <from_starting_point_which_is_usually_master>You make your change or changes on whatever branch you decide to make it on from step 2.
You can now commit it to the current branch with this command, replacing the message with something meaningful. The message is the stuff in between quotes. Oh, and do include the quotes. You can do it without the -m command, but if you do, you have to deal with vim. But this is how I do it:
$ git commit -a -m "A meaningful message for the commit"Do some more work if you want to and follow the same procedure as steps 3 and 4.
When you think you're done, you can then run this command, after running and testing of course:
$ git push -u upstream <name_of_branch_work_was_done_on>
Note: Remember, in this example, "upstream" is the name of the forked repo. "origin" is the main repo where the code is located, the central location which is my repo.Alternatively, if you want to keep things consistent, before step 6 above, and your changes are committed to something instead of master, you can merge things into the master branch and then just push master to upstream like this:
$ git checkout master
$ git merge <branch_work_was_done_on>
$ git push upstream masterWhen you're finished with all that, the last step is to put in a pull request so that I know that you want your changes in my repo. If you don't know how to do this, let me know, and I can provide instructions as to how this can be done. This process is managed through Github. Essentially, you're telling me which repo has your fixes and which branch of yours you want to merge with which one of my branches on my repository. Then, you submit the pull request. I will get to it, I promise. The rest can be handled by me. All I would have to do is see the branch you want me to merge into my master branch, and I'll pull and merge on my end.
Well, I think that's it. Sorry this reply was kind of long. I just wanted to document some of the process so that you guys have a quickstart to getting up and running with my repository. I know I may have left a lot of things out, and made an error or two. Feel free to point it out, and I'll edit my reply accordingly. Let me know if this was of any help to you. If so, I'm glad I could help at least one person. Happy contributing! And feel free to join my Skype and clone and contribute to this project! Please do read more for a more in-depth guide to Git and Github. This was just a quick tutorial. Nevertheless, hope it was useful.
-- Audiogames-reflector mailing list Audiogames-reflector@sabahattin-gucukoglu.com https://sabahattin-gucukoglu.com/cgi-bin/mailman/listinfo/audiogames-reflector
