Skip to content

[gh-pages] Document pnc-specific dependency ranking/filtering system. #973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: gh-pages
Choose a base branch
from
Open

[gh-pages] Document pnc-specific dependency ranking/filtering system. #973

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b91b13
Document pnc-specific dependency ranking/filtering system.
michalovjan Apr 27, 2023
bd593d0
add an example for allow/deny lists
michalovjan Apr 27, 2023
5f98a0f
Specify difference between global and scoped properties.
michalovjan May 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions guide/dep-manip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,68 @@ For example:

-DrestHeaders=log-user-id:102,log-request-context:061294ff-088,log-process-context:,log-expires:,log-tmp:

##### REST PNC-Specific properties

<table bgcolor="#ffff00">
<tr>
<td>
<b>NOTE</b> : Available from version 4.16
</td>
</tr>
</table>

As of new versions of DA (version TBD), it makes available 3 additional ways how you can influence returned results. By
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Before this is merged this will need to be updated)

default DA returns highest version with the highest version suffix. With `-DrestDependencyRanks`,
`-DrestDependencyAllowList`, `-DrestDependencyDenyList` you can alter this behaviour if you want to highlight some PNC
specific properties of the dependencies.

The general framework about how to express these PNC-Specific qualities is done through so called Qualifiers. Examples
of such Qualifiers are `PRODUCT`(PNC Product), `VERSION` (PNC Product Version), `MILESTONE` (PNC Product Milestone) or
`QUALITY` (PNC Artifact Quality) and more... These Qualifier have their respective values like `PRODUCT:RHSSO`,
`VERSION:RHSSO 7.2`, `MILESTONE:RHSSO 7.2.3.CR2`. If an PNC-made Artifact was built by Build which was a part of RHSSO
Product. A Qualifier `PRODUCT:RHSSO` would match that artifact or dependency in PME's context.

With `restDependencyRanks` you can express a preference which artifacts you prefer more than others. It consists of
separate ranks where each rank is delimited by `;` (can be modified by `-DrestDependencyRankDelimiter=','`). Simple
example of ranking could be`-DrestDependencyRanks="PRODUCT:RHSSO"`. What would happen is, that DA will look at all
versions of a dependency and sort them by the Product and version suffix at the same time.
With some example versions and `-DrestDependencyRanks="PRODUCT:RHSSO"` best version would be picked like this.
(highlighted version is picked for that dependency)

| Version | Product | Quality | SORTED -->><br/><<--PRE-SORT | Version | Product | Quality |
|---------------|---------|----------|------------------------------|-------------------|-----------|--------------|
| release-00006 | EAP | | | **release-00005** | **RHSSO** | **RELEASED** |
| release-00002 | | | | release-00004 | RHSSO | |
| release-00003 | EAP | RELEASED | | release-00006 | EAP | |
| release-00005 | RHSSO | RELEASED | | release-00002 | | |
| release-00001 | | | | release-00003 | EAP | RELEASED |
| release-00004 | RHSSO | | | release-00001 | | |

Order of ranks matter, with higher rank comes higher priority. Additionally, ranks 'cooperate' with each other. Versions
with multiple ranks that match will be prioritized.

For example `-DrestDependencyRanks="PRODUCT:EAP;QUALITY:RELEASED"` would result in this order.

| Version | Product | Quality | SORTED -->><br/><<--PRE-SORT | Version | Product | Quality |
|---------------|---------|----------|------------------------------|-------------------|---------|--------------|
| release-00006 | EAP | | | **release-00003** | **EAP** | **RELEASED** |
| release-00002 | | | | release-00006 | EAP | |
| release-00003 | EAP | RELEASED | | release-00005 | RHSSO | RELEASED |
| release-00005 | RHSSO | RELEASED | | release-00004 | RHSSO | |
| release-00001 | | | | release-00002 | | |
| release-00004 | RHSSO | | | release-00001 | | |


`restDependencyAllowList` and `restDependencyDenyList` are fairly straightforward. They are comma-seperated list of
Qualifiers that will, in case of allowList, be **exclusively** allowed or in case of denyList, **not allowed at all**.

Furthermore, you can change the scope of affected dependencies for specific groupIDs or groupID:artifactIDs. For example
`-DrestDependencyRanks.org.slf4j='PRODUCT:EAP'` would apply only to artifacts with `org.slf4j` groupID. This is the case
also for `-DrestDependencyAllowList.org.slf4j:slf4j-api` and `-DrestDependencyAllowList.org.slf4j:slf4j-api`.

Full list of available Qualifiers and much more in-depth guide how ranking system works is available in other document
(TBD).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Before this is merged this will need to be updated)


### Direct/Transitive Dependencies

<table bgcolor="#ffff00">
Expand Down