diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd0dfc0..66474c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ For larger changes — new sections, structural reorganisation, or changes to co 1. **Fork** this repository and create a branch from `main`. 2. **Make your changes** in the relevant Markdown file(s) under `source/`. -3. **Build locally** (optional but recommended) to check the output looks correct — see the [local build instructions](README.md#editing-and-building-locally) in the README. +3. **Build locally** (optional but recommended) to check the output looks correct — see the [local build instructions](README.md#building-locally) in the README. 4. **Open a pull request** against `main` with a clear description of what you changed and why. 5. A maintainer will review and may request changes before merging. @@ -33,7 +33,7 @@ For larger changes — new sections, structural reorganisation, or changes to co ## Section ownership -Each chapter and section has an owner listed in the [README](README.md#chapter-and-section-owners). If your change touches a specific section, it is good practice to request a review from the relevant owner. +Each chapter and section has an owner listed in the [README](README.md#section-owners). If your change touches a specific section, it is good practice to request a review from the relevant owner. ## Licensing @@ -41,4 +41,4 @@ By submitting a contribution, you agree that your work will be released under th ## Questions -If you are unsure where to start or have questions about the contribution process, open an issue or contact the EVERSE Task Force 2 team. +If you are unsure where to start or have questions about the contribution process, open an issue or contact the maintainers: [@gperu](https://github.com/gperu) and [@fdiblen](https://github.com/fdiblen). diff --git a/README.md b/README.md index 688bc31..4b15775 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,14 @@ # EVERSE Reference Framework -The EVERSE Reference Framework (RF) establishes quality assessment standards for research software across diverse research communities. It serves as both a theoretical foundation and practical guide for research software quality. +The EVERSE Reference Framework establishes quality assessment standards for research software. It covers twelve quality dimensions — nine technical dimensions based on ISO/IEC 25010:2023, plus FAIRness, Open Source Software, and Sustainability — and provides four complementary views (three-tier model, software lifecycle, personas, and science clusters) to help different stakeholders apply them. -## About +**Read the framework:** [Latest version (PDF)](reference-framework.pdf) · [Stable release v2.1 on Zenodo](https://doi.org/10.5281/zenodo.15856368) -The RF addresses research software quality through four main pillars: -- **Technical dimensions** based on ISO/IEC 25010:2023 standards -- **FAIR principles** for research software -- **Open source software** practices -- **Sustainability** considerations +**Version 2.1** (July 2025) — [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15856368.svg)](https://doi.org/10.5281/zenodo.15856368) [![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) -The framework targets multiple stakeholder groups through four complementary views: -- **Three-tier model** categorising software by complexity -- **Software lifecycle** development stages -- **Personas** role-based perspectives -- **Science clusters** domain-specific applications +## Section owners -## Current version - -**Version 2.1** (published July 2025) - -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15856368.svg)](https://doi.org/10.5281/zenodo.15856368) -[![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) - -## Chapter and Section owners +Each section has an owner responsible for its content. To claim a section, add yourself to the table and open a pull request. | Name (optionally email) | GitHub username | Affiliation | Chapter and Section | | :---------------------- | :-------------: | :---------: | :------------------ | @@ -40,159 +25,43 @@ The framework targets multiple stakeholder groups through four complementary vie | Your name | @username | Your affiliation | **Chapter-3:** Science Clusters View ([#14](https://github.com/EVERSE-ResearchSoftware/reference-framework/issues/14)) | | Your name | @username | Your affiliation | **Chapter-4:** Conclusions ([#15](https://github.com/EVERSE-ResearchSoftware/reference-framework/issues/15)) | -## Repository structure - -``` -reference-framework/ -├── README.md -├── CONTRIBUTING.md -├── LICENSE -├── Makefile # Build targets (pdf, html, markdown) -├── .github/ -│ └── workflows/ -│ └── build-pdf.yml # CI pipeline for PDF generation -├── templates/ -│ ├── everse.latex # Pandoc LaTeX template -│ └── logos/ # Header/footer logos -├── source/ -│ ├── main.md # Metadata (title, version, authors) -│ ├── 01-introduction/ -│ │ └── index.md -│ ├── 02-framework/ -│ │ ├── index.md -│ │ ├── technical-dimensions.md -│ │ ├── fair.md -│ │ ├── open-source-software.md -│ │ └── sustainability.md -│ ├── 03-views/ -│ │ ├── index.md -│ │ ├── three-tiers.md -│ │ ├── software-lifecycle.md -│ │ ├── personas.md -│ │ └── science-clusters.md -│ ├── 04-conclusions/ -│ │ └── index.md -│ └── figures/ # Diagrams and images -├── assets/ -│ └── EVERSE_reference_framework_v2.pdf # Archived v2.0 PDF -└── build/ # Generated output (gitignored) -``` +## Building locally -## Editing and building locally +The document source is in `source/` as Markdown files, combined by the `Makefile`. Output goes to `build/`. -### Prerequisites - -To build the PDF you need: - -- [Pandoc](https://pandoc.org/installing.html) (3.0 or later) -- A TeX Live installation with LuaLaTeX and the following packages: `titlesec`, `setspace`, `fontspec`, `fancyhdr`, `geometry`, `longtable`, `booktabs`, `tex-gyre` fonts -- GNU Make - -On **Ubuntu/Debian**: +**Prerequisites:** [Pandoc](https://pandoc.org/installing.html) 3.0+, LuaLaTeX (via TeX Live), GNU Make. ```bash +# Ubuntu/Debian sudo apt install pandoc texlive-luatex texlive-latex-extra texlive-fonts-extra make -``` - -On **macOS** (with Homebrew): - -```bash -brew install pandoc make -brew install --cask mactex -``` - -On **Fedora**: - -```bash -sudo dnf install pandoc texlive-scheme-medium texlive-titlesec texlive-setspace texlive-tex-gyre make -``` - -### Editing - -The document source lives under `source/` as Markdown files. Edit the files directly -- they are combined in the order listed in the `Makefile`. Metadata (title, version, authors) is in `source/main.md`. - -Images go in `source/figures/` and are referenced with relative paths from each Markdown file, e.g.: -```markdown -![Caption text](../figures/my-figure.png){ width=70% } +# macOS +brew install pandoc make && brew install --cask mactex ``` -The `{ width=70% }` attribute controls how wide the figure appears in the PDF (percentage of page width). - -### Building - -From the repository root: - ```bash -# Build PDF (default target) -make pdf - -# Build single-file HTML -make html - -# Build combined Markdown -make markdown - -# Remove all build output -make clean +make pdf # Build PDF (default) +make html # Build single-file HTML +make markdown # Build combined Markdown +make clean # Remove build output ``` -Output is written to the `build/` directory. - -## Development workflow - -The Reference Framework follows a periodic release model: - -- **GitHub main branch**: Contains work-in-progress for the next version -- **Zenodo releases**: Stable, citable versions with DOIs -- **Version releases**: Major versions only (v2, v3, v4...) - -### Release process - -1. Work on main branch accumulates changes and improvements -2. When ready for release, create git tag (e.g., `v3.0`) -3. Generate PDF from markdown source -4. Publish to Zenodo with DOI -5. Continue development on main for next version +## Contributing -### Between releases - -- Changes tracked via GitHub issues and pull requests -- Feedback from TF2 meetings, presentations, and community incorporated -- No automatic synchronisation from other EVERSE repositories (indicators, RSQKit) -- Alignment maintained through manual review and discussion - -## How to contribute - -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting issues, proposing changes, and submitting pull requests. +See [CONTRIBUTING.md](CONTRIBUTING.md). The `main` branch is work-in-progress for the next version; stable releases are published to Zenodo. ## Relationship to other EVERSE tools -- **RSQKit**: Actionable knowledge hub translating RF concepts into practical guidance -- **TechRadar**: Tool cataloguing system -- **Indicators repository**: Canonical source for dimensions and indicators data -- **QualityPipelines/resqui**: Automated assessment tools -- **DashVERSE**: Visualisation platform +The RF provides conceptual foundations for the EVERSE ecosystem: **RSQKit** translates RF concepts into practical guidance, the **Indicators repository** is the canonical source for dimensions and indicators data, and **QualityPipelines/resqui** and **DashVERSE** provide automated assessment and visualisation. -The RF provides conceptual foundations whilst these tools enable practical implementation. - -## Versions +## Contact -- **v2.1** (July 2025): Twelve quality dimensions established (nine technical plus FAIR, Open Source Software, and Sustainability) -- **v3.0** (target Summer 2026): Refinement and integration of community feedback +For questions, open an issue or reach out to the maintainers: [@gperu](https://github.com/gperu) and [@fdiblen](https://github.com/fdiblen). -## How to cite +## Cite as > EVERSE Consortium. (2025). EVERSE Reference Framework for Research Software Quality (v2.0). Zenodo. https://doi.org/10.5281/zenodo.15856368 -## Contact - -For questions about the Reference Framework, contact the EVERSE Task Force 2 team or open an issue in this repository. - ## Licence -This work is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). - -## Acknowledgements - -This work is funded by the European Union's Horizon Europe research and innovation programme under grant agreement No. 101129744 (EVERSE). +[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/) — funded by the European Union's Horizon Europe programme, grant agreement No. 101129744 (EVERSE). diff --git a/reference-framework.pdf b/reference-framework.pdf index 4ba7149..ba74c5f 100644 Binary files a/reference-framework.pdf and b/reference-framework.pdf differ