Fossil SCM

Assorted improvements to the "Contributing to Fossil" doc. The most substantial is replacement of references to the old mailing list with references to the forum. Added more info about patches and bundles, etc.

wyoung 2020-12-22 08:45 trunk
Commit 34205ea468e4fb46d2d8109d95ee8c4841ffe697cb84d6309a9c39aec62a8773
1 file changed +43 -28
--- www/contribute.wiki
+++ www/contribute.wiki
@@ -1,81 +1,96 @@
11
<title>Contributing To Fossil</title>
22
3
-Users are encouraged to contributed enhancements back to the Fossil
3
+Fossil users are encouraged to contributed enhancements back to the
44
project. This note outlines some of the procedures for making
55
useful contributions.
66
77
<h2>1.0 Contributor Agreement</h2>
88
9
-In order to accept your contributions, we <u>must</u> have a
9
+In order to accept non-trivial contributions, we <u>must</u> have a
1010
[./copyright-release.pdf | Contributor Agreement (PDF)]
1111
(or [./copyright-release.html | as HTML]) on file for you. We require
1212
this in order to maintain clear title to the Fossil code and prevent
1313
the introduction of code with incompatible licenses or other entanglements
14
-that might cause legal problems for Fossil users. Many larger companies
15
-and other lawyer-rich organizations require this as a precondition to using
14
+that might cause legal problems for Fossil users. Many
15
+lawyer-rich organizations require this as a precondition to using
1616
Fossil.
1717
1818
If you do not wish to submit a Contributor Agreement, we would still
1919
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
20
+directly: we will be forced to re-implement your changes from scratch, which
2121
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.
2225
2326
<h2>2.0 Submitting Patches</h2>
2427
2528
Suggested changes or bug fixes can be submitted by creating a patch
26
-against the current source tree. Email patches to
29
+against the current source tree:
30
+
31
+ <tt>fossil diff -i > my-change.patch</tt>
32
+
33
+Post patches to
34
+[https://fossil-scm.org/forum | the forum] or email them to
2735
<a href="mailto:[email protected]">[email protected]</a>. Be sure to
2836
describe in detail what the patch does and which version of Fossil
29
-it is written against.
30
-
31
-A contributor agreement is not strictly necessary to submit a patch.
32
-However, without a contributor agreement on file, your patch will be
33
-used for reference only - it will not be applied to the code. This
34
-may delay acceptance of your patch.
35
-
36
-Your patches or changes might not be accepted even if you do have
37
+it is written against. It's best to make patches against tip-of-trunk
38
+rather than against past releases.
39
+
40
+If your change is more complicated than a patch can properly encode, you
41
+may submit [/help?cmd=bundle | a Fossil bundle] instead. Unlike patches,
42
+bundles can contain multiple commits, check-in comments, file renames,
43
+file deletions, branching decisions, and more which <tt>patch(1)</tt>
44
+files cannot. It's best to make a bundle of a new branch so the change
45
+can be integrated, tested, enhanced, and merged down to trunk in a
46
+controlled fashion.
47
+
48
+A contributor agreement is not strictly necessary to submit a patch or bundle,
49
+but without a contributor agreement on file, your contribution will be
50
+used for reference only: it will not be applied to the code. This
51
+may delay acceptance of your contribution.
52
+
53
+Your contribution might not be accepted even if you do have
3754
a contributor agreement on file. Please do not take this personally
38
-or as an affront to your coding ability. Sometimes patches are rejected
55
+or as an affront to your coding ability. Sometimes contributions are rejected
3956
because they seem to be taking the project in a direction that the
40
-architect does not want to go. Or, there might be an alternative
57
+architect does not want to go. In other cases, there might be an alternative
4158
implementation of the same feature being prepared separately.
4259
4360
<h2>3.0 Check-in Privileges</h2>
4461
4562
Check-in privileges are granted on a case-by-case basis. Your chances
4663
of getting check-in privileges are much improved if you have a history
47
-of submitting quality patches and/or making thoughtful posts on the
48
-[http://www.mail-archive.com/[email protected]/ | mailing list].
49
-A contributor agreement is, of course, a prerequisite for check-in
64
+of submitting quality patches and/or making thoughtful posts on
65
+[https://fossil-scm.org/forum | the forum].
66
+A signed contributor agreement is, of course, a prerequisite for check-in
5067
privileges.</p>
5168
5269
Contributors are asked to make all non-trivial changes on a branch. The
5370
Fossil Architect (Richard Hipp) will merge changes onto the trunk.</p>
5471
55
-Contributors are required to following the
72
+Contributors are required to follow the
5673
[./checkin.wiki | pre-checkin checklist] prior to every check-in to
5774
the Fossil self-hosting repository. This checklist is short and succinct
5875
and should only require a few seconds to follow. Contributors
5976
should print out a copy of the pre-checkin checklist and keep
60
-it on a note card beside their workstations, for quick reference.
77
+it on a note card beside their workstations for quick reference.
6178
6279
Contributors should review the
6380
[./style.wiki | Coding Style Guidelines] and mimic the coding style
6481
used through the rest of the Fossil source code. Your code should
6582
blend in. A third-party reader should be unable to distinguish your
6683
code from any other code in the source corpus.
6784
6885
<h2>4.0 Testing</h2>
6986
70
-Fossil has the beginnings of a
71
-[../test/release-checklist.wiki | release checklist] but this is an
72
-area that needs further work. (Your contributions here are welcomed!)
73
-Contributors with check-in privileges are expected to run the release
74
-checklist on any major changes they contribute, and if appropriate expand
75
-the checklist and/or the automated test scripts to cover their additions.
76
-
87
+Fossil's [../test/release-checklist.wiki | release checklist] is of
88
+primary benefit to the project leader, followed by him at release time,
89
+but contributors are encouraged to run through its steps when making
90
+major changes, since if the change doesn't pass this checklist, it won't
91
+be included in the next release.
7792
7893
<h2>5.0 See Also</h2>
7994
8095
* [./build.wiki | How To Compile And Install Fossil]
8196
* [./makefile.wiki | The Fossil Build Process]
8297
--- www/contribute.wiki
+++ www/contribute.wiki
@@ -1,81 +1,96 @@
1 <title>Contributing To Fossil</title>
2
3 Users are encouraged to contributed enhancements back to the Fossil
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 your 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 larger companies
15 and other 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 <h2>2.0 Submitting Patches</h2>
24
25 Suggested changes or bug fixes can be submitted by creating a patch
26 against the current source tree. Email patches to
 
 
 
 
 
27 <a href="mailto:[email protected]">[email protected]</a>. Be sure to
28 describe in detail what the patch does and which version of Fossil
29 it is written against.
30
31 A contributor agreement is not strictly necessary to submit a patch.
32 However, without a contributor agreement on file, your patch will be
33 used for reference only - it will not be applied to the code. This
34 may delay acceptance of your patch.
35
36 Your patches or changes might not be accepted even if you do have
 
 
 
 
 
 
 
 
 
37 a contributor agreement on file. Please do not take this personally
38 or as an affront to your coding ability. Sometimes patches are rejected
39 because they seem to be taking the project in a direction that the
40 architect does not want to go. Or, there might be an alternative
41 implementation of the same feature being prepared separately.
42
43 <h2>3.0 Check-in Privileges</h2>
44
45 Check-in privileges are granted on a case-by-case basis. Your chances
46 of getting check-in privileges are much improved if you have a history
47 of submitting quality patches and/or making thoughtful posts on the
48 [http://www.mail-archive.com/[email protected]/ | mailing list].
49 A contributor agreement is, of course, a prerequisite for check-in
50 privileges.</p>
51
52 Contributors are asked to make all non-trivial changes on a branch. The
53 Fossil Architect (Richard Hipp) will merge changes onto the trunk.</p>
54
55 Contributors are required to following the
56 [./checkin.wiki | pre-checkin checklist] prior to every check-in to
57 the Fossil self-hosting repository. This checklist is short and succinct
58 and should only require a few seconds to follow. Contributors
59 should print out a copy of the pre-checkin checklist and keep
60 it on a note card beside their workstations, for quick reference.
61
62 Contributors should review the
63 [./style.wiki | Coding Style Guidelines] and mimic the coding style
64 used through the rest of the Fossil source code. Your code should
65 blend in. A third-party reader should be unable to distinguish your
66 code from any other code in the source corpus.
67
68 <h2>4.0 Testing</h2>
69
70 Fossil has the beginnings of a
71 [../test/release-checklist.wiki | release checklist] but this is an
72 area that needs further work. (Your contributions here are welcomed!)
73 Contributors with check-in privileges are expected to run the release
74 checklist on any major changes they contribute, and if appropriate expand
75 the checklist and/or the automated test scripts to cover their additions.
76
77
78 <h2>5.0 See Also</h2>
79
80 * [./build.wiki | How To Compile And Install Fossil]
81 * [./makefile.wiki | The Fossil Build Process]
82
--- www/contribute.wiki
+++ www/contribute.wiki
@@ -1,81 +1,96 @@
1 <title>Contributing To Fossil</title>
2
3 Fossil users are encouraged to contributed 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 <tt>fossil diff -i > my-change.patch</tt>
32
33 Post patches to
34 [https://fossil-scm.org/forum | the forum] or email them to
35 <a href="mailto:[email protected]">[email protected]</a>. Be sure to
36 describe in detail what the patch does and which version of Fossil
37 it is written against. It's best to make patches against tip-of-trunk
38 rather than against past releases.
39
40 If your change is more complicated than a patch can properly encode, you
41 may submit [/help?cmd=bundle | a Fossil bundle] instead. Unlike patches,
42 bundles can contain multiple commits, check-in comments, file renames,
43 file deletions, branching decisions, and more which <tt>patch(1)</tt>
44 files cannot. It's best to make a bundle of a new branch so the change
45 can be integrated, tested, enhanced, and merged down to trunk in a
46 controlled fashion.
47
48 A contributor agreement is not strictly necessary to submit a patch or bundle,
49 but without a contributor agreement on file, your contribution will be
50 used for reference only: it will not be applied to the code. This
51 may delay acceptance of your contribution.
52
53 Your contribution might not be accepted even if you do have
54 a contributor agreement on file. Please do not take this personally
55 or as an affront to your coding ability. Sometimes contributions are rejected
56 because they seem to be taking the project in a direction that the
57 architect does not want to go. In other cases, there might be an alternative
58 implementation of the same feature being prepared separately.
59
60 <h2>3.0 Check-in Privileges</h2>
61
62 Check-in privileges are granted on a case-by-case basis. Your chances
63 of getting check-in privileges are much improved if you have a history
64 of submitting quality patches and/or making thoughtful posts on
65 [https://fossil-scm.org/forum | the forum].
66 A signed contributor agreement is, of course, a prerequisite for check-in
67 privileges.</p>
68
69 Contributors are asked to make all non-trivial changes on a branch. The
70 Fossil Architect (Richard Hipp) will merge changes onto the trunk.</p>
71
72 Contributors are required to follow the
73 [./checkin.wiki | pre-checkin checklist] prior to every check-in to
74 the Fossil self-hosting repository. This checklist is short and succinct
75 and should only require a few seconds to follow. Contributors
76 should print out a copy of the pre-checkin checklist and keep
77 it on a note card beside their workstations for quick reference.
78
79 Contributors should review the
80 [./style.wiki | Coding Style Guidelines] and mimic the coding style
81 used through the rest of the Fossil source code. Your code should
82 blend in. A third-party reader should be unable to distinguish your
83 code from any other code in the source corpus.
84
85 <h2>4.0 Testing</h2>
86
87 Fossil's [../test/release-checklist.wiki | release checklist] is of
88 primary benefit to the project leader, followed by him at release time,
89 but contributors are encouraged to run through its steps when making
90 major changes, since if the change doesn't pass this checklist, it won't
91 be included in the next release.
 
 
92
93 <h2>5.0 See Also</h2>
94
95 * [./build.wiki | How To Compile And Install Fossil]
96 * [./makefile.wiki | The Fossil Build Process]
97

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button