Skip to content
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

[gh-pages] Document new pnc-specific user properties #435

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

[gh-pages] Document new pnc-specific user properties #435

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
61 changes: 61 additions & 0 deletions guide/dep-manip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,67 @@ For example:

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

##### REST PNC-Specific properties

As of new versions of DA (version TBD), it makes available 3 additional ways how you can influence returned results. By
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
(non-configurable) list of Qualifiers that will, in case of allowList, be **exclusively** allowed or in case of
denyList, **not allowed at all**.

An example:

-DrestDependencyAllowList="PRODUCT:EAP, PRODUCT:RHSSO"

-DrestDependencyDenyList="QUALITY:BLACKLISTED"

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).

### Disabling Dependency Manipulation

If the parameter `-DdependencySource=NONE` is set then this will disable communication with the REST source which effectively disables manipulation. Note that the version will still be changed - although, if there is no preexisting `manipulation.json` it will always get a `-00001` suffix.
Expand Down