Review of episodes 3 - 4: Version Control and Code Readability

[kkh451]

03-version-control:

• Minor edits after proof-read
• Link out to resources on creating diffs

The following unresolved issues are noted:

• Images in the "Understanding commit contents" exercise (03-version-control) are hard to read #83
• Dark-mode screenshots are hard to read #84
• The version control episode does not cover how to generate a diff #85

04-code-readability

• Minor edits after proof-read
• Swap reference to Sphinx for MkDocs (used in docs episode)
• Change thing1 and 1thing to read_speed1 and read_speed1

The following unresolved issues are noted:

• The "Add some comments to a code block" in 04-code-readability exercise refers to "old" bad code file bad-code.py #86
• The "Create a function" exercise in 04-code-readability uses an old version of read_json_to_dataframe #87
• The solution to "Writing Docstrings" in code readability does not use a google style docstring (needed in testing episode) #88
• The "bad" code is not refactored in the version control or the code readability episode #89

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/carpentries-incubator/fair-research-software/compare/md-outputs..md-outputs-PR-91

The following changes were observed in the rendered markdown documents:

 03-version-control.md  |  31 ++++----
 04-code-readability.md | 204 ++++++++++++++++++++-----------------------------
 links.md               |   4 +-
 md5sum.txt             |   6 +-
 4 files changed, 106 insertions(+), 139 deletions(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2024-06-29 16:08:39 +0000

[anenadic]

Thank you @kkh451