PR#450: Add Messaging documentation - greenwave

greenwave

#450 Add Messaging documentation

Merged 4 years ago by lholecek. Opened 4 years ago by lholecek.

lholecek/greenwave messaging-docs into master

Lukas Holecek • 4 years ago

1beb84c

docs/index.rst

file modified

		`@@ -18,6 +18,7 @@`
		`policies`
		`package-specific-policies`
		`api`
		`+ messaging`
		`dev-guide`
		`release-notes`

docs/messaging.rst

file added

+97

		`@@ -0,0 +1,97 @@`
		`+ =========`
		`+ Messaging`
		`+ =========`
		`+`
		`+ Greenwave publishes a decision change message whenever a decision (a response`
		`+ of the API call) would change for a policy predefined in the Greenwave`
		`+ configuration, i.e. when there is a new test result in ResultsDB or a new`
		`+ waiver in WaiverDB related to a predefined policy, and the new result/waiver`
		`+ changes the previous decision. The new result/waiver and related policy must`
		`+ have the subject type, product version, and test case name match.`
		`+`
		`+ The message topic is "greenwave.decision.update".`
		`+`
		`+ The message body contains the list of applicable policies, the new and previous`
		`+ decision.`
		`+`
		+ The previous decision is automatically retrieved using the ``when`` flag in the
		`+ API request. Its value is immediately before the submit time of the new`
		`+ result/waiver.`
		`+`
		`+ The decision change message is not published if the new and previous decisions`
		`+ have the same satisfied and unsatisfied requirements.`
		`+`
		`+ Below is an example decision change message body published after receiving a`
		`+ new test result message from ResultsDB.`
		`+`
		`+ .. code-block:: json`
		`+`
		`+ {`
		`+ "subject_type": "redhat-module",`
		`+ "subject_identifier": "nodejs-12-8010020190612143724.cdc1202b",`
		`+`
		`+ "product_version": "rhel-8",`
		`+`
		`+ "decision_context": "osci_compose_gate_modules",`
		`+`
		`+ "applicable_policies": ["osci_compose_modules"],`
		`+ "policies_satisfied": false,`
		`+ "summary": "1 of 2 required test results missing",`
		`+ "satisfied_requirements": [{`
		`+ "result_id": 7483048,`
		`+ "testcase": "osci.redhat-module.installability.functional",`
		`+ "type": "test-result-passed"`
		`+ }],`
		`+ "unsatisfied_requirements": [{`
		`+ "item": {`
		`+ "item": "nodejs-12-8010020190612143724.cdc1202b",`
		`+ "type": "redhat-module"`
		`+ },`
		`+ "scenario": null,`
		`+ "subject_identifier": "nodejs-12-8010020190612143724.cdc1202b",`
		`+ "subject_type": "redhat-module",`
		`+ "testcase": "baseos-ci.redhat-module.tier1.functional",`
		`+ "type": "test-result-missing"`
		`+ }],`
		`+`
		`+ "previous": {`
		`+ "applicable_policies": ["osci_compose_modules"],`
		`+ "policies_satisfied": false,`
		`+ "summary": "1 of 2 required tests failed",`
		`+ "satisfied_requirements": [{`
		`+ "result_id": 7483048,`
		`+ "testcase": "osci.redhat-module.installability.functional",`
		`+ "type": "test-result-passed"`
		`+ }],`
		`+ "unsatisfied_requirements": [{`
		`+ "item": {`
		`+ "item": "nodejs-12-8010020190612143724.cdc1202b",`
		`+ "type": "redhat-module"`
		`+ },`
		`+ "result_id": 7486745,`
		`+ "scenario": null,`
		`+ "testcase": "baseos-ci.redhat-module.tier1.functional",`
		`+ "type": "test-result-failed"`
		`+ }]`
		`+ }`
		`+ }`
		`+`
		`+ Product Version for Test Results`
		`+ ================================`
		`+`
		`+ Test results in ResultsDB do not contain a product version, but the value is`
		`+ needed to find applicable policies.`
		`+`
		`+ Greenwave tries to guess the product version from the subject identifier or get`
		`+ the value from Koji.`
		`+`
		`+ Sometimes, the product version cannot be guessed, e.g. for container image`
		`+ builds or subject types other than "koji_build", "brew-build", "compose" or`
		`+ "redhat-module".`
		`+`
		`+ If the product version cannot be guessed, policies with any product version are`
		`+ considered (subject type and test case name is still used for further`
		`+ matching).`
		`+`
		`+ Some policies may use custom unique value for product version when test`
		`+ subjects are not related to any real world product.`

lholecek commented 4 years ago

Signed-off-by: Lukas Holecek hluk@email.cz

lholecek commented 4 years ago

@lucarval, @gnaponie Anything else we discussed that should be in the documentation?

mprahl commented on line 6 of docs/messaging.rst 4 years ago

message => messages

