GitHub

It has to be noted that GitHub has grown in both size and popularity and is a great place for working on open source projects. Suppose though you want to do more than just raise issues, well, see below for some help.

Cheat Sheet

If you want some help or power tips then tiimgreen/github-cheat-sheet is a great place to start.

Contributing

Suppose you find a repository and you would like to contribute. It is unlikely the owner will give you direct contributor access, so try something like this:

  • Create an issue, so you can ask the question and discuss your idea
  • In their repository, click the Fork button, this will then create a copy of their repository under your account
  • Do all the changes you want against your forked copy
  • Then in your copy, click "Compare" so you can see if they have updated the same files
  • From the comparison page you can create a "Pull Request" which starts the process of merging your changes
All quite simple really.

It is simple until such a time as you find the repository that you forked has moved on and you want to do another change. If this happens, then you need to do the following on the machine you did the changes:

  • git fetch <repository> - this pulls the original repository changes down
  • git checkout master - should just confirm you are already on "master"
  • git merge <repository>/master - merges the changes to your local git
  • git push - pushes your local git up to GitHub
After this GitHub will see your forked repository as the same as the original repository.

Windows Desktop App

This is a short summary of what I did to create a Pull Request with the Desktop App for Windows, it confused me at first but the key is you need to work from your own branch or fork.

  • Create a fork on GitHub, if not already done
  • Clone with Desktop app, to pull repository locally
  • Update from Organisation/master which will refresh an old branch/fork
  • Edit file(s) locally
  • In Desktop commit changes file(s)
  • Click Create "Pull Request"
  • select from master into "Organisation/master"
  • Add summary and description
  • Click Send Pull request
One further problem I find is keeping your branch up to date, it is not obvious how you do this. However I believe there are two keys here. Firstly you need to configure your fork correctly, so follow Configuring a remote for a fork - User Documentation to get this working. Then, once that is done, any time you want to refresh your fork just do Syncing a fork - User Documentation.

Readme Files

You will have noticed that many repositories have a README.md file, this is a "markdown" file and forms the introduction to the repository. If you need help with the syntax see Writing on GitHub - User Documentation which covers everything but Mastering Markdown · GitHub Guides is a great starting point. Do note that GitHub does not use standard markdown but "GitHub Flavored Markdown" or GFM. See also File Formats.