docs: Simplify undestanding what's going on #750

MaxymVlasov · 2025-01-09T22:52:05Z

Description of your changes

Add notes for contributors
Describe what different parts of code does, for simplifying future maintenance if it will be needed

MaxymVlasov · 2025-01-09T22:58:23Z

tox.ini

@@ -216,6 +226,7 @@ commands_post =
      ); \
      print("codecov-flags=MyPy", file=gh_output_fd); \
      gh_output_fd.close()'
+  #


@webknjaz could you please specify what's try to achieve command below?

Suggested change

#

# Add all available reports to GHA Job Summary

Is it corresponds?

Suggested change

#

# Publish available MyPy-produced text and JSON reports wrapped as Markdown code blocks, to a GHA job summary

yermulnik · 2025-01-09T23:18:52Z

.github/CONTRIBUTING.md

+    tox -qq
+    ```
+
+    If there are any issues, copy-paste and run the `python3 ...` command to visualize the pytest coverage report.


Suggested change

If there are any issues, copy-paste and run the `python3 ...` command to visualize the pytest coverage report.

If there are any issues, copy-paste and run the failed `python3 ...` command to visualize the pytest coverage report.

Not sure whether "failed" is correct word in this context. Just want to give a reader a hint on what exactly needs to be copied and run. Please correct as applicable.

It always showed, no matter of execution result

Here is example:

➜ tox -qq ==================================== test session starts ==================================== platform linux -- Python 3.10.12, pytest-8.3.4, pluggy-1.5.0 cachedir: .tox/py/.pytest_cache rootdir: /home/vm/code/0-other/open-source/pre-commit-terraform configfile: pytest.ini testpaths: tests/pytest/ plugins: cov-6.0.0, xdist-3.6.1, mock-3.14.0 collected 11 items tests/pytest/_cli_test.py .... [ 36%] tests/pytest/terraform_docs_replace_test.py ....... [100%] ---------- coverage: platform linux, python 3.10.12-final-0 ---------- Coverage HTML written to dir /home/vm/code/0-other/open-source/pre-commit-terraform/.tox/py/tmp/htmlcov/ Required test coverage of 100% reached. Total coverage: 100.00% =================================== slowest 10 durations ==================================== 0.01s setup tests/pytest/_cli_test.py::test_known_interrupts[app-runtime-exc] (9 durations < 0.005s hidden. Use -vv to show these durations.) ==================================== 11 passed in 0.18s ===================================== To open the HTML coverage report, run python3 -Im webbrowser file:///home/vm/code/0-other/open-source/pre-commit-terraform/.tox/py/tmp/htmlcov/index.html To serve the HTML coverage report with a local web server, use python3 -Im http.server --directory cov_html_report_dir 0 ➜

Ah, I see. Then maybe either not "failed" but "questionable" or not "python3 ..." but "python3 -Im ..."? 🤔

Or "copy-paste and run the python3 ... command from tox -qq output" 🤔

The coverage HTML report is always produced by default locally. Unless one overrides the pytest posargs when calling tox. Regardless of whether it's a failure or a success. It's just a convenient one-liner to open a coverage report view in one's browser as opposed to doing this manually.

.github/CONTRIBUTING.md

yermulnik · 2025-01-09T23:21:30Z

.github/workflows/reusable-tox.yml

@@ -308,6 +310,7 @@ jobs:
          && format('-- {0}', inputs.tox-run-posargs)
          || ''
        }}
+    # Generate nice picture of passed/failed tests in GHA Job Summary


Suggested change

# Generate nice picture of passed/failed tests in GHA Job Summary

# Generate visualization of passed/failed tests in GHA Job Summary

It actually creates picture (looks like it is .svg)

"Visualization" is too wide for it, especially as locally and in codecov we can get much more visualization options of errors than just this:

Ah, didn't know it's an image 👍🏻 (the "image" fits better than "picture" though)

It's a widget: https://github.com/test-summary/action?tab=readme-ov-file#test-summary. Being an SVG is more of a low-level implementation detail.

pytest.ini

tox.ini

Co-authored-by: George L. Yermulnik <[email protected]>

webknjaz · 2025-01-10T04:24:42Z

.github/CONTRIBUTING.md

+
+    Make sure that all checks pass.
+
+4. (Optional): If you want to see more details on MyPy checks, you can run:


It doesn't give out more details. The coverage hints are always being printed out.

Suggested change

4. (Optional): If you want to see more details on MyPy checks, you can run:

4. (Optional): If you want to limit the checks to MyPy only, you can run:

webknjaz · 2025-01-10T04:26:11Z

.github/workflows/reusable-tox.yml

@@ -292,6 +292,8 @@ jobs:
        --quiet
        --
        python -Im pre_commit install-hooks
+    # Create GHA Job Summary markdown table of the coverage report
+    # For details: ../../tox.ini '[testenv]' 'commands_post'


This workflow is generic. That's only happening when the env with pytest is being invoked, but not the other envs.

webknjaz · 2025-01-10T04:28:48Z

tox.ini

@@ -23,6 +27,9 @@ commands =
      {tty:--color=yes} \
      {posargs:--cov-report=html:{envtmpdir}{/}htmlcov{/}}
 commands_post =
+  # Create GHA Job Summary markdown table of the coverage report
+  # https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/
+  # '-' ignores non-zero exit code


Suggested change

# '-' ignores non-zero exit code

# a leading '-' suppresses non-zero return codes

webknjaz · 2025-01-10T04:30:20Z

tox.ini

@@ -38,6 +45,7 @@ commands_post =
      cov = coverage.Coverage(); \
      cov.load(); \
      cov.report(file=gh_summary_fd, output_format="markdown")'
+  # Find path of coverage & testrun report for next step


The main effect is not the lookup (the implementation detail) but exposing the step outputs with what's found (the interface that GHA interacts with).

webknjaz · 2025-01-10T04:31:10Z

tox.ini

@@ -183,6 +193,7 @@ commands =
      {posargs:--all-files}

  # Print out the advice on how to install pre-commit from this env into Git:
+  # '-' ignores non-zero exit code


MaxymVlasov requested a review from yermulnik as a code owner January 9, 2025 22:52

MaxymVlasov commented Jan 9, 2025

View reviewed changes

docs: Simplify undestanding what's going on

71886dc

MaxymVlasov force-pushed the chore/imporve_python_tooling_docs branch from 5a84944 to 71886dc Compare January 9, 2025 23:00

yermulnik reviewed Jan 9, 2025

View reviewed changes

MaxymVlasov and others added 2 commits January 10, 2025 01:48

Apply suggestions from code review

862be47

Co-authored-by: George L. Yermulnik <[email protected]>

Apply suggestions from code review

a14a6fb

Co-authored-by: George L. Yermulnik <[email protected]>

webknjaz reviewed Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Simplify undestanding what's going on #750

docs: Simplify undestanding what's going on #750

MaxymVlasov commented Jan 9, 2025

MaxymVlasov Jan 9, 2025 •

edited

Loading

webknjaz Jan 10, 2025

yermulnik Jan 9, 2025

MaxymVlasov Jan 9, 2025 •

edited

Loading

yermulnik Jan 9, 2025 •

edited

Loading

yermulnik Jan 9, 2025

webknjaz Jan 10, 2025

yermulnik Jan 9, 2025

MaxymVlasov Jan 9, 2025

yermulnik Jan 10, 2025

webknjaz Jan 10, 2025

webknjaz Jan 10, 2025

webknjaz Jan 10, 2025

webknjaz Jan 10, 2025

webknjaz Jan 10, 2025

webknjaz Jan 10, 2025

	#
	# Publish available MyPy-produced text and JSON reports wrapped as Markdown code blocks, to a GHA job summary

	If there are any issues, copy-paste and run the `python3 ...` command to visualize the pytest coverage report.
	If there are any issues, copy-paste and run the failed `python3 ...` command to visualize the pytest coverage report.

	# Generate nice picture of passed/failed tests in GHA Job Summary
	# Generate visualization of passed/failed tests in GHA Job Summary


		Make sure that all checks pass.

		4. (Optional): If you want to see more details on MyPy checks, you can run:

	4. (Optional): If you want to see more details on MyPy checks, you can run:
	4. (Optional): If you want to limit the checks to MyPy only, you can run:

	# '-' ignores non-zero exit code
	# a leading '-' suppresses non-zero return codes

docs: Simplify undestanding what's going on #750

Are you sure you want to change the base?

docs: Simplify undestanding what's going on #750

Conversation

MaxymVlasov commented Jan 9, 2025

Description of your changes

MaxymVlasov Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaxymVlasov Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

yermulnik Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaxymVlasov Jan 9, 2025 •

edited

Loading

MaxymVlasov Jan 9, 2025 •

edited

Loading

yermulnik Jan 9, 2025 •

edited

Loading