CONTRIBUTING.md (6692B)
1 # Contributing 2 3 ## Submitting patches 4 5 *Most of this comes from the linux kernel guidelines for submitting 6 patches, we follow many of the same guidelines. These are very important! 7 If you want your code to be accepted, please read this carefully* 8 9 Describe your problem. Whether your patch is a one-line bug fix or 10 5000 lines of a new feature, there must be an underlying problem that 11 motivated you to do this work. Convince the reviewer that there is a 12 problem worth fixing and that it makes sense for them to read past the 13 first paragraph. 14 15 Once the problem is established, describe what you are actually doing 16 about it in technical detail. It's important to describe the change 17 in plain English for the reviewer to verify that the code is behaving 18 as you intend it to. 19 20 The maintainer will thank you if you write your patch description in a 21 form which can be easily pulled into Damus's source code tree. 22 23 **Solve only one problem per patch**. If your description starts to get 24 long, that's a sign that you probably need to split up your patch. See 25 the dedicated `Separate your changes` section because this is very 26 important. 27 28 Describe your changes in imperative mood, e.g. "make xyzzy do frotz" 29 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy 30 to do frotz", as if you are giving orders to the codebase to change 31 its behaviour. 32 33 If your patch fixes a bug, use the 'Closes:' tag with a URL referencing 34 the report in the mailing list archives or a public bug tracker. For 35 example: 36 37 Closes: https://github.com/damus-io/damus/issues/1234 38 39 Some bug trackers have the ability to close issues automatically when a 40 commit with such a tag is applied. Some bots monitoring mailing lists can 41 also track such tags and take certain actions. Private bug trackers and 42 invalid URLs are forbidden. 43 44 If your patch fixes a bug in a specific commit, e.g. you found an issue using 45 ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of 46 the SHA-1 ID, and the one line summary. Do not split the tag across multiple 47 lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify 48 parsing scripts. For example:: 49 50 Fixes: 54a4f0239f2e ("Fix crash in navigation") 51 52 The following ``git config`` settings can be used to add a pretty format for 53 outputting the above style in the ``git log`` or ``git show`` commands:: 54 55 [core] 56 abbrev = 12 57 [pretty] 58 fixes = Fixes: %h (\"%s\") 59 60 An example call:: 61 62 $ git log -1 --pretty=fixes 54a4f0239f2e 63 Fixes: 54a4f0239f2e ("Fix crash in navigation") 64 65 66 ### Separate your changes 67 68 Separate each **logical change** into a separate patch. 69 70 For example, if your changes include both bug fixes and performance 71 enhancements for a particular feature, separate those changes into two or 72 more patches. If your changes include an API update, and a new feature 73 which uses that new API, separate those into two patches. 74 75 On the other hand, if you make a single change to numerous files, group 76 those changes into a single patch. Thus a single logical change is 77 contained within a single patch. 78 79 The point to remember is that each patch should make an easily understood 80 change that can be verified by reviewers. Each patch should be justifiable 81 on its own merits. 82 83 When dividing your change into a series of patches, take special care to 84 ensure that the Damus builds and runs properly after each patch in the 85 series. Developers using ``git bisect`` to track down a problem can end 86 up splitting your patch series at any point; they will not thank you if 87 you introduce bugs in the middle. 88 89 If you cannot condense your patch set into a smaller set of patches, 90 then only post say 15 or so at a time and wait for review and integration. 91 92 Include `patch changelogs` which describe what has changed between the v1 and 93 v2 version of the patch. 94 95 ### Sign your work - the Developer's Certificate of Origin 96 97 To improve tracking of who did what, especially with patches that can 98 percolate to their final resting place in the Damus through several 99 layers of maintainers, we've introduced a "sign-off" procedure on 100 patches that are being emailed around. 101 102 The sign-off is a simple line at the end of the explanation for the 103 patch, which certifies that you wrote it or otherwise have the right to 104 pass it on as an open-source patch. The rules are pretty simple: if you 105 can certify the below: 106 107 Developer's Certificate of Origin 1.1 108 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 109 110 By making a contribution to this project, I certify that: 111 112 (a) The contribution was created in whole or in part by me and I 113 have the right to submit it under the open source license 114 indicated in the file; or 115 116 (b) The contribution is based upon previous work that, to the best 117 of my knowledge, is covered under an appropriate open source 118 license and I have the right under that license to submit that 119 work with modifications, whether created in whole or in part 120 by me, under the same open source license (unless I am 121 permitted to submit under a different license), as indicated 122 in the file; or 123 124 (c) The contribution was provided directly to me by some other 125 person who certified (a), (b) or (c) and I have not modified 126 it. 127 128 (d) I understand and agree that this project and the contribution 129 are public and that a record of the contribution (including all 130 personal information I submit with it, including my sign-off) is 131 maintained indefinitely and may be redistributed consistent with 132 this project or the open source license(s) involved. 133 134 then you just add a line saying: 135 136 Signed-off-by: Random J Developer <random@developer.example.org> 137 138 This will be done for you automatically if you use `git commit -s`. 139 Reverts should also include "Signed-off-by". `git revert -s` does that 140 for you. 141 142 Any further SoBs (Signed-off-by:'s) following the author's SoB are from 143 people handling and transporting the patch, but were not involved in its 144 development. SoB chains should reflect the **real** route a patch took 145 as it was propagated to the maintainers and ultimately to Will, with 146 the first SoB entry signalling primary authorship of a single author. 147 148 ### Add Changelog-Changed, Changelog-Fixed, etc 149 150 If you have a *user facing* change that you would like to include in Damus 151 changelogs, please include: 152 153 - Changelog-Changed: Changed the heart button to a shaka 154 - Changelog-Fixed: Fixed notes not appearing on profile 155 - Changelog-Added: Added a cool new feature 156 - Changelog-Removed: Removed zaps 157 158 The changelog script will pick these up and give you attribution for your 159 change 160