From 27d3f1e839fd13e24afac05f086d1651fc69cf54 Mon Sep 17 00:00:00 2001 From: Eva Martin del Pico Date: Tue, 7 May 2024 10:31:22 +0200 Subject: [PATCH] add github actions to copy cotributiona and intordutory text. Navigation updated. --- .github/workflows/copy_contributing.yml | 31 +++++++++++++++++++++ CONTRIBUTING.md | 1 + docs/index.md | 30 -------------------- docs/introduction/index.md | 37 +++++++++++++++++++++++++ mkdocs.yml | 30 ++++++++++---------- 5 files changed, 84 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/copy_contributing.yml create mode 100644 CONTRIBUTING.md delete mode 100644 docs/index.md create mode 100644 docs/introduction/index.md diff --git a/.github/workflows/copy_contributing.yml b/.github/workflows/copy_contributing.yml new file mode 100644 index 0000000..5ce4520 --- /dev/null +++ b/.github/workflows/copy_contributing.yml @@ -0,0 +1,31 @@ +name: Copy CONTRIBUTING.md + +on: + push: + branches: + - main # Change this to the name of your main branch + +jobs: + copy-contributing: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Copy CONTRIBUTING.md to docs/introduction directory + run: | + mkdir -p docs/introduction + cp CONTRIBUTING.md docs/introduction/ + + - name: Commit changes + run: | + git config --global user.name "GitHub Actions" + git config --global user.email "actions@users.noreply.github.com" + git add docs/introduction/CONTRIBUTING.md + git commit -m "Automatically update contributing.md" + + - name: Push changes + uses: ad-m/github-push-action@master + with: + github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5785200 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +# How to Contribute \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 857b6bc..0000000 --- a/docs/index.md +++ /dev/null @@ -1,30 +0,0 @@ -# Overview - - -## Findability indicators - -- **F1. Identity Uniqueness:** Whether the software has a proper, unique and persistent identifier. -- **F2. Existence of Metadata:** Whether the software is described with rich metadata, including scientific applicability. -- **F3. Discoverability:** How software can be found. - - -## Accessibility indicators - -- **A1. Existence of an available working version:** Whether it is possible to access/download/build a working version of the software. -- **A2. Software history trackability:** Whether code and metadata are available even when the software is no longer in use. -- **A3. Unrestricted access**: Whether the software lacks restrictions in terms of authorization and infrastructure/platform needed to use it. - - -## Interoperability indicators - -- **I1. Data Format Standards and Practices:** Whether the software adheres to data format standards and its operational practices concerning data handling it encompasses standard formats and APIs, the flexibility and verifiability of these formats, and the tracking of data provenance. -- **I2. Software Integration:** Whether software can be easily integrated into workflows or used in connection with other software. -- **I3. Dependencies availability**: Whether dependencies are documented and mechanisms to obtain them exist. - - -## Reusability indicators - -- **R1. Existence of usage documentation:** Whether software provides adequate usage documentation. -- **R2. Existence of license and/or terms of use:** Whether a clear and accessible usage license is provided. -- **R3. Existence of Contribution Recognition and Governance:** Whether there are policies governing contributor roles and systems in place for acknowledging their contributions ensuring fair and transparent collaboration within software projects. -- **R4. Existence of Versioning and Historical Traceability:** How effectively the software manages version control and documents historical changes, ensuring clear updates traceability and consistency in release practices for enhanced reliability, sustainability and auditability. \ No newline at end of file diff --git a/docs/introduction/index.md b/docs/introduction/index.md new file mode 100644 index 0000000..64bdba0 --- /dev/null +++ b/docs/introduction/index.md @@ -0,0 +1,37 @@ +# Overview + + +Designed to be measured in an automated way, the FAIRsoft indicators offer an efficient means of evaluating research software FAIRness, enabling developers and stakeholders to optimize the impact and longevity of their software. + +Each high-level FAIRsoft indicator is supported by several associated low-level indicators, which must be fulfilled to consider the high-level indicator achieved. By considering these low-level indicators, practitioners can work towards aligning their software with the criteria outlined by the FAIR principles, contributing to the ongoing effort to enhance the quality and FAIRness of research software. + + +The following list outlines the high-level FAIR indicators for research software. A detailed explanation of the low-level indicators that support each high-level indicator can be found in the respective sections. This explanation includes the rationale for measuring the indicator, the method of measurement, and the types of software to which it applies. + +## Findability indicators + +- **[F1. Identity Uniqueness](./findability/F1_identity_uniqueness.md):** Whether the software has a proper, unique and persistent identifier. +- **[F2. Existence of Metadata](./findability/F2_existence_of_metadata.md):** Whether the software is described with rich metadata, including scientific applicability. +- **[F3. Discoverability](./findability/F3_searchability.md):** How software can be found. + + +## Accessibility indicators + +- **[A1. Existence of an available working version](./accessibility/A1_downloadable.md):** Whether it is possible to access/download/build a working version of the software. +- **[A2. Software history trackability](./accessibility/A2_trackability.md):** Whether code and metadata are available even when the software is no longer in use. +- **[A3. Unrestricted access](./accessibility/A3_unrestricted_access.md)**: Whether the software lacks restrictions in terms of authorization and infrastructure/platform needed to use it. + + +## Interoperability indicators + +- **[I1. Data Format Standards and Practices](./interoperability/I1_input_output.md):** Whether the software adheres to data format standards and its operational practices concerning data handling it encompasses standard formats and APIs, the flexibility and verifiability of these formats, and the tracking of data provenance. +- **[I2. Software Integration](./interoperability/I2_workflow_compatibility.md):** Whether software can be easily integrated into workflows or used in connection with other software. +- **[I3. Dependencies availability](./interoperability/I3_dependencies_available.md)**: Whether dependencies are documented and mechanisms to obtain them exist. + + +## Reusability indicators + +- **[R1. Existence of usage documentation](./reusability/R1_usage_documentation.md):** Whether software provides adequate usage documentation. +- **[R2. Existence of license and/or terms of use](./reusability/R2_license.md):** Whether a clear and accessible usage license is provided. +- **[R3. Existence of Contribution Recognition and Governance](./reusability/R3_contribution_policy.md):** Whether there are policies governing contributor roles and systems in place for acknowledging their contributions ensuring fair and transparent collaboration within software projects. +- **[R4. Existence of Versioning and Historical Traceability](./reusability/R4_provenance.md):** How effectively the software manages version control and documents historical changes, ensuring clear updates traceability and consistency in release practices for enhanced reliability, sustainability and auditability. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index b3c26f9..48d6774 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,7 +93,9 @@ repo_url: https://github.com/inab/FAIRsoft_indicators # | | # +--------------------------------------------------------------------------------------------------------+ nav: - - Overview: index.md + - Overview: + - The FAIRsoft indicators: introduction/index.md + - How to contribute: introduction/CONTRIBUTING.md - Findability: - F1. Identity Uniqueness: findability/F1_identity_uniqueness.md - F2. Existence of metadata: findability/F2_existence_of_metadata.md @@ -112,7 +114,8 @@ nav: - R3. Existence of Contribution Recognition and Governance: reusability/R3_contribution_policy.md - R4. Existence of Versioning and Historical Traceabilitye: reusability/R4_provenance.md - + + # +--------------------------------------------------------------------------------------------------------+ # | | @@ -286,8 +289,10 @@ theme: # | | # +------------------------------------------------------------------------------------------------------+ features: - - content.tabs.link - #- navigation.sections + + #- content.tabs.link + + # Announce # @@ -298,16 +303,11 @@ theme: #- header.autohide # Hide header when user scrolls past a specific point. # Navigation: - # - - navigation.expand # Expand all collapsable sections. - - navigation.instant # Instant loading pages. - # - navigation.indexes # Attach pages directly to Sections. Incompatible with "toc.integrate" - - navigation.sections # Render top sections as groups. - # - navigation.tabs # Render top sections as tabs at the top. - #- navigation.tabs.sticky # Tabs won't disappear when scrolling down. Requires "navigation.tabs". - #- navigation.top # Adds a "Back to top" that is shown when scrolling up. - - navigation.tracking # Updates the url with highlighted section anchor. - + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.path + # Search # #- search.highlight # Search will highlight the searched word(s) on the page.* @@ -316,7 +316,7 @@ theme: # Table of Contents # - - toc.integrate # Include the TOC sections in the left navugation. + #- toc.integrate # Include the TOC sections in the left navugation. # +------------------------------------------------------------------------------------------------------+ # | |