wiki: add documents explain the rules

Closes #530

Signed-off-by: Konrad Weihmann <[email protected]>

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,7 @@
 ## New feature
 
 - [ ] A testcase was added to test the behavior
+- [ ] ``wiki-creator.py`` was run and a new wiki document was filled with information
 - [ ] New functions are documented with docstrings
 - [ ] No debug code is left
 - [ ] README.md was updated to reflect the changes (check even if n.a.)

docs/wiki/oelint.append.protvars.md

@@ -0,0 +1,25 @@
+# oelint.append.protvars
+
+severity: error
+
+## Example
+
+In `my-random-%.bbappend`
+
+```
+LICENSE = "MIT"
+LIC_FILES_CHKSUM = "foo;md5sum=f3e466264f6a083f8febd2b6921ce8c2"
+PR = "4"
+PV = "4"
+SRCREV = "f161ebd29699d93411cec0915c5133c0f3229a28"
+```
+
+## Why is this bad?
+
+This will obscure the license detection and change detection, leading to unpredictable effects, like
+missing rebuilds or missed out license changes.
+
+## Ways to fix it
+
+- do **NOT** use any of ``LICENSE``, ``LIC_FILES_CHKSUM``, ``PR``, ``PV`` or ``SRCREV`` in ``*.bbappend``
+- create a copy of the recipe instead and use `PREFERRED_PROVIDER` instead

docs/wiki/oelint.bbclass.underscores.md

@@ -0,0 +1,17 @@
+# oelint.bbclass.underscores
+
+severity: error
+
+## Example
+
+`my-class.bbclass`
+
+## Why is this bad?
+
+Bitbake tries to create shell and/or python functions out of the base name of the class when
+using ``EXPORT_FUNCTIONS`` in this particular class.
+``-`` is unfortunately not a valid symbol in neither shell nor python.
+
+## Ways to fix it
+
+Use ``_`` instead of ``-`` in the filename.

docs/wiki/oelint.exportfunction.dash.md

@@ -0,0 +1,23 @@
+# oelint.exportfunction.dash
+
+severity: error
+
+## Example
+
+In ``my_class.bbclass``
+
+```
+EXPORT_FUNCTIONS my_class_do-install
+```
+
+## Why is this bad?
+
+Bitbake tries to create shell and/or python functions out of the base name of the class when
+using ``EXPORT_FUNCTIONS``.
+``-`` is unfortunately not a valid symbol in neither shell nor python.
+
+## Ways to fix it
+
+```
+EXPORT_FUNCTIONS my_class_do_install
+```

docs/wiki/oelint.file.inactiveupstreamdetails.md

