Contributing to DOL with GitHub

A place to submit .patch fixes for the DOL SVN

Moderator: Developer Team

Contributing to DOL with GitHub

Postby Leodagan » Sun Nov 29, 2015 9:34 pm

Dawn of Light project is moving from Sourceforge.net Subversion Repository to GitHub.com Git Repository

Dawn Of Light Repositories

Organization Page : https://github.com/Dawn-of-Light

DOL Server (DOLSharp) Project Repository : https://github.com/Dawn-of-Light/DOLSharp

GitHub Wiki : https://github.com/Dawn-of-Light/DOLSharp/wiki

GitHub Gist to Share Text Snippets : https://gist.github.com

GitHub Workflow explained : https://guides.github.com/introduction/flow/

This How-To Gist for Editing : https://gist.github.com/dol-leodagan/12 ... e29e7e4075

Other projects will be converted to Git within Dawn-of-Light Organization.

Git Software

Git is a distributed code versioning system, there is no centralized repository like in Subversion, every user work on its own repository copy and can use all git command "offline", once your code edits are ready for publishing you can push your commits to an online repository or share it with your coworkers directly.

All remote references are handled as Branches, so you can switch between them easily to retrieve code or logs, or you can merge them to your local copy/branch to follow code changes.

Here are softwares you could need to work with Git :

Tortoise Git (Windows) : https://tortoisegit.org/download/
Portable Git Command Line (Windows) : https://github.com/sheabunge/GitPortable
GitHub Desktop Client (Windows/Mac) : https://desktop.github.com/
Git Command Line (Linux) : use your package Manager and look for "git" or "git-core" (check also for "gitk" or "git-gui" packages)
Other GUI : https://git-scm.com/download/gui/linux
Documentation : https://git-scm.com/doc

Getting Started

If you want to contribute easily to Dawn of Light sources the first thing to do is Fork the repository ! (If you just want to compile your own version of Latest Source a Clone should do...)

Browse to https://github.com/Dawn-of-Light/DOLSharp/ and hit the "Fork" button while logged in your GitHub account !

Image

Now you have your own copy of full Project History in your account, you can do anything you want without breaking anything in official repository !

You can now Clone Your repository locally to begin any work (or even use the few tools available from GitHub web view) and start creating your own branch for modification, keeping "master" branch even with DOL official repository so you can easily merge your work with current source.

Command Line :

Code: Select all
$ cd ~/any_working_directory
$ git clone https://github.com/[username}/DOLSharp/
$ cd DOLSharp
~~ configure upstream for master update with official repo ~~
$ git remote add upstream https://github.com/Dawn-of-Light/DOLSharp
$ git remote -v
origin  https://github.com/[username]/DOLSharp (fetch)
origin  https://github.com/[username]/DOLSharp (push)
upstream        https://github.com/Dawn-of-Light/DOLSharp (fetch)
upstream        https://github.com/Dawn-of-Light/DOLSharp (push)
~~ create your working branch and switch ~~
$ git branch working
$ git checkout working
Switched to branch 'working'


We create a Clone repository of Remote Fork, then create an own branch "working".
We set an "upstream" remote reference to Official Repository so we can update our Fork with upcoming changes.

For TortoiseGit User's, it's pretty much like working with TortoiseSVN, you just use Git Contextual Menu to Clone the repository with GUI options :

Image
Image
Image
Image
Image
Image
Image
Image


You are now working in your own local branch, you can make some changes to any file save them and try your first commit.
Git use a "Staged Area" where modifications are tracked but not committed to repository, using TortoiseGit you can still use "old style" commits which will auto-add modified files, using command line you have to explicitly add your files to staging area or auto-add them on commit.


Command Line :

Code: Select all
./DOLSharp/:$
~~ check your branch ~~
$ git branch
* working
  master
~~ edit README.md for example ~~
~~ check your files ~~
$ git status
On branch working
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")
$ git add README.md
$ git status
On branch working
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   README.md

