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.
Commit
34205ea468e4fb46d2d8109d95ee8c4841ffe697cb84d6309a9c39aec62a8773
Parent
1997b71cf7327ce…
1 file changed
+43
-28
+43
-28
| --- www/contribute.wiki | ||
| +++ www/contribute.wiki | ||
| @@ -1,81 +1,96 @@ | ||
| 1 | 1 | <title>Contributing To Fossil</title> |
| 2 | 2 | |
| 3 | -Users are encouraged to contributed enhancements back to the Fossil | |
| 3 | +Fossil users are encouraged to contributed enhancements back to the | |
| 4 | 4 | project. This note outlines some of the procedures for making |
| 5 | 5 | useful contributions. |
| 6 | 6 | |
| 7 | 7 | <h2>1.0 Contributor Agreement</h2> |
| 8 | 8 | |
| 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 | |
| 10 | 10 | [./copyright-release.pdf | Contributor Agreement (PDF)] |
| 11 | 11 | (or [./copyright-release.html | as HTML]) on file for you. We require |
| 12 | 12 | this in order to maintain clear title to the Fossil code and prevent |
| 13 | 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 | |
| 14 | +that might cause legal problems for Fossil users. Many | |
| 15 | +lawyer-rich organizations require this as a precondition to using | |
| 16 | 16 | Fossil. |
| 17 | 17 | |
| 18 | 18 | If you do not wish to submit a Contributor Agreement, we would still |
| 19 | 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 | |
| 20 | +directly: we will be forced to re-implement your changes from scratch, which | |
| 21 | 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. | |
| 22 | 25 | |
| 23 | 26 | <h2>2.0 Submitting Patches</h2> |
| 24 | 27 | |
| 25 | 28 | 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 | |
| 27 | 35 | <a href="mailto:[email protected]">[email protected]</a>. Be sure to |
| 28 | 36 | 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 | |
| 37 | 54 | 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 | |
| 39 | 56 | 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 | |
| 41 | 58 | implementation of the same feature being prepared separately. |
| 42 | 59 | |
| 43 | 60 | <h2>3.0 Check-in Privileges</h2> |
| 44 | 61 | |
| 45 | 62 | Check-in privileges are granted on a case-by-case basis. Your chances |
| 46 | 63 | 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 | |
| 50 | 67 | privileges.</p> |
| 51 | 68 | |
| 52 | 69 | Contributors are asked to make all non-trivial changes on a branch. The |
| 53 | 70 | Fossil Architect (Richard Hipp) will merge changes onto the trunk.</p> |
| 54 | 71 | |
| 55 | -Contributors are required to following the | |
| 72 | +Contributors are required to follow the | |
| 56 | 73 | [./checkin.wiki | pre-checkin checklist] prior to every check-in to |
| 57 | 74 | the Fossil self-hosting repository. This checklist is short and succinct |
| 58 | 75 | and should only require a few seconds to follow. Contributors |
| 59 | 76 | 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. | |
| 61 | 78 | |
| 62 | 79 | Contributors should review the |
| 63 | 80 | [./style.wiki | Coding Style Guidelines] and mimic the coding style |
| 64 | 81 | used through the rest of the Fossil source code. Your code should |
| 65 | 82 | blend in. A third-party reader should be unable to distinguish your |
| 66 | 83 | code from any other code in the source corpus. |
| 67 | 84 | |
| 68 | 85 | <h2>4.0 Testing</h2> |
| 69 | 86 | |
| 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. | |
| 77 | 92 | |
| 78 | 93 | <h2>5.0 See Also</h2> |
| 79 | 94 | |
| 80 | 95 | * [./build.wiki | How To Compile And Install Fossil] |
| 81 | 96 | * [./makefile.wiki | The Fossil Build Process] |
| 82 | 97 |
| --- 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 |