| 1 |
[[toc ]] |
| 2 |
|
| 3 |
[[meta title="Contributing to cwidget"]] |
| 4 |
|
| 5 |
# Getting the development tree # |
| 6 |
|
| 7 |
While you can always work from the distributed source (see |
| 8 |
[[getting_cwidget|downloading]]), I recommend that you use the active |
| 9 |
development tree to ensure that your changes are compatible with the |
| 10 |
current state of cwidget. |
| 11 |
|
| 12 |
The cwidget development tree is managed using the [git][] version |
| 13 |
control system. You can install git using your operating system's |
| 14 |
utilities or by following the instructions on its [web page][git]. |
| 15 |
Once it is installed, issuing the command |
| 16 |
|
| 17 |
[git]: <http://git-scm.com/> |
| 18 |
|
| 19 |
> git clone git://git.debian.org/git/cwidget/cwidget-upstream.git cwidget |
| 20 |
|
| 21 |
will retrieve the latest version of the source and store it in a |
| 22 |
directory named <q>`cwidget`</q>. You can update this directory to |
| 23 |
the latest source version by changing to it and issuing the folowing |
| 24 |
command: |
| 25 |
|
| 26 |
> git pull |
| 27 |
|
| 28 |
git is a fully distributed version control system. This means that |
| 29 |
once you have made some changes to your copy of the source code, you |
| 30 |
can commit them by running |
| 31 |
|
| 32 |
> git add <file> |
| 33 |
|
| 34 |
for each `<file>` that you have modified, then running |
| 35 |
|
| 36 |
> git commit |
| 37 |
|
| 38 |
and typing a commit message. In order to make it easier for us to |
| 39 |
review your patches, I recommend making small, logically distinct |
| 40 |
commits rather than checking in 50 changes at once. If this means |
| 41 |
that you have dead-ends in your change history, that's fine. |
| 42 |
|
| 43 |
For more information on using git, see the [git documentation][]. |
| 44 |
|
| 45 |
[git documentation]: <http://git-scm.com/documentation> |
| 46 |
|
| 47 |
# Sending patches # |
| 48 |
|
| 49 |
Once you have committed some changes, you can automatically generate |
| 50 |
emails containing your patches: |
| 51 |
|
| 52 |
> git pull && git format-patch origin |
| 53 |
|
| 54 |
This command will generate one or more patches represnting your |
| 55 |
changes relative to the upstream tree, writing the names of the files |
| 56 |
to standard output: |
| 57 |
|
| 58 |
> daniel@alpaca:/tmp/cwidget$ git format-patch origin |
| 59 |
> 0001-A-simple-test-commit-to-try-bundling.patch |
| 60 |
|
| 61 |
|
| 62 |
Patches should be sent to [email protected]. You |
| 63 |
can use patches as email templates, for instance via |
| 64 |
|
| 65 |
> mutt -H 0001-A-simple-test-commit-to-try-bundling.patch [email protected] |
| 66 |
|
| 67 |
, or you can just attach the patches themselves to your email. Using |
| 68 |
the patch as a template is preferred, but may not be easy or possible |
| 69 |
in all mail readers. |
| 70 |
|
| 71 |
# Compiling the development tree # |
| 72 |
|
| 73 |
In addition to cwidget's normal |
| 74 |
[[prerequisites|install#prerequisites]], you will need the following |
| 75 |
additional pieces of software: |
| 76 |
|
| 77 |
* [autoconf][] |
| 78 |
* [automake][] |
| 79 |
* [libtool][] |
| 80 |
|
| 81 |
[autoconf]: <http://www.gnu.org/software/autoconf/> |
| 82 |
[automake]: <http://www.gnu.org/software/automake/> |
| 83 |
[libtool]: <http://www.gnu.org/software/libtool/> |
| 84 |
|
| 85 |
These tools allow you to generate the build system of cwidget. The |
| 86 |
build system can be generated by running |
| 87 |
|
| 88 |
> sh ./autogen.sh |
| 89 |
|
| 90 |
, which will create and run a configure script to build the Makefiles. |
| 91 |
Once `autogen` is finished, you can just run |
| 92 |
|
| 93 |
> make |
| 94 |
|
| 95 |
as usual to build the library. |