2427 posts
UK
Posted 20 February 2016 - 06:07 PM
About This Tutorial
This tutorial is aimed at people who want to learn how to use GitHub to allow them to participate in collaborative projects. It will start with a small bit of background followed by instructions for joining an existing project and finishing with creating a project and inviting others to collaborate. There will be a lot of linking to external sites, I'm not going to try to repeat what better people have said.This tutorial is for writing programs with git, not for downloading existing programs from GitHub.
Some sections are not complete, please be patient if you want something from the incomplete sections.
This is quite a long post, you may want to copy and paste it into a text editor which supports links and delete sections as you read them.
What is Version Control?
A way of tracking changed in a programs source code, a change log is the simplest form of this. However, this tutorial will be looking into an advanced tool, which provides other features. Several of these features can make larger projects with multiple developers easier to manage, which is what this tutorial is assuming you want to do.Introducing Git
Git is a version control tool, it is notably more advanced then manually keeping a change log. It tracks every change made to the project and allows multiple people to work on a single project (called a repository, frequently shortened to 'repo'). I'm not going to go into too much detail about how it works, but I will tell you that git works by giving everyone a copy of the repo, these are then synchronised via another copy of the repo on a server somewhere.It should be noted that it is entirely possible to use git without a server, but this will make collaboration with others difficult. Though, I would recommend this for your smaller projects.
If you want to know more about version control and Git then have a look here: https://git-scm.com/book/en/v2/ Don't read too far ahead though
What is GitHub
GitHub is a provider for the server part of Git. You can make your own server, but that tends to more effort than it's worth if you want others to be able to access it. For this reason, I recommend using GitHub, there are other git server providers but GitHub is one of the most popular and the one I've seen on the forums the most.Using Git
First, you will need to install it, which you can do so from here: https://git-scm.com/...-Installing-GitIf you want to collaborate with others you will need a GitHub account, create one here: https://github.com/join
Finally, you need to learn how to use Git, rather than try and type out a definitive guide, I'm going to just link you some stuff, I would recommend reading the book as well as your preferred learning method, as the book is more complete.
- If you learn better through video, then these may be of interest to you: https://git-scm.com/videos
- If doing things is how you learn then this may be better for you: https://try.github.i.../1/challenges/1 you can stop after you know how to pull from a remote
- If you like to read then there is an entire book: https://git-scm.com/book/en/v2 You don't have to read it all for this tutorial, just read sections 1.4 through to 2.5
Don't worry if you can't remember all of this, there is a cheat sheet: https://training.git...cheat-sheet.pdf
And there is a reference guide: https://git-scm.com/docs
Side note: If you find that you like all this command line stuff and you are a Windows user then you may be interested in my tutorial on installing Bash on Windows: http://www.computerc...p?/topic/25661-
Is There a GUI? - Avoiding The Command Line
There are GUI clients for Git, but I do recommend that you try using the command line, it's not as scary as people make it out to be, and it is quicker than the GUI once you learn the commands (There are only four which you will likely use for everything, the rest can be looked up as needed).If you are going to use a GUI then I would recommend the GitHub GUI as it integrates with their website nearly automatically, however it is a bit light on advanced features (which is why I now use the command line). You can get it here for Mac and Windows: https://desktop.github.com/
The GitHub GUI has a nice tutorial built into it, so I won't include anything here.
If you want a GUI with advanced features, then I've heard some good things about SourceTree but I haven't used it: https://www.sourcetreeapp.com/
I've been told that SmartGit is similar to SourceTree but also has Linux support. http://www.syntevo.com/smartgit/
GitHub also allows you to make changes via their website, but their editor doesn't do syntax highlighting. They do provide a training book through https://training.git...r-everyone.html Scroll down to "Using the GitHub Desktop Application"
If you want to use the command line but find learning two things at once difficult then do use the GUI until you are familiar with Git, then you can try using the command line without also trying to figure out how Git should be used. There are resources available for learning the command line: https://try.github.i.../1/challenges/1 https://training.git...cheat-sheet.pdf https://git-scm.com/docs
There are other GUIs available too, you may want to have a browse.
Joining a Project
First, check that the project lead hasn't already provided instructions for joining the project. Look for a file in the repo named contributing it may be a *.txt file, or a *.md or *.markdown file.If you can't find a contributing file then contact the developers and ask if you can join, they may add you as a collaborator allowing you to use the repo as if it is your own (well, not quite but most of the things will be the same). Just clone the repo and push to it as you would to one in your own userspace on GitHub. You should know how to clone and push from the Using Git section.
If you have not been made a collaborator then don't worry, you can still work on the project with them, it's just going to be a bit more work for both you and them (the project leader). First you are going to want to fork their repo, GitHub has a guide for this too: https://guides.githu...vities/forking/
https://help.github....es/fork-a-repo/
Then you will want to clone your fork so that you have a local copy and then make your edits, then you push to your fork and then make a pull request from your fork back to the original repo. Again, GitHub have guides for this:
https://help.github....-pull-requests/
https://help.github....-pull-requests/
Markdown - What it is and How to Use it
Markdown is a markup language, that has support on GitHub. The format is great for readme files or other human read files, especially as the raw format is also easily human readable. Here's an example from one of my projects, make sure to click the raw button after seeing the rendered version: https://github.com/C...1e9bdd0/TODO.md As you can see, the rendered one looks nicer but, what I wanted to point out is, the raw format is also very easy to read and doesn't have any format tags like HTML (just have a look at the examples here: http://www.w3schools...ml_examples.asp ).Any file which uses the *.md or *.markdown file extension will have the special rendering applied when viewed on the GitHub website.
Side note: What is a markup language? You, presumably, are aware that Lua is a programming language, which tells a computer how to do something. Similarly, markup languages such as markdown, or even HTML (HyperText Markup Language) tell a computer what something should look like.
There is a nice interactive tutorial for markdown here: http://markdowntutorial.com/
And some documentation on the GitHub specific markdown (there are different 'flavours' which have slightly different features and syntax): https://help.github....ting-on-github/ https://guides.githu...ering-markdown/
GitHub *.md files are not the only things which use markdown, you can also use markdown in issues (see below) and any other place where the GitHub website allows you to talk to other people. Gitter (a chat room for GitHub repositories) also uses markdown in this way.
Making a Big Project, and Preparing for Collaboration Through GitHub
Step 1: Setting up the Repository (and Maybe a GitHub Organisation)First, consider how large you are expecting your project to be. If you are expecting to have several repositories then you may want to use a GitHub organisation, which can be created via the little plus icon at the top right. This is not a requirement for allowing others to contribute to your project, you can use a personal repo just as easily. Whichever you choose, you will need to create a repo for your project, this can be done on the website from the same plus icon. To have it as part of your organisation (if you made one) use the drop-down box under 'owner'.
Don't worry too much about the name of your repo, you can change it later. You can also transfer ownership to an organisation should you change your mind (look under settings near the top of the repository's page, it will be at the bottom of settings in the 'Danger Zone').
If you already have a local repository on your computer then leave "Initialize this repository with a README" unticked and leave license and .gitignore as none. The repo will give you instructions on how to push an existing repository.
If you do not have a local repo yet then you can tick the "Initialize this repository with a README" box, keep license and .gitignore as none, we will do those later.
If you forgot to tick the readme box and do not have a local repo to push yet, then click on README in the quick setup section of your repo.
You can now clone your repo like normal (see instructions above as required).
Step 2: Preparing for Others
A well organised and clean repo makes life easier for everyone who uses it. This is one of the uses of .gitignore files, which basically tells git what files extensions to not include in the repo commits despite that the file is in the repo's file tree. Simply create a file called .gitignore in the root of the repo and add file names which you want git to ignore. Wildcards (*) are accepted as well as folders through forward slashes (/). I find this website very useful for generating .gitignore files, here is one I preconfigured which should be fine for ComputerCraft projects: https://www.gitignor...macos%2Cwindows
.gitignore files are surprisingly flexible, you can ignore some files in one folder but include them in another, ignore a file unless it's in a folder as well as ignore everything but a defined selection of files.
https://git-scm.com/docs/gitignore
https://help.github....ignoring-files/
Licensing, this sounds more complicated than it is. I've made a tutorial for choosing a license already, don't worry it's shorter than what you have read already and doesn't have any domain terms. Once you have your license, paste it into a file at the root of your repo named license. Make sure that the license allows people to adapt and edit your code, if people are not legally allowed to have a copy of your code and edit it then they can't contribute. Some countries have automatic 'all rights reserved' licensing which means that not having a license is NOT the same as allowing everyone to do anything with your code.
Mentioning contributing, joining instructions are useful. You may want to create a file named CONTRIBUTING which will contain guidelines to how people should help in the project. You may want to link to a code of Conduct or similar here, as well as style guidelines for code and documentation, and bug reporting instructions. Google can be a good resource here if you need ideas.
You may also want to create a todo list, it's difficult to help when you don't know what needs doing. Markdown is good for lists.
Being able to communicate makes cooperating easier, you may want to set up a Gitter room for this. It integrates with Github, so you already have an account.
Step 3: What is the Project?
Only you know what your project is about, so this next part is going to tell others how they can help. Your readme file is what people will see first, put a general overview and the goals of your project at the top. Follow this with more details so that potential collaborators can get a better idea about your project. It will end up being similar to the forum post you will make when you release your program. When your program is ready you may want to add download and install instructions in the readme.
Step 4: Work and Wait
Keeping yourself motivated is quite possibly the most difficult part. Having other people working with you can be a motivator, but those same people will not be interested in helping the project if its leader, you, are not doing anything. Remember to tick things off the to-do list as you complete them, seeing the number of things to do shrink and the list of done things grow can also be a source of motivation. You may find that once you have a working version of your project that people will be more willing to help.
Some of this is covered in GitHub's own guide: https://help.github....o-your-project/
(WIP) Useful Extras For Everyone
brancheshttp://nvie.com/post...ranching-model/
issues and pull requests
git commit IDs
git log
git revert - git revert
will revert the latest commit
(WIP) Useful Extras For Project Managers
milestonestags
https://git-scm.com/...-Basics-Tagging
releases
submodules
Further Reading
I may have linked to these earlier in this post, they are in no particular orderTODO: Organise
https://help.github....ommit-messages/
https://help.github....g-a-repository/
https://help.github.com/
https://guides.github.com/
https://help.github....ories/bootcamp/
https://guides.githu...es/hello-world/
https://training.git...r-everyone.html
https://training.git...developers.html
https://guides.githu...es/hello-world/
https://git-scm.com/doc/ext
https://guides.githu...es/hello-world/
https://guides.githu...to-open-source/
Edited on 25 December 2017 - 10:42 PM