$ git diff HEAD README.md
diff --git a/README.md b/README.md
index 115a244..f5fa218 100644
--- a/README.md
+++ b/README.md
@@ -25,3 +25,4 @@ Documentation
  - Getting Started: [Official Forum](http://www.dolserver.net/index.php)
  - Coding: [Wiki Home](https://github.com/Dawn-of-Light/DOLSharp/wiki)

+Edition for my Fork !
~~ Now we have checked and staged our modifications, let's commit ~~
$ git commit -m "Added : My first Git Commit !"
[working 01a2fdd] Added : My first Git Commit !
 1 file changed, 1 insertion(+)
$ git log
commit 01a2fdd8553f73e746f50e5e3749ade94d4ca266
Author: dol-leodagan <leodagan@durron.net>
Date:   Sun Nov 29 13:15:57 2015 +0100

    Added : My first Git Commit !
~~ Finally Merge with "master" branch to prepare a Pull request ~~
$ git checkout master
Switched to branch 'master'
~~ update against upstream/master to be able to merge easily ~~
$ git fetch upstream
$ git merge upstream/master
~~ now merge your change to the updated master ~~
$ git merge working
Updating 555332d..01a2fdd
Fast-forward
 README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
$ git status
git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean
~~ finally publish your changes ~~
$ git push origin


The workflow is : Edit your working branch, commit to your working branch, switch (checkout) to master branch, fetch and merge upstream master branch so you have an up to date branch to Project Official repository, then merge your working branch update to the local up to date master, finally push the change to your user repository on GitHub so you can start a Pull Request !

Image
Image
Image
Image
Image
Image
Image
Image
Image
Image
Image
Image
Image


From there you can use GitHub Web to create your Pull Request :

Image

If you only make atomic changes and don't want to use all the working branch workflow you can still edit directly your Fork's master branch and produce Pull Request, you can run in some troubles if you heavily edit your Fork's master and your changes are not pulled into official repository, later upstream Merge will become difficult...


Finally don't forget to keep your working branch up to date !

Command Line :

Code: Select all
~~ Change to your working branch ~~
$ git checkout working
Switched to branch 'working'
$ git merge master
...


Simply switch to your working branch and merge any change you may have "pulled" from upstream

Image
Image
Image
Image




Set your Authoring Identity for Subversion Commit

When migrating Subversion to GitHub, it needs Author E-mail mapping to match the correct GitHub account to Sourceforge username...
Subversion repository have a lot of inactive contributors, so I used the Sourceforge mail alias for most of users.

The Sourceforge alias should be something like [sf-username]@users.sourceforge.net and forward to your private registered Sourceforge email, this way you can confirm in GitHub you are the owner of this account !

Image

The complete mapping is available here : viewtopic.php?f=16&t=21369&p=156812#p156812

After setting your email(s), all commit matching any address will display your GitHub Account

Don't forget to set your identity in Git Client for easier Commit Authoring :

Command Line :

Code: Select all
$ git config --global user.email "your_email@example.com"
$ git config --global user.name "MyUsername"


For TortoiseGit :

Image
Image


Pull Request and Continuous Integration

GitHub allows a pretty efficient Patch Merging process using Pull Request, in subversion you had to build a patch file matching all your change, then transmit this patch to someone with Commit Rights to apply it to current SVN source tree, if you were not a registered contributor, and the authoring was made with the committer credits...

With Git the "Rights Management System" only apply to the Centralized Official Repository, but you can do any updates in your own repository (Forked) or local repository (Cloned on your computer), you have the full range of Git versioning tools available just for you, and Git is made to follow distributed change so you can easily export your updates to an other user repository or the Centralized repository (if any...) especially if you share common references (updating a Clone/Fork)

GitHub has build a specific workflow around remote branch Merges, which is the process of upgrading someone else Git repository with the exported updates you made to a common source tree, this is the Pull Request

The main steps to do this is simply using the GitHub Web, browse to your own forked repository containing updates, use the New Pull Request button and start comparing your changes to Official Repository to make sure it match the update you want to provide to current Code Base, then you just need to add Title/Description and provide some explanations for your update, this will immediately create a "Ticket" to the main repository tracking this patch to be imported in main source tree, and give all the proper credits to whomever contributed even after the patch is merged in official repository.

Image
Image
Image

You can then display your pull request Status in Official Repository, this will sum up all the contributors working on this "Ticket", what commit is being exported, display differences between files involved in patch, and finally, thanks to Continuous Integration Service, your patch will be automatically tested on the current source tree to make sure the resulting Merge will be able to build or even run Unit Tests, this will provide a good starting point to prevent any patch from breaking the source tree :)

Image

This "Ticket" is working some way like an "Issue" Ticket or other bugs report tracking systems, we can discuss on it, add more code update to improve the merged patch, choose to apply it or discard completely...
It's way more efficient than forum topics/posts to track code patch, and it's integrated nicely into GitHub with all references needed to Git Repository (and continuous integration is really a powerful tool !)


GitHub Wiki and Issues

GitHub offer a Wiki repository for every project, even if this is not a powerful Wiki engine, it works with simple MarkDown Syntax and allow to share and update documentation with a pretty efficient Web access.

Every Forum Topic with How-to Guide, Any user provided Article or any Tips and Tricks resource can go in there, we'll worry about how we sort such data when we'll have some !

GitHub Wiki : https://github.com/Dawn-of-Light/DOLSharp/wiki

Some of the first needed article would be new guide on how to build or use DOL from GitHub repository !

GitHub also offer an efficient Issues Tracker, well DOL have so much issues right now I don't know how it could be fit in this...

Please try to use the Issues Tracker for identified bugs with as much data as you can provide on how to fix the issue, I don't think we'll be able to fix pretty hard bugs any faster by tracking them, but maybe "whole" feature request could fit in there ;)

