|
1
|
<title>Contributing To Fossil</title> |
|
2
|
|
|
3
|
Fossil users are encouraged to contribute enhancements back to the |
|
4
|
project. This note outlines some of the procedures for making |
|
5
|
useful contributions. |
|
6
|
|
|
7
|
<h2>1.0 Contributor Agreement</h2> |
|
8
|
|
|
9
|
In order to accept non-trivial contributions, we <u>must</u> have a |
|
10
|
[./copyright-release.pdf | Contributor Agreement (PDF)] |
|
11
|
(or [./copyright-release.html | as HTML]) on file for you. We require |
|
12
|
this in order to maintain clear title to the Fossil code and prevent |
|
13
|
the introduction of code with incompatible licenses or other entanglements |
|
14
|
that might cause legal problems for Fossil users. Many |
|
15
|
lawyer-rich organizations require this as a precondition to using |
|
16
|
Fossil. |
|
17
|
|
|
18
|
If you do not wish to submit a Contributor Agreement, we would still |
|
19
|
welcome your suggestions and example code, but we will not use your code |
|
20
|
directly: we will be forced to re-implement your changes from scratch, which |
|
21
|
might take longer. |
|
22
|
|
|
23
|
We've made exceptions for "trivial" changes in the past, but the |
|
24
|
definition of that term is up to the project leader. |
|
25
|
|
|
26
|
<h2>2.0 Submitting Patches</h2> |
|
27
|
|
|
28
|
Suggested changes or bug fixes can be submitted by creating a patch |
|
29
|
against the current source tree: |
|
30
|
|
|
31
|
<pre>fossil diff -i > my-change.patch</pre> |
|
32
|
|
|
33
|
Alternatively, you can create a binary patch: |
|
34
|
|
|
35
|
<pre>fossil patch create my-change.db</pre> |
|
36
|
|
|
37
|
Post patches to |
|
38
|
[https://fossil-scm.org/forum | the forum] or email them to |
|
39
|
<a href="mailto:[email protected]">[email protected]</a>. Be sure to |
|
40
|
describe in detail what the patch does and which version of Fossil |
|
41
|
it is written against. It's best to make patches against tip-of-trunk |
|
42
|
rather than against past releases. |
|
43
|
|
|
44
|
If your change is more complicated than a patch can properly encode, you |
|
45
|
may submit [/help/bundle | a Fossil bundle] instead. Unlike patches, |
|
46
|
bundles can contain multiple commits, check-in comments, file renames, |
|
47
|
file deletions, branching decisions, and more which <tt>patch(1)</tt> |
|
48
|
files cannot. It's best to make a bundle of a new branch so the change |
|
49
|
can be integrated, tested, enhanced, and merged down to trunk in a |
|
50
|
controlled fashion. |
|
51
|
|
|
52
|
A contributor agreement is not strictly necessary to submit a patch or bundle, |
|
53
|
but without a contributor agreement on file, your contribution will be |
|
54
|
used for reference only: it will not be applied to the code. This |
|
55
|
may delay acceptance of your contribution. |
|
56
|
|
|
57
|
Your contribution might not be accepted even if you do have |
|
58
|
a contributor agreement on file. Please do not take this personally |
|
59
|
or as an affront to your coding ability. Sometimes contributions are rejected |
|
60
|
because they seem to be taking the project in a direction that the |
|
61
|
architect does not want to go. In other cases, there might be an alternative |
|
62
|
implementation of the same feature being prepared separately. |
|
63
|
|
|
64
|
<h2>3.0 Check-in Privileges</h2> |
|
65
|
|
|
66
|
Check-in privileges are granted on a case-by-case basis. Your chances |
|
67
|
of getting check-in privileges are much improved if you have a history |
|
68
|
of submitting quality patches and/or making thoughtful posts on |
|
69
|
[https://fossil-scm.org/forum | the forum]. |
|
70
|
A signed contributor agreement is, of course, a prerequisite for check-in |
|
71
|
privileges.</p> |
|
72
|
|
|
73
|
Contributors are asked to make all non-trivial changes on a branch. The |
|
74
|
Fossil Architect (Richard Hipp) will merge changes onto the trunk.</p> |
|
75
|
|
|
76
|
Contributors are required to follow the |
|
77
|
[./checkin.wiki | pre-checkin checklist] prior to every check-in to |
|
78
|
the Fossil self-hosting repository. This checklist is short and succinct |
|
79
|
and should only require a few seconds to follow. Contributors |
|
80
|
should print out a copy of the pre-checkin checklist and keep |
|
81
|
it on a note card beside their workstations for quick reference. |
|
82
|
|
|
83
|
Contributors should review the |
|
84
|
[./style.wiki | Coding Style Guidelines] and mimic the coding style |
|
85
|
used through the rest of the Fossil source code. Your code should |
|
86
|
blend in. A third-party reader should be unable to distinguish your |
|
87
|
code from any other code in the source corpus. |
|
88
|
|
|
89
|
<h2>4.0 Testing</h2> |
|
90
|
|
|
91
|
Fossil's [../test/release-checklist.wiki | release checklist] is of |
|
92
|
primary benefit to the project leader, followed by him at release time, |
|
93
|
but contributors are encouraged to run through its steps when making |
|
94
|
major changes, since if the change doesn't pass this checklist, it won't |
|
95
|
be included in the next release. |
|
96
|
|
|
97
|
<h2>5.0 UI and Documentation Language</h2> |
|
98
|
|
|
99
|
The Fossil project uses American English in its web interface and |
|
100
|
documentation. Until there is some provision for translating the UI and |
|
101
|
docs into other languages and dialects, we ask that you do not commit |
|
102
|
changes that conflict with this. |
|
103
|
|
|
104
|
We aren't opposed to such a project, but it would be a huge amount of |
|
105
|
work, which no one's stepped up to do yet. Not only is each individual |
|
106
|
translation a large ongoing job its own right, there is no |
|
107
|
infrastructure for it yet, so the first few translations will be harder |
|
108
|
than any future translation built on that infrastructure. |
|
109
|
|
|
110
|
More immediately, we're likely to reject, revert, or rework commits that |
|
111
|
use other English dialects. One example that comes up occasionally is |
|
112
|
"artefact" versus "artifact." The UI and docs use the American English |
|
113
|
spelling pervasively, so you have poor options if you insist on |
|
114
|
"artefact:" |
|
115
|
|
|
116
|
* attempt to slip one-off changes by your peers |
|
117
|
* attempt to change all American English usages to Commonwealth English |
|
118
|
* make the Fossil UI and docs translatable, then contribute a |
|
119
|
Commonwealth English translation |
|
120
|
|
|
121
|
Only the latter is likely to succeed. |
|
122
|
|
|
123
|
<h2>6.0 See Also</h2> |
|
124
|
|
|
125
|
* [./build.wiki | How To Compile And Install Fossil] |
|
126
|
* [./makefile.wiki | The Fossil Build Process] |
|
127
|
* [./tech_overview.wiki | A Technical Overview of Fossil] |
|
128
|
* [./adding_code.wiki | Adding Features To Fossil] |
|
129
|
|