{"id":46107691,"url":"https://github.com/jatkinson1000/rse-skills-workshop","last_synced_at":"2026-03-01T21:38:00.211Z","repository":{"id":213840326,"uuid":"734814798","full_name":"jatkinson1000/rse-skills-workshop","owner":"jatkinson1000","description":"Teaching materials for improving research software writing abilities.","archived":false,"fork":false,"pushed_at":"2025-11-28T20:35:59.000Z","size":33362,"stargazers_count":12,"open_issues_count":6,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-30T02:29:55.800Z","etag":null,"topics":["python3","rse","software-engineering","teaching-materials"],"latest_commit_sha":null,"homepage":"https://jatkinson1000.github.io/rse-skills-workshop","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jatkinson1000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-22T17:39:48.000Z","updated_at":"2025-11-29T11:16:31.000Z","dependencies_parsed_at":"2023-12-23T16:31:17.561Z","dependency_job_id":"e90f8756-0f0c-49dc-a57c-8825cbacf685","html_url":"https://github.com/jatkinson1000/rse-skills-workshop","commit_stats":null,"previous_names":["jatkinson1000/power-up-python","jatkinson1000/rse-skills-workshop"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jatkinson1000/rse-skills-workshop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jatkinson1000%2Frse-skills-workshop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jatkinson1000%2Frse-skills-workshop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jatkinson1000%2Frse-skills-workshop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jatkinson1000%2Frse-skills-workshop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jatkinson1000","download_url":"https://codeload.github.com/jatkinson1000/rse-skills-workshop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jatkinson1000%2Frse-skills-workshop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29984725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T21:06:37.093Z","status":"ssl_error","status_checked_at":"2026-03-01T21:05:45.052Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python3","rse","software-engineering","teaching-materials"],"created_at":"2026-03-01T21:37:57.280Z","updated_at":"2026-03-01T21:38:00.202Z","avatar_url":"https://github.com/jatkinson1000.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Research Software Engineering Skills Workshop\n\n![GitLab License](https://img.shields.io/gitlab/license/jatkinson1000%2Frse-skills-workshop)\n\nMaterials for a workshop educating academic researchers in research software\nengineering (RSE) principles.\nThe example code used in the exercises is geared towards either climate scientists or\nastrophysicists, but the concepts and material is generally suited for people from\nvarious backgrounds.\n\nThis course is designed to be delivered as a code-along workshop, but you can also follow\nthe slides and work through the exercises in your own time.\n\n\n## Contents\n\n- [Learning Objectives](#learning-objectives)\n- [Materials](#materials)\n- [Prerequisites](#prerequisites)\n- [Setup](#setup)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n- [Contribution Guidelines](#contribution-guidelines)\n\n\n## Learning Objectives\n\nThe key learning objective for the workshop is to _Introduce key tools and concepts of\nresearch software engineering, and how they can be applied in everyday use to write\nhigher-quality code_.\n\nMore specifically we cover:\n\n- Why software engineering principles matter in research\n- (Virtual) environments and dependencies\n- Code standards and best practice (through PEP)\n  - Code formatters and linting/static-analysis tools\n- Documentation\n  - Docstrings\n  - Advice on commenting\n  - The idea of self-documenting code and variable naming\n  - Handling magic numbers in code\n  - READMEs and other useful files in your repository\n  - Software licenses\n- General principles for better code\n  - Removal of hard-coded content to config files\n  - Use of f-strings in Python (optional addition)\n  - Improving readability and reusability through better code structure\n\n\n## Materials\n\n### Slides\n\nThe main slide deck for the workshop can be viewed [here](https://jatkinson1000.github.io/rse-skills-workshop).\nThey are generated from the Quarto materials in the `slides/` directory.\nThey are broken into separate sections covering the different topics in the workshop.\nThe modular structure makes the course adaptable, as sections can be included or excluded from the slide deck.\n\n### Exercises\n\nA series of practical exercises accompany the teaching material in the slides.\nThese are contained in the `exercises/` directory in a series of sub-directories,\neach of which has instructions in a README.\n\nThe code used as the starting point for each exercise is the 'solution' to the\nprevious exercise allowing participants to validate/compare their work.\n\n- 01: Base code to examine.\n- 02: Apply a formatter to standardise code.\n- 03: Linting and static analysis of code.\n- 04: Code structure.\n- 05: Improve code clarity with naming and removing magic numbers.\n- 06: Writing docstrings and best use of comments.\n- 07: General techniques for better code.\n- 00: The end point of the workshop - an improved version of the code in exercise 01.\n\n\n## Prerequisites\n\nIn terms of knowledge this workshop requires:\n\n- Some general programming knowledge\n- Basic familiarity with Python - the course is taught in Python but teaches skills that\n  are transferrable to other languages.\n- The ability to clone this repository and work on it locally.\n\nPython and pip:\n\n- A working installation of Python 3.\n  This should come as standard on linux and can be installed on mac and Windows.\n- A working installation of pip for installing Python packages.\n  Often this will come with Python, but some operating systems/distributions disable it.\n  If `pip` is not available on the command line you can add it to a virtual environment\n  ([see below](#virtual-environment-setup)) using `python -m ensurepip --upgrade`\n\n\u003e [!NOTE]\n\u003e For macOS users: Python 3 can be installed through several popular package managers.\n\u003e Alternatively, if you are unfamiliar with this, refer to\n\u003e [Python's getting-started on mac information](https://docs.python.org/3/using/mac.html)\n\u003e for a complete guide to getting set up.\n\n\u003e [!NOTE]\n\u003e For Windows users: you may wish to refer to\n\u003e [Windows' getting-started with Python information](https://learn.microsoft.com/en-us/windows/python/beginners)\n\u003e for a complete guide to getting set up on a Windows system.\n\nParticipants will also be expected to have:\n\n- A text editor to open and edit code files.\\\n   e.g. vim/[neovim](https://neovim.io/), [gedit](https://gedit.en.softonic.com/), [VS code](https://code.visualstudio.com/), [sublimetext](https://www.sublimetext.com/) etc.\n- A terminal emulator to run the code.\\\n  e.g. [GNOME Terminal](https://help.gnome.org/users/gnome-terminal/stable/), [wezterm](https://wezfurlong.org/wezterm/index.html), [Windows Terminal (windows only)](https://learn.microsoft.com/en-us/windows/terminal/), [iTerm (mac only)](https://iterm2.com/) etc.\n- The two of these may be combined in a single IDE e.g. PyCharm, VS Code, IntelliJ IDEA etc.\n\n\n## Setup\n\n### Cloning the materials\n\nCloning the repository and setting up a virtual environment will be covered in the course,\nbut in preparation you can complete these steps as follows:\n\nNavigate to the location you want to install this repository on your system and clone\nvia https by running:\n```\ngit clone https://github.com/jatkinson1000/rse-skills-workshop.git\n```\nThis will create a directory `rse-skills-workshop/` with the contents of this repository.\n\nPlease note that if you have a GitHub account and want to preserve any work you do\nwe suggest you first [fork the repository](https://github.com/Cambridge-ICCS/rse-skills-workshop/fork) \nand then clone your fork.\nThis will allow you to push your changes and progress from the workshop back up to your\nfork for future reference.\n\nIf you would prefer to do this from GitHub you can use the [GitHub mirror](https://gitlab.com/jatkinson1000/rse-skills-workshop).\n\n### Virtual environment setup\n\nYou can then instantiate a Python virtual environment by running:\n```\npython3 -m venv rse-venv\n```\nThis will create a directory called `rse-venv` containing software for the virtual environment.\nTo activate the environment run:\n```\nsource rse-venv/bin/activate\n```\nYou can now work on Python from within this isolated environment, installing packages\nas you wish without disturbing your base system environment.\n\nWhen you have finished working on this project run:\n```\ndeactivate\n```\nto deactivate the venv and return to the system Python environment.\n\nYou can always boot back into the venv as you left it by running the activate command again.\n\n\n## License\n\nCopyright \u0026copy; Jack Atkinson\n\nUnless otherwise noted the programs and other software provided in this repository are\nmade available under an [OSI](https://opensource.org/)-approved\n[GPL-3.0-only](https://opensource.org/license/gpl-3-0/) license.\n\nUnless otherwise noted the teaching materials provided in this repository are\nmade available under a Creative Commons [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)\nlicense for which the full legal text is [available online](https://creativecommons.org/licenses/by/4.0/legalcode).\n\n\n## Acknowledgments\n\nThe geoscience code used in the exercises is adapted from a script in\\\nIrving, (2019). Python for Atmosphere and Ocean Scientists.\nJournal of Open Source Education, 2(11), 37,\n[doi.org/10.21105/jose.00037](https://doi.org/10.21105/jose.00037)\n\nThe astrophysics code in the exercises is adapted from a notebook kindly provided by\nAnke Ardern-Arentsen ([@ankearentsen](https://github.com/ankearentsen))\nof the Institute of Astronomy at the University of Cambridge.\n\n\n## Contribution Guidelines\n\nContributions and collaborations are welcome from anyone with an\ninterest in RSE education.\n\nIn particular we welcome submission of exercise code for research domains beyond\nthose currently catered for.\n\nFor bugs, feature requests, and clear suggestions for improvement please\n[open an issue](https://gitlab.com/jatkinson1000/rse-skills-workshop/-/issues).\n\nIf you built something upon this that would be useful to others, or can\naddress an [open issue](https://gitlab.com/jatkinson1000/rse-skills-workshop/-/issues),\nplease [fork the repository](https://gitlab.com/jatkinson1000/rse-skills-workshop/-/forks/new)\nand open a merge request.\nIf you wish to contribute a new exercise you think would be useful please follow the\nexisting format in [exercises/](exercises/), and also try and update the slides in\n[slides/](slides/).\n\n\n### A note on mirrors\n\nThis repository exists mainly as a\n[GitLab repository](https://gitlab.com/jatkinson1000/rse-skills-workshop)\nwith a [mirror on GitHub](https://github.com/jatkinson1000/rse-skills-workshop).\\\nPlease try to open issues and contributions on GitLab.\n\n\n### Code of Conduct\n\nEveryone participating in this project, including as a participant at a workshop,\nis expected to treat other people with respect and more generally to follow\nthe guidelines articulated in the\n[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjatkinson1000%2Frse-skills-workshop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjatkinson1000%2Frse-skills-workshop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjatkinson1000%2Frse-skills-workshop/lists"}