ContributingCode.wiki
author Wuzzy
Sun, 17 Jan 2016 12:57:26 +0000
changeset 758 ecdd12db8754
parent 728 1b0f7b17e748
child 768 6d2816127552
permissions -rw-r--r--
ConfigurationFiles: Add title, fix header levels, simplify TOC
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
718
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     1
#summary Useful hints for contributing code to Hedgewars
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     2
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     3
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     4
*Table of Contents*
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     5
<wiki:toc max_depth="2" />
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     6
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     7
= Introduction =
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     8
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
     9
You want to contribute code to Hedgewars? That's great! Here are some hints how to help us with importing your code.
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    10
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    11
= Recommended workflows =
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    12
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    13
== Using a mercurial clone ==
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    14
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    15
TODO
e4e1597f6b84 New Page: ContributingCode
sheepluva
parents:
diff changeset
    16
721
76c078df2785 Edited via web interface
sheepluva
parents: 720
diff changeset
    17
=== Using (named) branches ===
727
8c4a065a898c Edited via web interface
sheepluva
parents: 726
diff changeset
    18
Branches are alternative commit histories.
8c4a065a898c Edited via web interface
sheepluva
parents: 726
diff changeset
    19
8c4a065a898c Edited via web interface
sheepluva
parents: 726
diff changeset
    20
The commits history from one branch, up to any commit, can be merged into other branches when needed.
8c4a065a898c Edited via web interface
sheepluva
parents: 726
diff changeset
    21
Note: In Mercurial merging a commit always means to also merge all its ancestor commits.
722
ea553850a74d Edited via web interface
sheepluva
parents: 721
diff changeset
    22
725
92086cbfde4c Edited via web interface
sheepluva
parents: 724
diff changeset
    23
_Most main development happens on the main repository branch "default"._
721
76c078df2785 Edited via web interface
sheepluva
parents: 720
diff changeset
    24
722
ea553850a74d Edited via web interface
sheepluva
parents: 721
diff changeset
    25
725
92086cbfde4c Edited via web interface
sheepluva
parents: 724
diff changeset
    26
We prefer *not* to use separate branches for little patches, as branches are permanent and will clutter the list of {{{hg branches}}}.
722
ea553850a74d Edited via web interface
sheepluva
parents: 721
diff changeset
    27
725
92086cbfde4c Edited via web interface
sheepluva
parents: 724
diff changeset
    28
*So for small code contributions, use "unnamed branches" instead (see below).*
721
76c078df2785 Edited via web interface
sheepluva
parents: 720
diff changeset
    29
725
92086cbfde4c Edited via web interface
sheepluva
parents: 724
diff changeset
    30
_However, if you are going to write code that is more a project than a patch and that will take dozens of commits, feel free to do that work on a new branch._
720
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    31
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    32
To create a new branch use {{{hg branch}}} followed by the name of the new branch, before committing the first code.
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    33
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    34
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    35
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    36
=== Using unnamed branches ===
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    37
723
d519f85c008f Edited via web interface
sheepluva
parents: 722
diff changeset
    38
_Unnamed branches_ a.k.a. _topological branches_ happen when the history of commits within a branch (e.g. "default") splits up into  alternative commits chains.
720
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    39
These alternative chains will have more than one {{{head}}} (at the the end of each chain) within the same branch, until they will be merged back together into a single chain.
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    40
723
d519f85c008f Edited via web interface
sheepluva
parents: 722
diff changeset
    41
*In order for us to be able which bugfixes/features of you we merge into the official repository, you should put each in a separate _unnamed branch_ as described above.*
720
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    42
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    43
Make sure that the first commit of each bugfix/feature commit set is based on a commit from the official repository, that way your bugfixes/features will not depend on the commits of each other and can be merged into official individually, as needed.
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    44
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    45
That means: *Before you start writing code towards a new bugfix/feature, make sure to {{{hg update}}} to a revision from the official repository.*
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    46
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    47
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    48
In newer versions of Mercurial you can give those unnamed branches a "local" and removable name using {{{hg bookmark}}}.
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    49
724
798364e1fd76 Edited via web interface
sheepluva
parents: 723
diff changeset
    50
*You can see example of how unnamed branches and bookmarks are used best [http://hg.hedgewars.org/hw-example-clone/graph HERE]*
720
03def791ae0b Edited via web interface
sheepluva
parents: 718
diff changeset
    51
728
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    52
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    53
= How to make your changes known and available to us  =
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    54
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    55
TODO: diffs, exported patches, public repo clone, etc.
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    56