[conan centre] conandata.yml extended format for patches

[SSE4]

the current format is:

  1.75.0:
    - patch_file: "patches/boost_build_qcc_fix_debug_build_parameter_since_1_74.patch"
      base_path: "source_subfolder"
    - patch_file: "patches/python_base_prefix_since_1_74.patch"
      base_path: "source_subfolder"

we want more fields according to the discussion at https://github.com/conan-io/conan-center-index/pull/3951

the proposal format would be:

  1.75.0:
    - patch_file: "patches/boost_build_qcc_fix_debug_build_parameter_since_1_74.patch"
      base_path: "source_subfolder"
      patch_type: <the type of the patch>
      patch_description: <short description on what does patch do, why does it do that and how exactly>
      patch_source: <the original location patch was taken from>

there are several new (mandatory) fields: patch_type, patch_description and patch_source. let's discuss them in details:

1. patch_type

there are several patch types we want to allow in conan centre right away.

1.1. official

patch_type: official indicates the patch is distributed with source code itself. usually, this happens if release managers failed to include a critical fix to the release, but it's too much burden to make new release just because of that one fix. example: https://www.boost.org/users/history/version_1_72_0.html (notice the coroutine patch)

in that case, the description could be copied from the release page, and the release page would be the patch source itself

1.2. vulnerability

patch_type: vulnerability indicated the patch addresses the security issue. the patch description should include the index of CVE or CWE the patch addresses. usually, upstream does new releases for vulnerabilities itself, but some projects are abandoned or inactive.

1.3. backport

patch_type: backport indicates the patch backports existing bug fix from the newer release or master branch (or equivalent, such as main/develop/trunk/etc). the patch address may be a pull request, or bug issue tracker entry.

backports are accepted only for bugs, but not for feature requests. usually, the following kind of problems are good candidates to backports:

• program doesn't start at all
• crash, such as segmentation fault or access violation
• hang up or deadlock
• memory leak or resource leak in general
• garbage output
• abnormal termination without a crash (e.g. just exit 1 at very beginning)
• data corruption
• use of outdated or deprecated API or library

1.4. portability

patch_type: portability indicates the patch improves the portability of the library, e.g. adding supports of new architectures (ARM, Sparc, etc.), operation systems (FreeBSD, Android, etc.), compilers (Intel, MinGW, etc.), and other types of configurations which are not originally supported by the project.

in such cases, the patch could be adopted from another package repository (e.g. MSYS packages, Debian packages, Homebrew, FreeBSD ports, etc.).

patches of this kind are preferred to be submitted upstream (in contrast to patch_type: conan), but it's not always possible.

1.5. conan

patch_type: conan indicates the patch that is conan-specific, patches of such kind are not welcomed upstream, because they provide zero value outside of conan. examples of such a patches may include modifications of build system files to allow dependencies provided by conan instead of dependencies provided by projects themselves (e.g. as submodule or just 3rd-party sub-directory) or by the system package manager (rpm/deb).

2. patch_source

patch_source is an URL from where patch was taken from, https is preferred, but other URLs (e.g. git/svn/hg) are also accepted if there is no alternative. what could be a patch source?

• link to the public commit in project hosting like GitHub/GitLab/BitBucket/Savanha/SourceForge/etc
• link to the Pull Request or equivalent (e.g. gerrit review)
• link to the bug tracker (such as JIRA, BugZilla, etc.)
• link to the mail list discussion
• link to the patch itself in another repository (e.g. MSYS, Debian, etc.)

for the patch_type: portability there might be no patch source matching the definition above. although we encourage contributors to submit all such portability fixes upstream, it's not always possible (e.g. for projects no longer maintained), in such case link to the conan issue is valid patch source.

for the patch_type: conan, it doesn't make sense to submit patch upstream, so there will be no patch source.

3. patch_description

patch_description is an arbitrary text describing the following aspects of the patch:

• what does patch do (example - add missing unistd.h header)
• why is it necessary (example port to Android)
• how exactly does patch (example - update configure.ac) therefore, the full description may look like: port to android: update configure.ac adding missing unistd.h header

[Croydon]

This sounds really good 👍

[jgsogo]

@SSE4 do you think you can write black on white the proposal and add a PR to this branch here: https://github.com/jgsogo/conan-center-index/tree/policy/patching-update Let's see if we can finish that piece of documentation

Thanks!

[SSE4]

@SSE4 do you think you can write black on white the proposal and add a PR to this branch here: https://github.com/jgsogo/conan-center-index/tree/policy/patching-update Let's see if we can finish that piece of documentation

Thanks!

I am not sure I understand. I think if we're okay with conandata.yml format, the next step would be to write a hook and get it merged. then, your PR may just reference conandata.yml format.

[jgsogo]

Yes, but we need to document that format, something easier to understand than the hook itself. IMO, the docs about the patches and conandata.yml format can be in the same PR (patches will reference the format).

[SSE4]

@jgsogo check https://github.com/jgsogo/conan-center-index/pull/5