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