Manual.md: No mention of replaces

[toluschr]

Expected behavior

A brief explanation of what replaces does, how and when it should be used (>=, <, etc.).

Actual behavior

Grepping for replaces yields results in a lot of packages. However, when reading the manual, the keyword is not mentioned.

Steps to reproduce the behavior

Read the manual

[sgn]

replaces doesn't work the way people usually expected.
Until someone go to xbps fix it, I think it's unlikely replaces will mention it.

[ashpool37]

Sorry, I'm not sure if I understand it correctly. replaces works in a counter-intuitive way, so shouldn't that be the reason to document it better? I also found it used in other packages, and applied it to one of my packages relying heavily on intuition. The lack of documentation leaves me worried if I did something wrong.

[ericonr]

Now that this mechanism is being used in removed-packages, it should definitely be documented.

@Chocimier ?

[Chocimier]

Will documenting as "counter-intuitive and subject to change behaviour, use transitional packages instead" be fine for you?

[ericonr]

Given b7ce94c, shouldn't it be documented to be used together with transitional packages? And I think it'd be best to have the documentation actually list why it's counter intuitive and what's still undefined / can change, even if it isn't an ideal situation.

[ericonr]

Otherwise people have to guess and depend on unspoken knowledge...

[ashpool37]

In addition to any warnings as to the keyword being deprecated, palliative and temporary, it would be really helpful to have a description of how it actually works as is. I understand that this might feel like a step towards "legitimizing" it and leaving it be for a long time, but it's been there for a long time already, used in many packages, and therefore I think it's better to have it properly documented.

To motivate more people to consider using transitional packages and other alternatives to this keyword, I suggest introducing some highly visible warnings to the packaging tools like xlint or xbps-src shown upon encountering replaces= in a template.

[github-actions]

Issues become stale 90 days after last activity and are closed 14 days after that. If this issue is still relevant bump it or assign it.