From 675dab0bed39e9ddd57be6d5a5fb1302a106ea85 Mon Sep 17 00:00:00 2001
From: Fabio Valentini <decathorpe@gmail.com>
Date: Apr 06 2021 21:29:30 +0000
Subject: README: add documentation for limitations and license notice


---

diff --git a/README.md b/README.md
index fabb0a8..87a32c1 100644
--- a/README.md
+++ b/README.md
@@ -39,3 +39,67 @@ locations for an existing configuration file and overrides, in this order, and w
 - `/etc/repochecker/repochecker.{toml,json}`
 - `/usr/share/repochecker/repochecker.{toml,json}`
 
+## limitations
+
+Data served via HTTP endpoints by `repochecker` is provided on a best-effort basis. Limitations of the underlying data
+sources and/or technologies make providing 100% correct data almost impossible.
+
+- architecture-dependent RPM source packages (SRPMs)
+
+While it is forbidden by policy to have a package produce RPM source package **contents** that differ depending on the
+environment (including the architecture that the SRPM is generated on), the RPM **headers** (source package metadata)
+can - and will - be different. For example, BuildRequires that are only present on specific architectures might or
+might not be present in RPM headers, depending on the host system the SRPM is built on.
+
+- architecture-specific source packages discarded by koji
+
+For "normal" builds in the Fedora koji instance, the SRPM for the build is built from dist-git, and then distributed to
+builders of the different architectures. There, they are built in mock, which also produces a rebuilt SRPM file that
+has RPM headers that are specific to that architecture. However, only the initial SRPM file is collected, and those
+built on different builder architectures are discarded. The machine that runs the `buildSRPMfromSCM` task for generating
+the initial SRPM file is selected by the koji scheduler, so its architecture is, essentially, [randomized].
+
+[randomized]: https://pagure.io/koji/issue/2726
+
+- Fedora infrastructure treats SRPM packages as architecture-independent
+
+Since only one SRPM file (which might or might not have architecture-dependent RPM headers) is collected by koji, there
+is also only one `-source` repository produced for all architectures. Querying this repository hence yields unreliable
+results - in particular, `BuildRequires` might be present on architectures even if they should explicitly not be present
+for that architecture according to the `.spec` file contained in the SRPM file.
+
+It is possible to add overrides for "false positives" that are caused by these architectural limitations, as described
+above.
+
+- compose process has issues with architecture-specific `noarch` packages
+
+Packages that are contain no architecture-specific files (`noarch`) but have dependencies that are not available on all
+architectures get [erroneously] included in repositories that are explicitly excluded by the package's `.spec` file.
+
+These are not really "false positives" in the same sense, because the packages really do have broken dependencies on
+some architectures, but since this is due to infrastructure bugs, they can be added to the overrides as well. 
+
+[erroneously]: https://pagure.io/koji/issue/1843
+
+- incomplete package maintainer information from pagure
+
+Pagure provides a "special" API endpoint for getting all packages and their maintainers in one request, but this only
+includes the package's main admin ("owner") and any BugZilla assignee overrides that might be present for each
+package. However, co-maintainers are not returned by this endpoint at all. Querying the pagure API for almost 30000
+individual packages just to get information for all co-maintainers seems unreasonable, so `repochecker` can only
+associate packages with their "main admin".
+
+## license
+
+This project is licensed under either of
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>) or
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>),
+
+at your option.
+
+### contributions
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as
+defined in the Apache-2.0 license, shall be dual licensed as stated above, without any additional terms or conditions.
+