A guide to git/github contribution

[Mariculous]

Git can be super strange to start with. I'll try to cover the most relevent concepts a potential simutrans-extended contributor should be aware of.

Basic git background
If you are already familiar with the basic concept of git and github or you simply don't care, you can skip this section. (continue to the next post)

What is git?
Git is the version control system used in simutrans-extended developement.
It is used to maintain different states of the project and to pass around the changes made, for example to get your local changes into the next nightly release of simutrans-extended.

What is a repository?
A repository is simply a directory whose state is maintained by git. Usually this is local directory on your computer where you have cloned an existing repository to.
Git will track changes being made to that directory.
There can be multiple parallel timelines of your directories contets managed in your repository, but for now let's keep things simple and have a look at a linear timeline of changes only.
Whenever you make a change in the directory, you can save these changes by doing a commit.

So, what is a commit?
You can find definitions like this in the web: In version control systems, a commit is an operation which sends the latest changes of the source code to the repository"
Yes, this is a commit! But it's not the only kind of commit. We will refer to a commit as the result of such an operation.
So a commit is a snapshot of your directory at a specific point in time.
You can "load" this state by using the checkout operation and save the state by using the commit operation.
Nice to know: A commit does not store the whole state of your directory. Instead it stores the introduced changes as well as a link to the previous commit. The actual state of the directory is reproduced from that commit chain, so you won't waste tons of memory by a simple commit.

I have mentioned parallel timelines before, which is the next topic.

What is a branch?
A branch is simply a name referencing to a commit. You can checkout a branch just like you can checkout any commit.
When working on a branch, on each new commit, the branches reference will be updated to point to that new commit.
This permits you to, for example, have a break on your new, truly_awesome_feature branch, create a new branch to make a minor bugfix of something entirely unrelated, and later on check out your truly_awesome_feature branch again, to continue on this.

In theory, you could do this without any branches. Practically, you really don't want to remember commit IDs like "0afb7bf017a518defd343c5b9f4cc076958e70ed" to return to your nice feature later on, do you?

Finally, what is a remote?
A remote is a repository whose commit history is related to your local repository. Usually this is because you have cloned from a remote some day, but it might as well be the other way round.
Note that unlike svn, git itself does not know hierarchical structures like "this git repository is the server and that one is the client".
There simply is no such concept. All related repositories can be synced in either direction.

Git? Github? What's the difference?
Github is a service hosting git repositories in the web, but it is even more.
It is backed on git, but further introduces its own concepts. For example, it introduces a repository hierachy, called forks and the way how your local repositories interact with your own fork on github creates some kind of hierachy as well.

In simutrans-extended, you usually interact with three layers of repositories:
The topmost one is jamespetts/simutrans-extended. If your local changes made the long way into the master branch of that repository, these will be available in the next nightly release.

The second layer is your fork of jamespetts/simutrans-extended on github. Any commits that made their way over there are publicly available to anyoene else, so other people can test those changes or even base their own work on it.

The third layer is your local repository. Your commits will be stored there and you have much freedom of what you can do with these, before pushing the changes to your repository on github.

In the next section, we will interact between these. It's not as complicated as it might seem.

[jamespetts]

Excellent, thank you for this! I have stickied this.

[Mariculous]

A practical guide to git(hub) in simutrans-extended.

Prequisites:
I assume you have git installed on your system and you know how to use it from the commandline.

1. Setup a local repository of simurans-extended
- Create a fork of jamespetts/simutrans-extended on github.
- Initial local checkout of the fork: git clone https://github.com/<user>/simutrans.git
- Setup upstream: git remote add upstream https://github.com/jamespetts/simutrans-extended.git
The repository is ready now.

2. Prepare the feature branch
- checkout local master: git checkout master
- update local master: git pull upstream master
- optional: push updated master to your fork: git push
- create a new local feature branch git checkout -b <feature_branch_name>
Now the feature branch is ready and you can start coding on your new truly awesome feature.

3. Coding your truly awesome feature
- Make changes to the code until you think one step of the feature is implemented.
- Stage the changes: You have to tell git which changes you want to include into the commit: git add <space seperated list of files to add, asterisk works>
- Then commit the staged changes: git commit -m "<what has changed?>"
- optional: test the changes. It doesn't always make sense to test every single commit, but generally commits should offer a working state of the program. Don't worry if not. You can still rewrite the commit history later on.
Repeat this cycle, until you think your entire feature is ready for incorporation.

4. prepare your repository for the upstream
!!!Warning!!! the commands used in here are destructive commands.
Whilst it's totally fine to use them here, you should not use them to rewrite public repositories.

At first, you should get your feature branch up-to-date with latest master again: git pull --rebase upstream master
Then you might optionally clean up your commit history. This is an advanced operation. Please search the web for git rebase --interactive if you are interessted.

Further, you should intensively test your new feature at this point.
When you think it is ready and stable, carry on.

5. Finally, publish your changes
Run git push to publish your changes on your github repository.
Then you can create a pull request on github.

6. Returning to pending pull requests
Once you finished step 5, you might want to start the cycle again to develop a new feature.

As incorporation of the previous one is still pending, there might be change requests in the review progress.
To return to your previous feature, make sure there are no uncommitted changes in the directory. If there are any, I recommend to simply git add <files that changed> followed by git commit -m "work in prgress"
Then you can checkout your previous features branch as git checkout <feature_branch_name>

Then go back to coding until you think you have implemented the requested changes.
Do not continue to step 4!
If there are merge conflicts between your branch and upstream master, you can run git pull upstream and resolve the conflicts to get back in sync.
Once there are no merge conflicts between your branch and upstream master anymore, you should simply git push to publish your changes.
Your pull request will then automatically be updated to include these changes.

Now you can return to your new feature using git checkout <feature_branch_name> again.

Surely, the same procedure of switching between branches is not restricted to adjusting contents of a pull request. You might work on two features in parallel, then make some bugfixes on yet another branch and return to one of the feature branches again.
It is strongly recommended not to work on too many branches in parallel though.

[ceeac]

Setup upstream: git remote add upstream https://github.com/aburch/simutrans.git

Minor correction: This should point to James's repository.

[Mariculous]

Ooops.
Thanks, this should be fixed now.