ContributingCode.wiki
author Wuzzy
Fri, 19 Apr 2019 16:07:50 +0100
changeset 1831 365c30b4c669
parent 1283 e490fc45e2ae
permissions -rw-r--r--
LuaGears: Add temporary mistake to test documentation script
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
870
55e67d58d19e ContributingCode: Edited via web interface
sheepluva
parents: 798
diff changeset
    45
That means: *Before you start writing code towards a new bugfix/feature, make sure to {{{hg update -r}}} to a revision from the official repository.*
720
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
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 773
diff changeset
    50
*You can see example of how unnamed branches and bookmarks are used best [https://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
768
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    53
= How to export your changes so that we can use them  =
728
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    54
769
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    55
== Public Repository ==
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    56
If you setup a public repository e.g. at github, bitbucket or on your own server, just push your commits there.
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    57
Then send us the links to the commits/bookmarks that you want to go into the official repository!
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    58
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    59
== Export mercurial commits ==
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    60
With {{{hg export --git -r commitid1 -rcommitid2 ... > my.patch}}} you can export the commits specified to a patch file.
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    61
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    62
Note: the {{{--git}}} argument is used, so that binary file changes (e.g. changed pictures), are included in the export.
728
1b0f7b17e748 ContributingCode: Edited via web interface
sheepluva
parents: 727
diff changeset
    63
769
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    64
== Creating a file containing the code differences ==
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    65
You can use the {{{diff}}} command (if available on your platform) to output the differences between e.g. the original code and yours.
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    66
Save that into a file and send it to us.
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    67
Note: Don't forget to also send binary files, so pictures/etc. that you changed - since usually {{{diff}}} will only cover text changes!
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    68
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    69
 
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    70
ccf2964c7497 ContributingCode: Edited via web interface
sheepluva
parents: 768
diff changeset
    71
If you have a mercurial clone of the official repository but you don't want to locally commit your changes for some reason, you can use use {{{hg diff --git > my.diff}}} to generate a diff file containing changes to code and binary files.
768
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    72
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    73
770
350db3641bcf ContributingCode: Edited via web interface
sheepluva
parents: 769
diff changeset
    74
= How to ask for patch inclusion in official repository =
768
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    75
1283
e490fc45e2ae ContributingCode: fix contact link
Wuzzy
parents: 1282
diff changeset
    76
Just send your patches (or links to them) to [https://hedgewars.org/contact.html the development mailing list]. Feel free to compress them as {{{tar.gz}}}, {{{tar.bz2}}} or {{{zip}}}.
768
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    77
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    78
Don't forget to add a short description (can be a copy of the commit message if it's explaining everything needed).
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    79
773
502c0dc0e381 ContributingCode: Edited via web interface
sheepluva
parents: 772
diff changeset
    80
*Note*: Please be aware that by sending in patches you grant unC0Rr (the project leader) *all rights* to the code (and any patents you may hold on it) and assets included in the patch.
768
6d2816127552 ContributingCode: Edited via web interface
sheepluva
parents: 728
diff changeset
    81
That implies that your code *will be made public* under the *[http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html GNU GPL2]*.