I would like to try and give interested developers a "crash course" on contributing via GitHub:
Juha decided to use GitHub as the version control system. While everyone has personal likes or dislikes, git IMHO nicely supports open source software development in distributed and diverse teams.
To contribute to an existing project on GitHub, you basically need to do the following:
1. Obviously you need a GitHub account (free) and client software for your OS. There are command line interface clients and graphical clients (e.g. GitHub for Windows). While usage slightly differs, the principles all stay the same.
2. If you want to modify files from and contribute to an existing project, you first of all clone the original repository.
The latter is under Juha's control and contains the sources. By cloning it, you create a fork under your control which you can modify as you like without affecting anyone else. In some places this function is actually called fork, while on command line the command is clone.
3. To work with your files you should understand the places in which the code resides:
- Global / Remote repository on GitHub server
- Local repository on your PC under git control
- Local working copy on your PC in file system and not under git control yet
4. So far, you have created the fork on GitHub server. So next step is to clone that to your desktop.
5. Then you can start making changes in file system. If you add new files, be sure to add them to git control. You can always check the status of your local repository vs. the local working copy and list all files that were modified, added or deleted.
6. Once you are done with your changes, you sync the local repository back to the remote repository on GitHub. Until this point, all these changes are only yours. Other users can see them by browsing your repository (the one you forked from Juha in step 2) but they do not affect Juha's code base.
7. If you want to contribute a change, you create a pull request. Basically you ask the owner of the orginial repository (Juha in this case) to pull your changes back to the original repository. As part of that process, Juha and / or other users can review your changes and decide whether they should become part of the main branch.
8. Similarly, if Juha adds or changes, commits and syncs anything to his repository, you can pull those changes into your fork as well.
Generally speaking, you should have one commit per change - so commit small and often! This is essential to help yourself and others understand what you changed, when and why.
Also, create a separate pull request per added functionality. It is hard for a project to review and accept a pull request which contains many changes at once.
Assuming you use Windows, try these step-by-step instructions:
a) Create GitHub account and install GitHub Desktop for Windows
https://desktop.github.com/
b) Open original repository in web browser:
https://github.com/jkuusama/LitePlacer-DEV
c) Sign in to GitHub using your username and password (if not already signed in)
d) Click "Fork" button on upper right of screen - this will create a clone under your username. Open the new repository.
-> https://github.com/jkuusama/LitePlacer-DEV becomes https://github.com/[yourusername]/LitePlacer-DEV
e) Make sure you are viewing your clone. You will see the hint "forked from jkuusama/LitePlacer-DEV" next to repository name.
Click "Clone in Desktop" on the right. This should open your previously installed Windows client, which will ask for a place in filesystem and download files to local disk.
Be careful to select an empty (!) directory. GitHub client will sync remote to local and delete all files that exist locally but not in remote repository...
f) Start changing or adding files in / to the newly created directory. Then open GitHub client again. Select the repository on the left and you will see a list of changes in the middle column.
e) Inspect your changes, add meaningful comments and click "commit" on the bottom of the middle column. This will save the changes locally (!). You can also revert changes.
!!! As I said earlier, do this often and add meaningful comments !!!
f) Sync changes to your remote repository (on GitHub server) by clicking "Sync" on top right.
g) Now you should be able to also see the changes / additions on the repository site in your web browser (https://github.com/[yourusername]/LitePlacer-DEV).
h) I find it to be the easiest to create pull requests from the web site interface.
As you view your repository in the web browser, click pull requests category on the right, then the green "New Pull Request" button on the top.
GitHub will compare the original repo and your clone and allow you to select the changes you want the original author to pull.
That's it - in a nutshell.
If you have more advanced questions - there are many good tutorials published on the internet. Should not be hard to find them
Happy coding and have fun!
Malte