mprahl commented on line 7 of docs/messaging.rst 4 years ago

in Greenwave => in the Greenwave

mprahl commented on line 10 of docs/messaging.rst 4 years ago

have matching subject type, product version and test case name. => have the subject type, product version, and test case name match.

mprahl commented on line 14 of docs/messaging.rst 4 years ago

contains list => contains the list
and new => and the new

mprahl commented on line 17 of docs/messaging.rst 4 years ago

Previous => The previous

mprahl commented on line 21 of docs/messaging.rst 4 years ago

have same => have the same

mprahl commented on line 23 of docs/messaging.rst 4 years ago

receiving new => receiving a new

mprahl commented on line 81 of docs/messaging.rst 4 years ago

product version but => a product version, but

mprahl commented on line 84 of docs/messaging.rst 4 years ago

from subject => from the subject

mprahl commented on line 87 of docs/messaging.rst 4 years ago

product version => the product version

lholecek commented on line 6 of docs/messaging.rst 4 years ago

message => messages

It publishes single message for a decision change. Maybe a decision change message? (I'm bad with articles.)

rebased onto 89b20914d97ea9a1d33061c4d8090d8216e9bffa

4 years ago

mprahl commented 4 years ago

message => messages

It publishes single message for a decision change. Maybe a decision change message? (I'm bad with articles.)

That sounds good to me.

rebased onto e4f382ea0593a2e83f98ae1dd0f581cc514d6015

4 years ago

lholecek commented 4 years ago

Updated.

gnaponie commented on line 9 of docs/messaging.rst 4 years ago

That changes the previous decision. Or no message is sent.
I would emphasize this concept and put an example.

gnaponie commented on line 9 of docs/messaging.rst 4 years ago

I would also explicitly say that if there's no change, the message doesn't get published, because, as it is clear from the topic, it is about a "decision update".
I know it's a lot of repetition of the same concept, but many people didn't get this in the past and they were confused about why Greenwave doesn't just publishes a message every time a new result or waiver comes in.

gnaponie commented on line 15 of docs/messaging.rst 4 years ago

Can we remove the 2 "and"s? Just "the list of applicable policies, the new and previous decision."

gnaponie commented on line 18 of docs/messaging.rst 4 years ago

isn't it "when - a millisecond" or something like that?

gnaponie commented on line 18 of docs/messaging.rst 4 years ago

But actually... is it really important for the user to know this information?

gnaponie commented on line 93 of docs/messaging.rst 4 years ago

Yeah. I would add that people are free to configure "custom" product version because maybe it doesn't apply to their use case. But this means that "If the product version cannot be guessed, policies with any product version are considered...)

lholecek commented on line 9 of docs/messaging.rst 4 years ago

That changes the previous decision. Or no message is sent.
I would emphasize this concept and put an example.

@gnaponie No idea what you mean here.

lholecek commented on line 18 of docs/messaging.rst 4 years ago

isn't it "when - a millisecond" or something like that?
But actually... is it really important for the user to know this information?

I think this could be useful for some trouble shooting. But mentioning the removed millisecond is maybe too much ... not sure.

lholecek commented on line 9 of docs/messaging.rst 4 years ago

I would also explicitly say that if there's no change, the message doesn't get published

This is mentioned below:

The decision change message is not published if the new and previous decisions have the same satisfied and unsatisfied requirements.

rebased onto 62936e1ddc293aa5b1313c8a5be0e371cc3ae177

4 years ago

lholecek commented on line 93 of docs/messaging.rst 4 years ago

I've added:

Some policies may use custom unique value for product version when test subjects are not related to any real world product.

lholecek commented on line 15 of docs/messaging.rst 4 years ago

Can we remove the 2 "and"s?

Done.

gnaponie commented 4 years ago

@gnaponie No idea what you mean here.

Yeah sorry, I guess I said it in an unclear way.
I mean that I would say something like (but maybe better rephrased):
"when there is a new test result in ResultsDB or a new waiver in WaiverDB related to a predefined policy, and the new result or waiver changes the previous decision. Or no message is sent."

Because from how you wrote this sentence I would understand that a message get published every time there's a new result/waiver, no matter if the decision changed.

gnaponie commented 4 years ago

I think this could be useful for some trouble shooting. But mentioning the removed millisecond is maybe too much ... not sure.

Nevermind. I guess the sentence is fine.

gnaponie commented on line 19 of docs/messaging.rst 4 years ago

Optional: But can't we just say here... "Its value is immediately before the submit time of the new result/waiver" or something?

lholecek commented 4 years ago

I mean that I would say something like (but maybe better rephrased):
"when there is a new test result in ResultsDB or a new waiver in WaiverDB related to a predefined policy, and the new result or waiver changes the previous decision. Or no message is sent."

OK, changed.

rebased onto 9d354f357889364602e33ae5f5a12386a2546035

4 years ago

lholecek commented on line 19 of docs/messaging.rst 4 years ago