And don't forget, GitHub have some social Features ! You can Follow People to receive notifications, you can "Star" Projects to keep updated, you can comment almost everywhere :)

Image
Image
Image


Migration TODO List

* Storm RvR Latest Source update (Storm is actually updating on Sourceforge and should Checkout Git Code)
* Nightly Builds (Need auto building hook and releases, update links available on DOL Website)
* Website Source Links Update (Mostly for DOL Server page)
* Portal Setup distribution and auto-update Moved to gh-pages
* Continuous Integration Setup with Pull Request Testing
Last edited by Leodagan on Wed Dec 02, 2015 10:32 am, edited 5 times in total.
Reason: Made announce, more visible !
User avatar
Leodagan
Developer
 
Posts: 1303
Joined: Tue May 01, 2012 9:30 am
Location: Lyon

Re: Contributing to DOL with GitHub

Postby HunabKu » Mon Nov 30, 2015 9:43 am

You rox !
"C'est l'ignorance qui apporte le chaos, pas la connaissance."
Scarlett Johansson dans "Lucy" de Luc Besson
-------------------------------------------------------------------------------
"Ignorance brings chaos, not knowledge."
Scarlett Johansson on "Lucy" by Luc Besson
User avatar
HunabKu
Developer
 
Posts: 1813
Joined: Sat Jun 18, 2011 4:48 am

Re: Contributing to DOL with GitHub

Postby Tolakram » Mon Nov 30, 2015 2:48 pm

Very nice overview, very very nice. :)
- Mark
User avatar
Tolakram
Storm / Storm-D2 Admin
 
Posts: 9181
Joined: Tue Jun 13, 2006 1:49 am
Location: Kentucky, USA

Re: Contributing to DOL with GitHub

Postby Leodagan » Tue Dec 01, 2015 1:17 pm

Updated Guide with Pull Request and Continuous Integration.

Don't forget to register your Source Forge mail alias in your GitHub account Mail address book to be matched correctly as Contributors in the newly exported Git Repository :)
User avatar
Leodagan
Developer
 
Posts: 1303
Joined: Tue May 01, 2012 9:30 am
Location: Lyon

Re: Contributing to DOL with GitHub

Postby Graveen » Wed Dec 02, 2015 9:35 am

Concise, clear, understandable, excellent work ! /worship
--
i'm totally aware GITHub workflow will need to be mastered by beginners. To ease this, i'll assign to a key for fasters answers on this forum : URL of this guide and https://guides.github.com/introduction/flow/index.html

TY Leo!
Image
* pm me to contribute in Dawn of Light: code, database *
User avatar
Graveen
Project Leader
 
Posts: 12536
Joined: Fri Oct 19, 2007 9:22 pm
Location: France

Re: Contributing to DOL with GitHub

Postby Leodagan » Wed Dec 02, 2015 8:06 pm

And Now DOL Server has complete Continuous Integration with Fine-Grained Releases :

https://github.com/Dawn-of-Light/DOLSha ... ses/latest
User avatar
Leodagan
Developer
 
Posts: 1303
Joined: Tue May 01, 2012 9:30 am
Location: Lyon


Return to DOL Code Contributions

Who is online

Users browsing this forum: No registered users and 1 guest