Create the Logging and Output guidelines

[psss]

Add a new section defining the individual output types and individual verbosity levels. Describes the target state to which we want to get.

Fix #4814.

Pull Request Checklist

• write the documentation
• include a release note

[gemini-code-assist]

Code Review

This pull request adds a new 'Logging and Output' section to the contribution documentation (docs/contribute.rst) to clarify the distinction between logging (stderr) and output (stdout), and to define verbosity and debug levels. Feedback recommends formatting the logging method names as inline literals for consistent rendering, and adding a note to clarify that using the level parameter with info() is a planned target state, as the current implementation requires using verbose() instead.

[LecrisUT]

The separation between these 2 is still vague in the wording. I don't feel like I can answer yet when a potentially loggable output should be:

• info0
• info1
• moved to debug
• not logged at all

Let me give a concrete snippet

tmt/tmt/steps/prepare/artifact/providers/repository.py

Lines 82 to 83 in bae12b9

	self.logger.info(f"Reading repository file from local path: {parsed_path}")
	self.logger.debug(f"Absolute path of the repository file: '{parsed_path.resolve()}'")

[psss]

The two levels are actually described using the current tmt run behavior. Overal summaries versus listing individual tests. If you have more tangible examples at hand, please suggest them.

[LecrisUT]

If you have more tangible examples at hand, please suggest them.

What is wrong with the example snippet given above?

[psss]

I mean, example of how to better write the summary, for those two levels.

[LecrisUT]

Well, first is the question of what to do in that example case. Because I do not know how it should be handled and as such I don't know what info0 and info1 should have

[tcornell-bus]

After reading the level summaries...

 self.logger.info(f"Reading repository file from local path: {parsed_path}")

seems like this one should be log level 1

 self.logger.debug(f"Absolute path of the repository file: '{parsed_path.resolve()}'") 

This one should be debug level 2

If those choices seem wrong, then maybe the summary for those two levels could be changed 😆

[LecrisUT]

Suggested change

	method. Output represents the actual data result of a command —
	a list of names, exported metadata, or formatted details meant
	method. Output represents the actual data result of a command, such as
	a list of names, exported metadata, or formatted details meant

[LecrisUT]

Suggested change

	execution. It is the primary form of communication for commands
	that do not produce structured data, such as:
	* ``tmt run``
	* ``tmt try``
	* ``tmt lint``
	* ``tmt clean``
	execution. This is the main mode of communication you should use throughout the code.

Main thing here is to:

• mention that this is the main thing to focus on
• the developer should not have to figure out how one part of the code is used in either tmt run or tmt ls

[LecrisUT]

Well, first is the question of what to do in that example case. Because I do not know how it should be handled and as such I don't know what info0 and info1 should have

[LecrisUT]

Would leave out the enumeration of topics. It's a recipe for divergence. Instead we can add docstrings to log.Topic if needed.

[tcornell-bus]

If these are moved to log.Topic as docstrings, having a link to the docstrings here would be very helpful