# Hands-on Exercise 1 — Generate, Assess and Improve CodeMeta Metadata **Duration:** 40 minutes ## Goal In this exercise, you will use GitHub Actions to generate a `codemeta.json` file with **SOMEF**, assess the FAIRness of the research software with **RSFC**, detect research software metadata pitfalls with **RSMetadataCheck**, and improve the repository by addressing some of the identified issues. The exercise follows an iterative workflow: ```text Select repository ↓ Generate codemeta.json with SOMEF ↓ Review and improve metadata ↓ Run FAIR assessment with RSFC ↓ Fix one failed FAIR test ↓ Detect metadata pitfalls with RSMetadataCheck ↓ Fix one pitfall ``` ## Before you start You will need: - a GitHub account, - a software repository that you can modify, - permission to enable and run GitHub Actions in that repository. You may use your own repository, or your fork of **this repository**, which pairs a plain GitHub Pages site with a real QGIS project ([`qgis/`](../qgis/)) as the worked example for this exercise. A reference `codemeta.json` for this repository is provided at the repo root — use it to compare against what SOMEF generates for your own fork. > **Note** > > GitHub Action workflow files must be stored in the `.github/workflows/` directory of the repository. --- ## Step 1 — Select a repository Choose the repository you want to use during the exercise. Before making any changes, spend a couple of minutes inspecting the information already available in the repository. Look for metadata such as: - software name, - description, - authors or contributors, - licence, - version, - programming language, - keywords or topics, - documentation, - repository URL, - related publications. ### Checkpoint Ask yourself: - Is the repository clearly described? - Is the licence explicit? - Are authors or contributors identified? - Is the software version available? - Are keywords or topics present? --- ## Step 2 — Generate `codemeta.json` with SOMEF Copy the GitHub Action template provided in this repository at [`.github/workflows/generate-codemeta.yml`](../.github/workflows/generate-codemeta.yml) for **CodeMeta generation with SOMEF**. Place the workflow file inside: ```text .github/workflows/ ``` For example: ```text .github/workflows/generate-codemeta.yml ``` Commit and push the workflow to GitHub. Then: 1. Open the **Actions** tab of your repository. 2. Locate the CodeMeta generation workflow. 3. Run the workflow if it is configured for manual execution, or trigger it according to the instructions provided in the template. 4. The workflow will use **SOMEF** to extract software metadata from the repository. 5. Check whether a `codemeta.json` file has been created or updated. ### Checkpoint Confirm that: - the GitHub Action completed successfully, - SOMEF generated the metadata, - a `codemeta.json` file was produced, - the generated file is valid JSON. --- ## Step 3 — Analyse and adjust the generated `codemeta.json` Open the `codemeta.json` generated by SOMEF. Compare its content with the information available in your repository. Pay particular attention to fields such as: - `name` - `description` - `author` - `license` - `version` - `codeRepository` - `programmingLanguage` - `keywords` - `dateCreated` - `dateModified` - `softwareRequirements` Ask yourself: - Is the metadata extracted by SOMEF correct? - Is important information missing? - Has any information been inferred incorrectly? - Could some values be more precise? - Does the metadata accurately describe the software? Modify the repository metadata or the `codemeta.json` file as appropriate. ### Expected result At this point, you should have a first improved version of your CodeMeta metadata. --- > **Optional stretch — Steps 4–8** > > RSFC and RSMetadataCheck workflow templates are not bundled in this repository (their exact > package/action names should be confirmed against current tooling before running these > steps). If time or tooling doesn't allow it, stop after Step 3 with a working > `codemeta.json` — that already covers this webinar's Part 2 objective. ## Step 4 — Add the RSFC FAIR Assessment GitHub Action Copy the GitHub Action template provided for **FAIR assessment with RSFC** into: ```text .github/workflows/ ``` For example: ```text .github/workflows/fair-assessment.yml ``` Commit and push the workflow. Open the **Actions** tab and locate the RSFC FAIR assessment workflow. --- ## Step 5 — Run the FAIR Assessment with RSFC Run the FAIR assessment workflow. The workflow will use **RSFC** to evaluate the FAIRness of the research software. Once the assessment has finished, inspect the results. Identify: - tests that passed, - tests that failed, - warnings or recommendations, - the metadata elements related to each result. Do not focus only on the final score. The most useful part of the assessment is understanding **why a specific test passed or failed**. ### Checkpoint Select at least one failed FAIR test and identify: 1. what the test is checking, 2. why your repository or metadata did not pass it, 3. what change could improve the result. --- ## Step 6 — Fix one failed FAIR test Choose **one failed RSFC test** that you think can reasonably be addressed during the workshop. Modify the repository or its metadata accordingly. Examples may include: - adding a missing licence, - improving the software description, - adding an identifier, - adding missing author information, - adding a repository URL, - improving metadata completeness. Commit and push your changes. Run the RSFC FAIR assessment again. ### Compare the results Check whether: - the selected test now passes, - the FAIR score changed, - the change affected any other tests. Document what you changed and why. --- ## Step 7 — Detect metadata pitfalls with RSMetadataCheck Copy the GitHub Action template provided for **RSMetadataCheck** into: ```text .github/workflows/ ``` For example: ```text .github/workflows/metadata-pitfalls.yml ``` Commit and push the workflow. Run the GitHub Action. The workflow will use **RSMetadataCheck** to detect common research software metadata pitfalls. Inspect the results and identify detected issues such as: - missing metadata, - inconsistent metadata, - incomplete author information, - missing or unclear licence information, - missing repository information, - weak descriptions, - missing links or identifiers, - inconsistencies between metadata files. ### Checkpoint Choose one pitfall and determine: - why RSMetadataCheck detected it, - where the problematic metadata comes from, - how it could be corrected. --- ## Step 8 — Fix one detected pitfall Select **one RSMetadataCheck pitfall** that can be addressed during the session. Modify the relevant metadata or repository configuration. Commit and push your change. Run the RSMetadataCheck workflow again. Check whether the issue has disappeared or changed. --- # Final result By the end of the exercise, you should have: - selected a research software repository, - generated a `codemeta.json` file with **SOMEF** using GitHub Actions, - reviewed and improved the generated CodeMeta metadata, - executed a FAIR assessment with **RSFC**, - understood at least one failed FAIR test, - attempted to solve one failed FAIR test, - executed **RSMetadataCheck**, - understood at least one detected metadata pitfall, - attempted to solve one metadata pitfall. ## Reflection Before finishing, discuss briefly: 1. Which metadata could SOMEF generate automatically? 2. Which metadata required manual intervention? 3. Was RSFC useful for identifying actionable FAIR improvements? 4. Did RSMetadataCheck identify problems that were not obvious from the FAIR assessment? 5. Which of these checks would you integrate into your normal software development workflow? ## Optional challenge If you finish early: - solve an additional failed RSFC test, - solve an additional RSMetadataCheck pitfall, - compare the repository before and after the improvements, - inspect whether one change improves both the FAIR assessment and the metadata quality checks.