1# Contributing 2 3## Mailing list 4 5The main communication tool in use is the Yocto Project mailing list: 6 7* <yocto@lists.yoctoproject.org> 8* <https://lists.yoctoproject.org/g/yocto> 9 10Feel free to ask any kind of questions but please always prepend your email 11subject with `[meta-raspberrypi]` as this is the global *Yocto* mailing 12list and not a dedicated *meta-raspberrypi* mailing list. 13 14## Formatting patches 15 16First and foremost, all of the contributions to the layer must be compliant 17with the standard openembedded patch guidelines: 18 19* <http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines> 20 21In summary, your commit log messages should be formatted as follows: 22 23 <layer-component>: <short log/statement of what needed to be changed> 24 25 (Optional pointers to external resources, such as defect tracking) 26 27 The intent of your change. 28 29 (Optional: if it's not clear from above, how your change resolves 30 the issues in the first part) 31 32 Signed-off-by: Your Name <yourname@youremail.com> 33 34The `<layer-component>` is the layer component name that your changes affect. 35It is important that you choose it correctly. A simple guide for selecting a 36a good component name is the following: 37 38* For changes that affect *layer recipes*, please just use the **base names** 39 of the affected recipes, separated by commas (`,`), as the component name. 40 For example: use `omxplayer` instead of `omxplayer_git.bb`. If you are 41 adding new recipe(s), just use the new recipe(s) base name(s). An example 42 for changes to multiple recipes would be `userland,vc-graphics,wayland`. 43* For changes that affect the *layer documentation*, please just use `docs` 44 as the component name. 45* For changes that affect *other files*, i.e. under the `conf` directory, 46 please use the full path as the component name, e.g. `conf/layer.conf`. 47* For changes that affect the *layer itself* and do not fall into any of 48 the above cases, please use `meta-raspberrypi` as the component name. 49 50A full example of a suitable commit log message is below: 51 52 foobar: Adjusted the foo setting in bar 53 54 When using foobar on systems with less than a gigabyte of RAM common 55 usage patterns often result in an Out-of-memory condition causing 56 slowdowns and unexpected application termination. 57 58 Low-memory systems should continue to function without running into 59 memory-starvation conditions with minimal cost to systems with more 60 available memory. High-memory systems will be less able to use the 61 full extent of the system, a dynamically tunable option may be best, 62 long-term. 63 64 The foo setting in bar was decreased from X to X-50% in order to 65 ensure we don't exhaust all system memory with foobar threads. 66 67 Signed-off-by: Joe Developer <joe.developer@example.com> 68 69A common issue during patch reviewing is commit log formatting, please review 70the above formatting guidelines carefully before sending your patches. 71 72## Sending patches 73 74The preferred method to contribute to this project is to send pull 75requests to the GitHub mirror of the layer: 76 77* <https://github.com/agherzan/meta-raspberrypi> 78 79**In addition**, you may send patches for review to the above specified 80mailing list. In this case, when creating patches using `git` please make 81sure to use the following formatting for the message subject: 82 83 git format-patch -s --subject-prefix='meta-raspberrypi][PATCH' origin 84 85Then, for sending patches to the mailing list, you may use this command: 86 87 git send-email --to yocto@lists.yoctoproject.org <generated patch> 88 89When patches are sent through the mailing list, the maintainer will include 90them in a GitHub pull request that will take the patches through the CI 91workflows. This process happens periodically. 92 93## GitHub issues 94 95In order to manage and track the layer issues more efficiently, the 96GitHub issues facility is used by this project: 97 98* <https://github.com/agherzan/meta-raspberrypi/issues> 99 100If you submit patches that have a GitHub issue associated, please make sure to 101use standard GitHub keywords, e.g. `closes`, `resolves` or `fixes`, before the 102"Signed-off-by" tag to close the relevant issues automatically: 103 104 foobar: Adjusted the foo setting in bar 105 106 Fixes: #324 107 108 Signed-off-by: Joe Developer <joe.developer@example.com> 109 110More information on the available GitHub close keywords can be found here: 111 112* <https://help.github.com/articles/closing-issues-using-keywords> 113 114