Dawn of Light

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 !



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 :











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 !
















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



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









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 !



The complete mapping is available here : http://www.dolserver.net/viewtopic.php? ... 12#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 :





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.





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



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






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

You rox !

Very nice overview, very very nice.

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

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!

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

https://github.com/Dawn-of-Light/DOLSha ... ses/latest