Free and Open Source real time strategy game with a new take on micro-management

Difference between revisions of "Mercurial"

From Globulation2

Jump to: navigation, search
(Notify about the migration to Git.)
 
(36 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{UserManualLinks}}
==Browsing the Mercurial Repository==
You can Browse the Mercurial repository of this project with your web browser. This gives you a good picture of the current status of the source files. You may also view the complete histories of any file in the repository as well as differences among two versions.


{{warning|Migration to GitHub|Following Bitbucket's decision to shut down its mercurial support, the Globulation 2 project migrated to a [[Git]] repository hosted on GitHub. This page is only kept for posterity.}}
* [http://hg.globulation2.org/glob2/ Browse the Globulation 2 Source Repository]


== Browsing the Project Repository ==
At https://bitbucket.org/giszmo/glob2 you can browse through the repository.
==Getting a Copy of the Mercurial Repository==
===Anonymous Mercurial Access===
This project's Mercurial repository can be checked out through with the following instruction set:
:hg clone http://hg.globulation2.org/glob2/
There is only one glob2 branch which almost always guarantees a functioning glob2. This branch is called "master". '''So you certainly want to do'''
:hg clone -r master http://hg.globulation2.org/glob2/
instead of the clone command above.


== Tools ==
Once you have a cloned repository, you can simply update it with
;hg: To really access a mercurial repository you need mercurial. You can get it from your distribution if you are running Linux or from [http://www.selenic.com/mercurial the mercurial homepage]. An in depth manual of hg you can find [http://hgbook.red-bean.com/read/ here].
:hg pull -r master http://hg.globulation2.org/glob2/
;tortoise-hg: To generally access hg repositories at a file system level you might want to use a GUI. [http://tortoisehg.bitbucket.org/ Tortoise-HG] is just great for that.
inside the cloned directory. This reduces the net traffic drastically.
;HGE: The mercurial plugin for Eclipse is another great way to navigate our repository. You need Eclipse (the CDT-version) and can then get HGE by going to help -> install new software... -> Add... -> Location = http://cbes.javaforge.com/update -> checking mercurial eclipse ...


== Getting a Copy of the Mercurial Repository ==
===Project Member Mercurial Access via HTTPS===
No matter if you want to contribute with write access or just want to get a read only copy of glob2, you should cd to a directory where you have write permissions and run hg clone:
Member access is performed using the Mercurial over HTTPS method. Access can be given by providing [[User:Nct]] with a username and password by emailing him at stephane [at] magnenat [dot] net
cd ~/my_hg_repositories
hg clone https://bitbucket.org/giszmo/glob2
cd glob2
The same can be achieved using HGE or tortoise-HG.


== Which revision to use ==
This project's Mercurial repository can be checked out through member Mercurial access with the following instruction set:
Having cloned the repository you now have all the history of glob2 at hands. According to your intents you now might want to choose different revisions to jump to and start working on them. Pick from the subsections what most fits your intents:
:hg clone -r master https://hg.globulation2.org/glob2/

=== The player ===
If you want to play against others you need the same '''major''' version of glob2 as they have. If they have betaX.4 you should pick some betaX version. You get the latest version in the betaX release candidate branch using the tip of betaX-rc. To get there issue
hg update betaX-rc

In rare occasions this version might not work. To get a version that was tagged for being released, check the output of
hg tags
for lines matching betaX.y and update to the highest y:
hg update betaX.y

=== The tester ===
If you want to test the latest not yet released version of glob2 you should update to the tip of the latest release candidate (-rc) branch:
hg update betaY-rc
or if a feature freeze was not yet decided on, you can also test the latest version of the default branch:
hg update default

=== The bug fixer ===
You might have started as a tester but now want to actually touch code. Now it is getting slightly more complicated. Having found a bug and a solution to it means applying the fix to the right revision. As bugs often are not only bugs of not yet released features but also express in years old versions you should fix the oldest relevant version. If on the download page beta4 is still promoted, you should fix this and merge your changes up to beta5 and finally to default. In hg this is pretty easy to do:
hg update beta4-rc
do your changes to the code ....
hg commit -m"fixed bug xy ..."
hg update beta5-rc
hg merge beta4-rc
hg commit -m"merge"
hg update default
hg merge beta5-rc
hg commit -m"merge"
Depending on how important the bug-fix was you might now want to directly tag the new versions:
hg tag beta4-rc beta4.X
hg tag beta5-rc beta5.Y

=== The mini-features guy ===
If you have a new small feature to contribute, you do this in "default":
hg update default
do your changes to the code ...
hg commit -m"implemented mini-feature xy"

=== The big-features guy ===
If you have a new big feature to contribute, you do this in a separate branch starting at "default":
hg update default
hg branch fooFeature
work on your feature with a series of
change code
hg commit -m"changed this and that"
but while you work on your feature don't miss to get in sync with the changing "default" by doing as follows:
hg pull
hg merge -r default
hg commit -m"merge"
once your feature is ready to be used in the game just like other features, merge it into default:
hg update default
hg merge fooFeature
hg commit -m"merged"

== Publishing changes ==
All the above was read only from the point of view of the main glob2-repository. If you have changes worth sharing you must make them public. Easiest is to pick one of the free mercurial hosters. If you go for [https://bitbucket.org bit bucket] you can fork [[User:Giszmo|Giszmo]]'s [https://bitbucket.org/giszmo/glob2 repository].
With your own bitbucket setup you can check for what would push
hg outgoing https://bitbucket.org/yourBBNick/glob2
and push your changes there:
hg push https://bitbucket.org/yourBBNick/glob2

Now after you checked all is fine you can ask on the glob2 mailing list for someone with write access to the main repo to pull your changes. Asking on the irc is an option, too but for bigger changes you review might take some time and then it is safer to do it via the mailing list.

Don't forget to change the authors file if it's your first contribution ;)

If you are a regular contributor you may get write permissions for the central repo from [[User:Nct|Nct]]. You can mail him your username and password at stephane [at] magnenat [dot] net.


==Mercurial Newbies==
==Mercurial Newbies==
If you've never used Mercurial, you should read some documentation about it; a useful URL is http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart. Using Mercurial is not complex but you have to understand what is going on. The best way to start is to ask a friend to show you the way, or pop onto the [irc://irc.globulation2.org/glob2 glob2 development] IRC channel and ask there.
If you've never used Mercurial, you should read some documentation about it; a useful URL is http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart. Using Mercurial is not complex but you have to understand what is going on. The best way to start is to ask a friend to show you the way, or pop onto the [irc://irc.globulation2.org/glob2 glob2 development] IRC channel and ask there.
===A quick overview of Mercurial===
===A quick overview of Mercurial===
Basically you have to know that there is not total order on a mercurial repository. Each revision exept the initial revision has at least one parent. And different revisions can have the same parent(s). A revision will have more than one parent, if and only if it is a merge of those parents.<br /><br />
Basically you have to know that there is not total order on a mercurial repository. Each revision except the initial revision has at least one parent. Different revisions can have the same parent(s). A revision will have more than one parent, if and only if it is a merge of those parents.

If two or more revisions share a parent, we have infact different branches in the repository. The new mercurial feature allows to give a revision a sticky tag that is past to almost all its children. Exeptions are merges. If you merge branch A into branch B, this revision will belong to branch B. So when you merge the master branch into a development branch, the result will belong to the development branch. This is good because you can keep track of approved changes, during your development now and then.<br /><br />
If two or more revisions share a parent, we have infact different branches in the repository. The new mercurial feature allows to give a revision a sticky tag that is past to almost all its children. Exeptions are merges. If you merge branch A into branch B, this revision will belong to branch B. So when you merge the default branch into a development branch, the result will belong to the development branch. This is good because you can keep track of approved changes, during your development now and then.<br /><br />
Branches don't have names, unless you give them a name. I don't know whether the names have to be unique. So multiple branches were supported all the time. The new feature

just allows to name them. You can put the branchname everywhere you can put a revision number. So all commands that have ''''-r'''' or ''''-rev'''' option accept a branchname too. Mercurial will then search the latest revision in that branch and path its number to the command. (At least that's what I think it does.)<br /><br />
*A tag name is associated with a revision ID number.
If every branch (named or not) has the same "latest revision", our repository will have exactly 1 head. Otherwise we will have more heads and mercurial will suppose that we merge the heads. But most of the time this would be inappropriate, and we shouldn't do it.<br /><br />
*A branch name should represent the '''tipmost''' revision of that branch.
The latest revision is always called tip, and mercurial defaults to think that we want to work on it. This is also very sad, if it does belong to an other branch. I really recomment that you only pull the branch you want to use. You can do this, because the clone and pull commands have a ''''-r'''' option. I pull the whole repository on my computer and than pull the branches that I want to work on, from that local repository to different working repositories. I suggest everyone should do this. So there is one incoming repository, one or more working repository and one outgoing repository locally on my computer.<br /><br />
*The special tag "'''tip'''" is '''always identifies the most recent revision'''.
Our master branch I called "'''master'''". But the first twothousendsomething revisions of that branch have no name.<br /><br />

Glob2 players should always pull the master branch. Unfortunately we can't force them.<br /><br />
Branches might have names, unless you give them a name.Their names don't have to be unique but it is strengthy recommended to don't use an already given name branch to another. So multiple branches were supported all the time. The new feature just allows to name them. You can put the branchname everywhere you can put a revision number. So all commands that have ''''-r'''' or ''''-rev'''' option accept a branchname too. Mercurial will then search the latest revision in that branch and path its number to the command. (At least that's what I think it does.)
You can try everything mercurial locally before pushing to the remote repository.<br /><br />

"'''hg log'''", "'''hg diff'''", "'''hg branch'''", "'''hg heads'''", "'''hg incoming'''", "'''hg outgoing'''" and "'''hg status'''" are very helpfull. Oh, and "'''hg help'''" and "'''hg help <command>'''" too.<br /><br />
{{message|HINT for Tags name & branch|Since tag names have priority over branch names during revision lookup, using an existing branch name as a tag name is discouraged.
Please look into the extentions.<br />
Tag and branch names must not contain the ":" character.Note that because '''revision numbers''' may be different in different repository clones, the branch tip may be different in different cloned repositories.
"hg view" is very good for an graphical overview of the repository

structure, though it seems not to display the branch names.
For Further details please visit the '''[http://www.selenic.com/mercurial/hg.1.html#tag HG MAN PAGE]'''.}}
And you definetly have to set up a merge tool for those case when

you have to merge manually.<br /><br />
If every branch (named or not) has the same "latest revision", our repository will have exactly 1 head. Otherwise we will have more heads and mercurial will suppose that we merge the heads. But most of the time this would be inappropriate, and we shouldn't do it.

The latest revision is always called tip, and mercurial defaults to think that we want to work on it. This is also very sad, if it does belong to an other branch. I really recomment that you only pull the branch you want to use. You can do this, because the clone and pull commands have a ''''-r'''' option. I pull the whole repository on my computer and than pull the branches that I want to work on, from that local repository to different working repositories. I suggest everyone should do this. So there is one incoming repository, one or more working repository and one outgoing repository locally on my computer.

Our "trunk" or default branch is called "'''default'''".
You can try everything with mercurial locally before pushing to the remote repository.
hg log
hg diff
hg branches
hg heads
hg tags
hg incoming
hg outgoing
hg status
are very helpful to get information. Try "hg help" for details.


hg serve //and browsing to localhost:8000
Branching of should look like this:<br /><br />
is very good for a graphical overview of the repository structure. If you prefer using a GUI tool, go for [http://tortoisehg.bitbucket.org/ Tortoise-HG].
In case you don't want to branch from the tip of your local repository:<br />
And you definitely have to set up a merge tool for those case when you have to merge manually.
"'''hg revert --all -r <revision from which you want to branch of>'''"<br />
"'''hg branch <branchname>'''"<br />
"'''hg commit'''"<br />
done.<br /><br />


Branching of should look like this:
Cloning from a branch:<br />
"'''hg clone -r <branchname> <location of the repository> <name that you want your repository to have>'''"<br />
Pulling from a branch:<br />
"'''hg pull -r <branchname> <location of the repository>'''"


*Branch from a revision other than the tip of your local repository:
hg revert --all -r <revision from which you want to branch of>
hg branch <branchname>
hg commit -m "message"
*Cloning from a branch:
''Using -r/--rev (or 'clone src#rev dest') implies --pull, even for local source''. repositories.
hg clone -r <branchname> <location of the repository> <name that you want your repository to have>
*Pulling from a branch:
'Ppulling is implicitly engage when -r option is set within the clone command.''
hg pull -r <branchname> <location of the repository>


[[Category:en]]
==Older source code==
[[Category:User Manual]]
For revisions and branches older than the new Mercurial setup, visit [[CVS]]. This code could be quite old by the time you read this, so its advised that you use the latest code instead.
[[Category:Developer_Resources]]

Latest revision as of 14:49, 15 February 2021

Main User Resources: User Manual | Frequently Asked Questions | Map editor guide | YOG
Game specific arguments: Resources | Buildings | Units | Combat | Flags and special areas | Farming | Graphs | Statistics | Prestige | Fruit and conversion
Building from Sources: Git | Compiling
Migration to GitHub: Following Bitbucket's decision to shut down its mercurial support, the Globulation 2 project migrated to a Git repository hosted on GitHub. This page is only kept for posterity.

Browsing the Project Repository

At https://bitbucket.org/giszmo/glob2 you can browse through the repository.

Tools

hg
To really access a mercurial repository you need mercurial. You can get it from your distribution if you are running Linux or from the mercurial homepage. An in depth manual of hg you can find here.
tortoise-hg
To generally access hg repositories at a file system level you might want to use a GUI. Tortoise-HG is just great for that.
HGE
The mercurial plugin for Eclipse is another great way to navigate our repository. You need Eclipse (the CDT-version) and can then get HGE by going to help -> install new software... -> Add... -> Location = http://cbes.javaforge.com/update -> checking mercurial eclipse ...

Getting a Copy of the Mercurial Repository

No matter if you want to contribute with write access or just want to get a read only copy of glob2, you should cd to a directory where you have write permissions and run hg clone:

cd ~/my_hg_repositories
hg clone https://bitbucket.org/giszmo/glob2
cd glob2

The same can be achieved using HGE or tortoise-HG.

Which revision to use

Having cloned the repository you now have all the history of glob2 at hands. According to your intents you now might want to choose different revisions to jump to and start working on them. Pick from the subsections what most fits your intents:

The player

If you want to play against others you need the same major version of glob2 as they have. If they have betaX.4 you should pick some betaX version. You get the latest version in the betaX release candidate branch using the tip of betaX-rc. To get there issue

hg update betaX-rc

In rare occasions this version might not work. To get a version that was tagged for being released, check the output of

hg tags

for lines matching betaX.y and update to the highest y:

hg update betaX.y

The tester

If you want to test the latest not yet released version of glob2 you should update to the tip of the latest release candidate (-rc) branch:

hg update betaY-rc

or if a feature freeze was not yet decided on, you can also test the latest version of the default branch:

hg update default

The bug fixer

You might have started as a tester but now want to actually touch code. Now it is getting slightly more complicated. Having found a bug and a solution to it means applying the fix to the right revision. As bugs often are not only bugs of not yet released features but also express in years old versions you should fix the oldest relevant version. If on the download page beta4 is still promoted, you should fix this and merge your changes up to beta5 and finally to default. In hg this is pretty easy to do:

hg update beta4-rc
do your changes to the code ....
hg commit -m"fixed bug xy ..."
hg update beta5-rc
hg merge beta4-rc
hg commit -m"merge"
hg update default
hg merge beta5-rc
hg commit -m"merge"

Depending on how important the bug-fix was you might now want to directly tag the new versions:

hg tag beta4-rc beta4.X
hg tag beta5-rc beta5.Y

The mini-features guy

If you have a new small feature to contribute, you do this in "default":

hg update default
do your changes to the code ...
hg commit -m"implemented mini-feature xy"

The big-features guy

If you have a new big feature to contribute, you do this in a separate branch starting at "default":

hg update default
hg branch fooFeature

work on your feature with a series of

change code
hg commit -m"changed this and that"

but while you work on your feature don't miss to get in sync with the changing "default" by doing as follows:

hg pull
hg merge -r default
hg commit -m"merge"

once your feature is ready to be used in the game just like other features, merge it into default:

hg update default
hg merge fooFeature
hg commit -m"merged"

Publishing changes

All the above was read only from the point of view of the main glob2-repository. If you have changes worth sharing you must make them public. Easiest is to pick one of the free mercurial hosters. If you go for bit bucket you can fork Giszmo's repository. With your own bitbucket setup you can check for what would push

hg outgoing https://bitbucket.org/yourBBNick/glob2

and push your changes there:

hg push https://bitbucket.org/yourBBNick/glob2

Now after you checked all is fine you can ask on the glob2 mailing list for someone with write access to the main repo to pull your changes. Asking on the irc is an option, too but for bigger changes you review might take some time and then it is safer to do it via the mailing list.

Don't forget to change the authors file if it's your first contribution ;)

If you are a regular contributor you may get write permissions for the central repo from Nct. You can mail him your username and password at stephane [at] magnenat [dot] net.

Mercurial Newbies

If you've never used Mercurial, you should read some documentation about it; a useful URL is http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart. Using Mercurial is not complex but you have to understand what is going on. The best way to start is to ask a friend to show you the way, or pop onto the glob2 development IRC channel and ask there.

A quick overview of Mercurial

Basically you have to know that there is not total order on a mercurial repository. Each revision except the initial revision has at least one parent. Different revisions can have the same parent(s). A revision will have more than one parent, if and only if it is a merge of those parents.

If two or more revisions share a parent, we have infact different branches in the repository. The new mercurial feature allows to give a revision a sticky tag that is past to almost all its children. Exeptions are merges. If you merge branch A into branch B, this revision will belong to branch B. So when you merge the default branch into a development branch, the result will belong to the development branch. This is good because you can keep track of approved changes, during your development now and then.

  • A tag name is associated with a revision ID number.
  • A branch name should represent the tipmost revision of that branch.
  • The special tag "tip" is always identifies the most recent revision.

Branches might have names, unless you give them a name.Their names don't have to be unique but it is strengthy recommended to don't use an already given name branch to another. So multiple branches were supported all the time. The new feature just allows to name them. You can put the branchname everywhere you can put a revision number. So all commands that have '-r' or '-rev' option accept a branchname too. Mercurial will then search the latest revision in that branch and path its number to the command. (At least that's what I think it does.)

HINT for Tags name & branch: Since tag names have priority over branch names during revision lookup, using an existing branch name as a tag name is discouraged.

Tag and branch names must not contain the ":" character.Note that because revision numbers may be different in different repository clones, the branch tip may be different in different cloned repositories.

For Further details please visit the HG MAN PAGE.

If every branch (named or not) has the same "latest revision", our repository will have exactly 1 head. Otherwise we will have more heads and mercurial will suppose that we merge the heads. But most of the time this would be inappropriate, and we shouldn't do it.

The latest revision is always called tip, and mercurial defaults to think that we want to work on it. This is also very sad, if it does belong to an other branch. I really recomment that you only pull the branch you want to use. You can do this, because the clone and pull commands have a '-r' option. I pull the whole repository on my computer and than pull the branches that I want to work on, from that local repository to different working repositories. I suggest everyone should do this. So there is one incoming repository, one or more working repository and one outgoing repository locally on my computer.

Our "trunk" or default branch is called "default". You can try everything with mercurial locally before pushing to the remote repository.

hg log
hg diff
hg branches
hg heads
hg tags
hg incoming
hg outgoing
hg status

are very helpful to get information. Try "hg help" for details.

hg serve //and browsing to localhost:8000

is very good for a graphical overview of the repository structure. If you prefer using a GUI tool, go for Tortoise-HG. And you definitely have to set up a merge tool for those case when you have to merge manually.

Branching of should look like this:

  • Branch from a revision other than the tip of your local repository:
hg revert --all -r <revision from which you want to branch of>
hg branch <branchname>
hg commit -m "message"
  • Cloning from a branch:

Using -r/--rev (or 'clone src#rev dest') implies --pull, even for local source. repositories.

hg clone -r <branchname> <location of the repository> <name that you want your repository to have>
  • Pulling from a branch:

'Ppulling is implicitly engage when -r option is set within the clone command.

hg pull -r <branchname> <location of the repository>
Misc