@@ -0,0 +1,40 @@
+# oelint.file.inactiveupstreamdetails
+
+severity: info
+
+## Example
+
+With `my.patch`
+
+```
+Upstream-Status: Inactive-Upstream
+```
+
+or 
+
+```
+Upstream-Status: Inactive-Upstream [1234]
+```
+
+## Why is this bad?
+
+``Inactive-Upstream`` shall name a timestamp when the last activity was seen upstream,
+see former [OpenEmbedded contribution guide](https://www.openembedded.org/index.php?title=Commit_Patch_Message_Guidelines&oldid=10935)
+
+## Ways to fix it
+
+```
+Inactive-Upstream [lastcommit: 11.11.2011]
+```
+
+or
+
+```
+Inactive-Upstream [lastrelease: 11.11.2011]
+```
+
+or even
+
+```
+Inactive-Upstream [lastcommit: 11.11.2011, lastrelease: 11.11.2011]
+```

docs/wiki/oelint.file.inappropriatemsg.md

@@ -0,0 +1,50 @@
+# oelint.file.inappropriatemsg
+
+severity: info
+
+## Example
+
+With `my.patch`
+
+```
+Upstream-Status: Inappropriate [me don't care]
+```
+
+or
+
+```
+Upstream-Status: Inappropriate
+```
+
+or
+
+```
+Upstream-Status: Inappropriate (configuration)
+```
+
+## Why is this bad?
+
+``Inappropriate`` will create technical debt, as the will never be merged upstream,
+so labelling why this patch is needed is essential for tracking.
+See [OpenEmbedded contribution guide](https://www.openembedded.org/index.php?title=Commit_Patch_Message_Guidelines&oldid=10935)
+
+## Ways to fix it
+
+```
+Inappropriate [licensing]
+```
+
+or any other reason in the square brackets from the following list
+
+- oe-specific
+- OE specific
+- oe-core specific
+- not author
+- native
+- configuration
+- enable feature
+- disable feature
+- bugfix .*
+- embedded specific
+- no upstream
+- other

docs/wiki/oelint.file.includenotfound.md

@@ -0,0 +1,35 @@
+# oelint.file.includenotfound
+
+severity: warning
+
+## Example
+
+```
+include this/file/does/not/exist.inc
+```
+
+or
+
+```
+include a/file/from/another/layer.inc
+```
+
+
+## Why is this bad?
+
+If the an include file doesn't reside in the same layer, it creates an external dependency on something
+that is likely beyond the control of the layer.
+It will create breakage if the other layer changes the name and/or the path of the include file.
+
+Or the include simply doesn't exit at all.
+
+## Ways to fix it
+
+Fix the include path or
+
+```
+# noelint: oelint.file.includenotfound
+include a/file/from/another/layer.inc
+```
+
+in case the include file is from another layer.

docs/wiki/oelint.file.includerelpath.md

@@ -0,0 +1,23 @@
+# oelint.file.includerelpath
+
+severity: warning
+
+## Example
+
+```
+include ../../include-file.inc
+```
+
+## Why is this bad?
+
+This makes assumptions about the layout, how layers are stored on the storage of the local
+workspace.
+If now someone places the files in a different layout, the include will be broken.
+
+## Ways to fix it
+
+Use a relative path from the layer root instead
+
+```
+include recipes-something/some-path/include-file.inc
+```

docs/wiki/oelint.file.inlinesuppress_na.md

@@ -0,0 +1,23 @@
+# oelint.file.inlinesuppress_na
+
+severity: info
+
+## Example
+
+```
+# nooelint: some.warning
+A = "1"
+```
+
+## Why is this bad?
+
+A warning couldn't be reproduced from the line in question, meaning that there is no warning of the
+specified ID.
+
+## Ways to fix it
+
+remove the ``nooelint`` line
+
+```
+A = "1"
+```

docs/wiki/oelint.file.nospaces.md

@@ -0,0 +1,15 @@
+# oelint.file.nospaces
+
+severity: error
+
+## Example
+
+File ``/some/file/with/a /space/ in /its/path.bb``
+
+## Why is this bad?
+
+Bitbake doesn't support spaces at any place in the absolute file path.
+
+## Ways to fix it
+
+Rename to ``/some/file/with/a_/space/_in_/its/path.bb``

docs/wiki/oelint.file.patchsignedoff.md

@@ -0,0 +1,26 @@
+# oelint.file.inappropriatemsg
+
+severity: info
+
+## Example
+
+With `my.patch`
+
+```
+Signed-off-by: some body <[email protected]>
+```
+
+is missing
+
+## Why is this bad?
+
+Every upstreamable patch should have a ``Signed-off-by`` line.
+See [OpenEmbedded contribution guide](https://www.openembedded.org/index.php?title=Commit_Patch_Message_Guidelines&oldid=10935)
+
+## Ways to fix it
+
+Add to the patch file
+
+```
+Signed-off-by: some body <[email protected]>
+```

docs/wiki/oelint.file.requireinclude.md

@@ -0,0 +1,29 @@
+# oelint.file.requireinclude
+
+severity: warning
+
+## Example
+
+In ``my-recipe_1.0.bb``
+
+```
+include some-include-file.inc
+```
+
+## Why is this bad?
+
+``include`` statement fail silently is the file is not found.
+``require`` will fail if the file hasn't been found.
+
+## Ways to fix it
+
+```
+require some-include-file.inc
+```
+
+or if that is indented behavior
+
+```
+# nooelint: oelint.file.requireinclude
+include some-include-file.inc
+```

docs/wiki/oelint.file.requirenotfound.md

@@ -0,0 +1,35 @@
+# oelint.file.includenotfound
+
+severity: warning
+
+## Example
+
+```
+require this/file/does/not/exist.inc
+```
+
+or
+
+```
+require a/file/from/another/layer.inc
+```
+
+
+## Why is this bad?
+
+If the an include file doesn't reside in the same layer, it creates an external dependency on something
+that is likely beyond the control of the layer.
+It will create breakage if the other layer changes the name and/or the path of the include file.
+
+Or the include simply doesn't exit at all.
+
+## Ways to fix it
+
+Fix the include path or
+
+```
+# noelint: oelint.file.includenotfound
+require a/file/from/another/layer.inc
+```
+
+in case the include file is from another layer.

docs/wiki/oelint.file.underscores.md

@@ -0,0 +1,22 @@
+# oelint.file.underscores
+
+severity: error
+
+## Example
+
+``my_recipe_1.0.bb``
+
+or
+
+``my-recipe.bb``
+
+## Why is this bad?
+
+Bitbake's version detection takes the last chunk after a ``_`` of the filename as the default version.
+If not present ``1.0`` is assumed, so any updates to the recipe might not result in a rebuild of the recipe.
+
+## Ways to fix it
+
+rename to
+
+``my-recipe_1.0.bb``