author | Wuzzy |
Fri, 21 Jun 2019 22:41:51 +0100 | |
changeset 1920 | fea4b9719045 |
parent 1283 | e490fc45e2ae |
permissions | -rw-r--r-- |
718 | 1 |
#summary Useful hints for contributing code to Hedgewars |
2 |
||
3 |
||
4 |
*Table of Contents* |
|
5 |
<wiki:toc max_depth="2" /> |
|
6 |
||
7 |
= Introduction = |
|
8 |
||
9 |
You want to contribute code to Hedgewars? That's great! Here are some hints how to help us with importing your code. |
|
10 |
||
11 |
= Recommended workflows = |
|
12 |
||
13 |
== Using a mercurial clone == |
|
14 |
||
15 |
TODO |
|
16 |
||
721 | 17 |
=== Using (named) branches === |
727 | 18 |
Branches are alternative commit histories. |
19 |
||
20 |
The commits history from one branch, up to any commit, can be merged into other branches when needed. |
|
21 |
Note: In Mercurial merging a commit always means to also merge all its ancestor commits. |
|
722 | 22 |
|
725 | 23 |
_Most main development happens on the main repository branch "default"._ |
721 | 24 |
|
722 | 25 |
|
725 | 26 |
We prefer *not* to use separate branches for little patches, as branches are permanent and will clutter the list of {{{hg branches}}}. |
722 | 27 |
|
725 | 28 |
*So for small code contributions, use "unnamed branches" instead (see below).* |
721 | 29 |
|
725 | 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 | 31 |
|
32 |
To create a new branch use {{{hg branch}}} followed by the name of the new branch, before committing the first code. |
|
33 |
||
34 |
||
35 |
||
36 |
=== Using unnamed branches === |
|
37 |
||
723 | 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 | 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. |
40 |
||
723 | 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 | 42 |
|
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. |
|
44 |
||
870 | 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 | 46 |
|
47 |
||
48 |
In newer versions of Mercurial you can give those unnamed branches a "local" and removable name using {{{hg bookmark}}}. |
|
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 | 51 |
|
728 | 52 |
|
768 | 53 |
= How to export your changes so that we can use them = |
728 | 54 |
|
769 | 55 |
== Public Repository == |
56 |
If you setup a public repository e.g. at github, bitbucket or on your own server, just push your commits there. |
|
57 |
Then send us the links to the commits/bookmarks that you want to go into the official repository! |
|
58 |
||
59 |
== Export mercurial commits == |
|
60 |
With {{{hg export --git -r commitid1 -rcommitid2 ... > my.patch}}} you can export the commits specified to a patch file. |
|
61 |
||
62 |
Note: the {{{--git}}} argument is used, so that binary file changes (e.g. changed pictures), are included in the export. |
|
728 | 63 |
|
769 | 64 |
== Creating a file containing the code differences == |
65 |
You can use the {{{diff}}} command (if available on your platform) to output the differences between e.g. the original code and yours. |
|
66 |
Save that into a file and send it to us. |
|
67 |
Note: Don't forget to also send binary files, so pictures/etc. that you changed - since usually {{{diff}}} will only cover text changes! |
|
68 |
||
69 |
||
70 |
||
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 | 72 |
|
73 |
||
770 | 74 |
= How to ask for patch inclusion in official repository = |
768 | 75 |
|
1283 | 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 | 77 |
|
78 |
Don't forget to add a short description (can be a copy of the commit message if it's explaining everything needed). |
|
79 |
||
773 | 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 | 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]*. |