Update Documentation on creating patches, and patch.json formats

[nephros]

1. Documentation on how to create a new patch is sparse and could be improved. [1], [3] Especially the correlations of packaging patch.json and using a Web Catalog upload:
   • patch.json ins only required for RPMs (or more generally patches not distributed via Web Catalog)
   • patch.json should use the newer format (but old is supported)
   • Web catalog creates a patch.json from the info entered in the web interface and packages it automatically

The information is there but is not immediately obvious.

2. patch.json contents are not documented at all (AFAIK)

3. Some of the documentation points to [2] as an example for a patch. While this still works as an example, it uses the legacy patch.json format, which has much fewer information bits than the newer one.

References: [1] Web catalog "Documentation (kinda)" page: https://coderus.openrepos.net/pm2/usage/ [2] Example project pointed to by README currently: https://github.com/CODeRUS/sailfishos-disable-glass-avatar [3] Project README - for developers: https://github.com/sailfishos-patches/patchmanager/blob/master/README.md#for-developers [4] probably various guides floating around at the usual places (TJC, TMO, etc.)

[Olf0]

Side note 1

There is also [5] https://openrepos.net/content/coderus/patchmanager-30 But that does not seem to add anything significant over [1].

Side note 2

Well, point 2 is documented in [3]:

{
    "name": "My super patch",
    "description": "Some description.",
    "category": "other",
    "infos": {
        "maintainer": "Foo Bar"
    }
}

Main message

I think the primary task is to consolidate [1] and [3] into [3] (mind that I inserted a pointer to a subsection) and adapt to proper language for specifications (following RFC2119 closely, but not necessarily its spelling in all capital letters): No "shall", no "can". Only "must", "should" and "may", plus their negations. But also try to avoid these negations ("must not", "should not" and "may not"), because they tend to be a source of misunderstandings (because e.g., while "must" = "have to", but "do not have to" = "may not" ≠ "must not"!) .

Reasons: [3] already is the richest source of information and it is the easiest to discuss and work on, because it is hosted at Github. Furthermore, writing and formatting in Markdown is expressive and comes with a lot of benefits, e.g. automatic generation of IDs (jump marks) for every section header etc.

[Olf0]

https://github.com/sailfishos-patches/patchmanager/pull/73#discussion_r722775922 provides a good example and reason for making [3] the principal documentation and the only place where it is maintained.