Extend the compatibility-with-leapp-repository.html

[fernflower]

Include real life scenario how to cross-reference leapp/leapp-repository
dependencies in spec files from a leapp dev POV.

[github-actions]

Thank you for contributing to the Leapp project!

Please note that every PR needs to comply with the Leapp Guidelines and must pass all tests in order to be mergable.
If you want to request a review or rebuild a package in copr, you can use following commands as a comment:

• review please to notify leapp developers of review request
• /packit copr-build to submit a public copr build using packit

To launch regression testing public members of oamg organization can leave the following comment:

• /rerun to schedule basic regression tests using this pr build and leapp-repository*master* as artifacts
• /rerun 42 to schedule basic regression tests using this pr build and leapp-repository*PR42* as artifacts
• /rerun-all to schedule all tests (including sst) using this pr build and leapp-repository*master* as artifacts
• /rerun-all 42 to schedule all tests (including sst) using this pr build and leapp-repository*PR42* as artifacts

Please open ticket in case you experience technical problem with the CI. (RH internal only)

Note: In case there are problems with tests not being triggered automatically on new PR/commit or pending for a long time, please consider rerunning the CI by commenting leapp-ci build (might require several comments). If the problem persists, contact leapp-infra.

[centos-ci]

Can one of the admins verify this patch?

[pirat89]

what about something like:

Suggested change

	# Leapp developer's point of view
	# An example story from leapp developer's POV

My point is to explain we provide an example / story to people in this section that covers the stuff above.

[pirat89]

Let's rather make it general. It does not matter whether someone is working on a functionality that needs to be addressed in both projects in the same time or whether we speak just about generic case: I want to provide new feature in leapp; I want to start to use a feature in official leapp repositories.

Suggested change

	Some big and cool feature requests expect changes to land in both leapp and leapp-repository projects simultaneously.
	To instruct how to pick up the proper version, you need to make changes to the spec files that reside in the
	`packaging` directory of both projects.
	For example, let's say that [packaging/leapp.spec](../../packaging/leapp.spec#L16) has `framework_version 42.42` and
	the cool change you are working on is breaking previous functionality.
	* In a leapp PR you would need to bump the version in the spec file to `framework_version 43.0`.
	* In a leapp-repository PR you would then need to address the expected version by adjusting the Requires directive,
	like `Requires: leapp-framework >= 43.0, leapp-framework < 44`
	I want to address new feature / functionality in leapp. Let's say that looking into [packaging/leapp.spec](../../packaging/leapp.spec#L16) `framework_version` is set to `2.2` (the macro is used to set the value for the provided `leapp-framework` capability). Based on my change I need to bump the value to:
	* `2.3` - if my change is providing new funcionality that is compatible with previous version, so it's not breaking anything
	* `3.0` - if my change is not compatible with the original functionality, so e.g. a library function is removed, etc. whatever change that affect the current existing leapp repositories.
	Now let's say the other case: I want to start to use the new leapp functionality in a leapp repository (in the leapp-repository git repo). In such a case, in the commit I start to use the new functionality (newer leapp), I check the [packaging/leapp-repository.spec](https://github.com/oamg/leapp-repository/blob/a2ae28455d4d28be62749e141a66beb35e686764/packaging/leapp-repository.spec#L99) spec file to see what `leapp-framework` is required. Let's say you see now line like this:
	`
	Requires: leapp-framework >= 2.2, leapp-framework < 3
	`
	There are possible two cases:
	* If the functionality you require is provided by `leapp-framework` older than `2.2` you do not need to do anything as the required functionality is already provided in the required version of the framework (ignoring the possibility you would like to use a removed functionality provided e.g. in framework `1.1`, the lowering of the required version of the framework is just not possible in our projects).
	* If the functionality you require is provided by `leapp-framework` newer/higher than `2.2` (e.g. `2.4`, or `3.0`) than update the requirement so you are sure that minimal version will be the one you require, and the highest possible version will be lower than next the next major one (where the functionality could be missing or changed). So let's say in case you need functionality in `3.5`, you are sure that you will not install framework `4.x` or newer. So for this example set:
	`
	Requires: leapp-framework >= 3.5, leapp-framework < 4
	`

@fernflower: i cannot use triple backticks in the suggestion :/, so replace simple backticks when speking about "lines" by triple backticks instead.

[fernflower]

TBH I'd like to keep it simple and goal oriented - we already have a generic description above that doesn't really help to find an immediate answer to "How do I specify the cross-dependent versions asap" :(

I would like to keep this paragraph only for cases when leapp developer actually needs to become aware of the need to bump framework version.

[fernflower]

@MichalHe @Rezney @vinzenz what do you think?

[pirat89]

@fernflower let's put it somewhere so we discuss it the next week, to have it resolved. it's not cabal topic, but possibly we could use that mtg when nobody is answering. wdyt?

or we could sync first to discover whether we find a better solution alone :)