CONTRIBUTING.md

   1 # Contributing to waffle
   2
   3 Thanks for taking the time to contribute to waffle!
   4
   5 If you want to submit changes, you can send GitLab [merge requests]. In addition
   6 you can open issues and feature requests on our [GitLab tracker].
   7
   8 In this file you can find:
   9   * [License and SPDX](#license-and-spdx)
  10   * [Commit style and history](#commit-style-and-history)
  11   * [Using commit trailers](#using-commit-trailers)
  12     + [Signed-off-by](#signed-off-by)
  13     + [Issues, feature requests](#issues--feature-requests)
  14     + [Discussions, references](#discussions--references)
  15     + [Bugfixes, regressions](#bugfixes--regressions)
  16   * [Coding style](#coding-style)
  17   * [API manual pages](#api-manual-pages)
  18   * [Shell completion](#shell-completion)
  19
  20 ## License and SPDX
  21
  22 The project uses `BSD-2-Clause` for everything but the manual pages, which are
  23 under `CC BY-SA 3.0 US`. All new changes and additions must be licensed under
  24 the same license.
  25
  26 When adding new files use the respective `SPDX-FileCopyrightText:` and
  27 `SPDX-License-Identifier:` instead of the complete license text.
  28
  29 ## Commit style and history
  30
  31 The waffle project uses a [linear, "recipe" style] history. This means that
  32 commits should be small, digestible, stand-alone, and functional.
  33
  34 Commit messages are in imperative mood and merges are to be avoided.
  35
  36 When in doubt, or need a refresher, checking through the output of `git log` is
  37 highly recommended.
  38
  39 ## Using commit trailers
  40
  41 Commit messages, apart from stating why a particular change is made, can include
  42 a range of trailers.
  43
  44 ### Signed-off-by
  45
  46 By using a `Signed-off-by:` trailer you agree that you comply with the
  47 [Developer Certificate of Origin v1.1], as found in the Linux kernel v3.15.
  48
  49     Developer's Certificate of Origin 1.1
  50
  51     By making a contribution to this project, I certify that:
  52
  53     (a) The contribution was created in whole or in part by me and I
  54         have the right to submit it under the open source license
  55         indicated in the file; or
  56
  57     (b) The contribution is based upon previous work that, to the best
  58         of my knowledge, is covered under an appropriate open source
  59         license and I have the right under that license to submit that
  60         work with modifications, whether created in whole or in part
  61         by me, under the same open source license (unless I am
  62         permitted to submit under a different license), as indicated
  63         in the file; or
  64
  65     (c) The contribution was provided directly to me by some other
  66         person who certified (a), (b) or (c) and I have not modified
  67         it.
  68
  69     (d) I understand and agree that this project and the contribution
  70         are public and that a record of the contribution (including all
  71         personal information I submit with it, including my sign-off) is
  72         maintained indefinitely and may be redistributed consistent with
  73         this project or the open source license(s) involved.
  74
  75 ### Issues, feature requests
  76
  77 Whenever a patch resolves a particular issue, be that one on our [GitHub
  78 tracker] or elsewhere, use the `Closes:` trailer followed by the full URL.
  79
  80     Closes: https://gitlab.freedesktop.org/mesa/waffle/-/issues/118
  81
  82 ### Discussions, references
  83
  84 If your commit covers a topic raised in an issue, but does not resolve the issue
  85 itself; or otherwise refers to a more complicated topic, you can use
  86 `Reference:`.
  87
  88 ### Bugfixes, regressions
  89
  90 Nobody is perfect and regressions happen from time to time. Whenever a commit
  91 addresses a regression caused by another commit, use `Fixes:` as below:
  92
  93     Fixes: 2c33597 ("wayland: fix build against version 1.20")
  94
  95 ## Coding style
  96
  97 The project uses style practically identical to the kernel style. You can see
  98 the in-tree [coding-style file](doc/coding-style.txt) for quick references.
  99
 100 We also have a [.clang-format file](.clang-format) to ease and enforce the
 101 style. Make sure you run `git-clang-format` against your changes, before
 102 submitting MRs.
 103
 104 ## API manual pages
 105
 106 Our manual pages are written in xml and we're in the process of converting them
 107 to [scdoc] which uses a simple [markdown-like syntax]. Please make sure to
 108 update them as you add new options to the waffle tools.
 109
 110 ## Shell completion
 111
 112 The project provides `bash`, `zsh` and `fish` shell completions for all the
 113 waffle tools. When adding new tools and enhancing existings ones, make sure to
 114 keep them up-to date.
 115
 116 [merge requests]: https://gitlab.freedesktop.org/mesa/waffle/-/merge_requests
 117 [GitLab tracker]: https://gitlab.freedesktop.org/mesa/waffle/-/issues
 118 [linear, "recipe" style]: https://www.bitsnbites.eu/git-history-work-log-vs-recipe/
 119 [scdoc]: https://sr.ht/~sircmpwn/scdoc/
 120 [markdown-like syntax]: https://man.archlinux.org/man/scdoc.5.en