Suggestion: How to contribute to LitePlacer software

[mrandt]

1a. If you identify something in the software which you'd like to fix, imrpove, enhance or add, check the issue tracker to see if it is already listed as a feature request or bug report:
https://github.com/jkuusama/LitePlacer-DEV/issues

If it is not on the list yet, add it with a meaninful title and description.

1b. If you want to help but have no idea where to start, check the issue tracker and see if there is anything you'd like to do.

2. In any case, add a comment to the issue which states that you will be working on that issue - simply to avoid double work and wasted effort.

3. Create a fork of the DEV repo. Easiest way is to navigate to the repository page in your browser, sign in with username + password and then click "fork" button on the upper right of the screen.

Repository page:
https://github.com/jkuusama/LitePlacer-DEV

This basically creates a working copy of all the sources under your control. This will be your isolated development environment. But your copy is still linked to Juha's repository (it is listed as a "remote" in your fork), so you can update your copy later and also contribute back. Check the git docs for more info.

Your fork will have it's own URL like https://github.com/<USERNAME>/LitePlacer-DEV

So far this copy is still on GitHub server, not your computer.

4. Create your local working copy by using git UI or commandline. This of course requires that you have git (and UI if you desire) installed on your PC.

If you use Windows and have the UI installed, simply click the "download / clone to desktop" icon on your repository web page.

Otherwise, the command

Code: Select all

git clone <REPOSITORY_URL>

is what you're looking for.

!!! Make sure to clone to a new or empty directory, as clone will overwrite local files that you might already have !!!

5. Create a branch in your repository (git branch) and give it a meaningful name for each feature / bugfix you work on; this makes things much easier if the central repo advances in the meantime.

This can again be easily done in the UI, create a new branch by clicking "create new branch icon" on the upper left, typing a name and clicking create.

If you're on the commandline, type

Code: Select all

git branch <BRANCHNAME>

to create the branch and

Code: Select all

git checkout <BRANCHNAME>

to select it to work on.

!!! Ce careful if you switch branches; checkout of another branch will revert unsaved local changes !!!

So far, the branch only exists on your computer. You have to push it to the GitHub server so it becomes visible to you and others, e.g. on the repository web page.

In the UI, click "Publish to remote" on the upper right.

On commandline, type

Code: Select all

git push -u origin <BRANCHNAME>

5. Now you can start to make your local changes with your preferred IDE, probably MS Visual Studio in this case. My suggestion is to keep each change small so it is easier to merge and test it later.

6. Once you are happy, you commit the local changes to the remote repository. Newly created files have to be added to version control.

UI is pretty much self-explantory. On commandline you are looking for:

Code: Select all

git add *

Code: Select all

git push

I'd recommend a UI as it gives you a nice overview of the diffs here...

7. Once you published your changes, they reside in your forked repository and can be seen on the repository web page and the network diagram.

8. Last not least, the changed files should make it back to Juha's centralized repository. To achieve this, you have to create a "pull request" which asks Juha to pull and merge your changes into the centralized repository.

This request can be created on the web page of YOUR repository again. Click the green "Compare & Pull Request" button on the top right and select your feature branch. Git will compare the code to the main repository and show you all changes as diffs.

Add a comment for Juha and other reviewers.

!!! You may reference the issues you have dealt with in the comment by simply typing a hash tag and the number of the issue (e.g. #11) which will automatically create mutual links from the issue to the pull request and vice versa. !!!

Create the pull request and wait for Juha to review your changes.

9. If you want to work on other issues, create a new branch for those changes and start over.

Happy coding, thank you for your contributions and have fun!!!

Best regards
Malte

[dc37]

Note about the command:

Code: Select all

git add *

This adds everything in your current working directory, which may or may not be what you want. To be more explicit with the file adding, you might want to do something more like

Code: Select all

git add ./path/to/filename

Or just use the GUI.

Some useful references:

http://gitref.org/
http://git-scm.com/doc

[mrandt]

Note about the command:

Code: Select all

git add *

This adds everything in your current working directory, which may or may not be what you want. To be more explicit with the file adding, you might want to do something more like

Absolutely correct. I just tried to keep this as simple as possible

Using some sort of Git UI makes this more interactive - so I'd recommend that.

As for git documentation / tutorials, I can recommend the following:
https://www.atlassian.com/git/tutorials/

This guide is quite concise, uses examples and has nice diagrams explaining the concepts.

[Pixopax]

I tried again, I want to fork the repository from knaster.

So I go to
"jkuusama/LitePlacer-ver2"

Then go to the graph, select network, and see the FORK which KNASTER created.

git1.png (24.95 KiB) Viewed 4032 times

I click on "knaster", and then I am at
"Knaster/LitePlacer-ver2"

git3.png (23.73 KiB) Viewed 4032 times

Alright, I am at the latest Version from KNASTER then right? That is what I want to have.
If I then click on "fork" it creates the files in my repo,

It is called: "Pixopax/LitePlacer-ver2" , ok.
But below it says: "forked from jkuusama/LitePlacer-ver2"

So not forked from Knaster, but from jkuusama!
The question is, which fork do I have now?

My graph then also looks like I have the files from juku, not from knaster.

git2.png (29.31 KiB) Viewed 4032 times

Also, I am not in the graph, is that because I did not commit any changes?
Besides of that, Malte has forked it too, and called it "Karl". What is that version? Did i change the wrong code?

Very confusing... That is what I mean: "Git sucks"

[dc37]

I did the same exact starting steps as you did (fork from knaster/LitePlacer-ver2) and I got the desired result (forked from knaster/LitePlacer-ver2 - screenshot attached)

Not sure what is going on on your side? It definitely looks like you have the files from JuKu.

[Pixopax]

I will try it again from scratch, maybe something went wrong on installation.