diff --git a/.editorconfig b/.editorconfig index 53a78eb..be794c1 100644 --- a/.editorconfig +++ b/.editorconfig @@ -12,6 +12,7 @@ max_line_length = off indent_size = 4 [*.bat] +indent_style = tab end_of_line = crlf [*.{yaml,yml}] @@ -25,3 +26,6 @@ indent_size = 2 [*.js] indent_size = 2 + +[Makefile] +indent_style = tab diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce61019..7354c43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,16 +78,16 @@ fix: correct typos When contributing to the documentation, please follow these steps: 1. Fork the repository (if not in the OSTrails organization). -2. Create a new branch for your changes (base = `develop`). +2. Create a new branch for your changes (base = `next`). 3. Make your changes and commit them. 4. Push your changes. -5. Open a pull request to the `develop` branch of the main repository. +5. Open a pull request to the `next` branch of the main repository. ### Crediting Contributors We will credit all contributors in the documentation. If you would like to be credited, please add your name and related information to the [`CONTRIBUTORS.yml`](./CONTRIBUTORS.yml) file. -Then, you can add your name to the list of contributors for a specific page: +Then, you can add your name to the list of contributors for a specific page (under the first heading) using the `page-authors` directive: ```rst Page Title @@ -95,4 +95,5 @@ Page Title .. page-authors:: John Doe + ``` diff --git a/CONTRIBUTORS.yml b/CONTRIBUTORS.yml index 7376716..490681f 100644 --- a/CONTRIBUTORS.yml +++ b/CONTRIBUTORS.yml @@ -4,3 +4,38 @@ Marek Suchánek: github: MarekSuchanek orcid: 0000-0001-7525-9218 affiliation: CTU in Prague + +Daniel Garijo: + first_name: Daniel + last_name: Garijo + github: dgarijo + orcid: 0000-0003-0454-7145 + affiliation: Universidad Politécnica de Madrid + +Mark Wilkinson: + first_name: Mark + last_name: Wilkinson + github: markwilkinson + orcid: 0000-0001-6960-357X + affiliation: Universidad Politécnica de Madrid + +Tomasz Miksa: + first_name: Tomasz + last_name: Miksa + github: TomMiksa + orcid: 0000-0002-4929-7875 + affiliation: TU Wien + +John Shepherdson: + first_name: John + last_name: Shepherdson + github: john-shepherdson + orcid: 0000-0002-4402-9644 + affiliation: CESSDA ERIC + +Allyson Lister: + first_name: Allyson + last_name: Lister + github: allysonlister + orcid: 0000-0002-7702-4495 + affiliation: University of Oxford diff --git a/README.md b/README.md index 63c9723..10498a4 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # OSTrails Read-the-Docs Documentation -[![Documentation Status](https://readthedocs.org/projects/ostrails/badge/?version=latest)](https://ostrails.readthedocs.io/en/latest/?badge=latest) +[![Documentation Status](https://readthedocs.org/projects/ostrails-docs/badge/?version=latest)](https://docs.ostrails.eu) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md) ## Usage -This repository contains the source files for the OSTrails documentation. The documentation is hosted on Read-the-Docs and can be accessed [here](https://ostrails.readthedocs.io/en/latest/). +This repository contains the source files for the OSTrails documentation. The documentation is hosted on Read-the-Docs and can be accessed [here](https://docs.ostrails.eu/en/latest/). ## Contributing diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..f7f816a --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,47 @@ +# Changelog + +## [3.2.0](https://github.com/editorconfig-checker/editorconfig-checker/compare/v3.1.2...v3.2.0) (2025-01-25) + + +### Features + +* add support for env var NO_COLOR ([#429](https://github.com/editorconfig-checker/editorconfig-checker/issues/429)) ([9135f53](https://github.com/editorconfig-checker/editorconfig-checker/commit/9135f531e762ad4c02f4bf45f03888771773da56)) +* only output "0 errors found" when verbose output is enabled ([#423](https://github.com/editorconfig-checker/editorconfig-checker/issues/423)) ([1d29a8b](https://github.com/editorconfig-checker/editorconfig-checker/commit/1d29a8b16b4cde8d46f80db29e60330c5bd16095)) + + +### Bug Fixes + +* improve default excludes ([#427](https://github.com/editorconfig-checker/editorconfig-checker/issues/427)) ([d0cbd25](https://github.com/editorconfig-checker/editorconfig-checker/commit/d0cbd250caa46a07994b6161ccf2bb4910571a23)) + +## [3.1.2](https://github.com/editorconfig-checker/editorconfig-checker/compare/v3.1.1...v3.1.2) (2025-01-10) + + +### Bug Fixes + +* provide both .tar.gz as well as .zip archives ([#416](https://github.com/editorconfig-checker/editorconfig-checker/issues/416)) ([00e9890](https://github.com/editorconfig-checker/editorconfig-checker/commit/00e9890847982b2503ec3a11ff539bf2ac4c34c6)), closes [#415](https://github.com/editorconfig-checker/editorconfig-checker/issues/415) + +## [3.1.1](https://github.com/editorconfig-checker/editorconfig-checker/compare/v3.1.0...v3.1.1) (2025-01-08) + + +### Bug Fixes + +* dockerfile expected binary at /, not /usr/bin/ [#410](https://github.com/editorconfig-checker/editorconfig-checker/issues/410) ([#411](https://github.com/editorconfig-checker/editorconfig-checker/issues/411)) ([2c82197](https://github.com/editorconfig-checker/editorconfig-checker/commit/2c821979c0b3ea291f65ec813cae3fa265603528)) + +## [3.1.0](https://github.com/editorconfig-checker/editorconfig-checker/compare/v3.0.3...v3.1.0) (2025-01-06) + + +### Features + +* add zip version when compressing all binaries ([#321](https://github.com/editorconfig-checker/editorconfig-checker/issues/321)) ([#362](https://github.com/editorconfig-checker/editorconfig-checker/issues/362)) ([f1bb625](https://github.com/editorconfig-checker/editorconfig-checker/commit/f1bb625f2553952d4d8c72e3f97d17417f0c1ef7)) +* consolidate adjacent error messages ([#360](https://github.com/editorconfig-checker/editorconfig-checker/issues/360)) ([cf4ae1c](https://github.com/editorconfig-checker/editorconfig-checker/commit/cf4ae1ccede331b2aa1b115f1de5257737de7eef)) +* editorconfig-checker-disable-next-line ([#363](https://github.com/editorconfig-checker/editorconfig-checker/issues/363)) ([6116ec6](https://github.com/editorconfig-checker/editorconfig-checker/commit/6116ec6685b33652e9e25def9b8897ed4b015c7d)) +* provide Codeclimate compatible report fromat ([#367](https://github.com/editorconfig-checker/editorconfig-checker/issues/367)) ([282c315](https://github.com/editorconfig-checker/editorconfig-checker/commit/282c315bd1c48f49cc1328de36e2ba4433c50249)) +* support `.editorconfig-checker.json` config ([#375](https://github.com/editorconfig-checker/editorconfig-checker/issues/375)) ([cb0039c](https://github.com/editorconfig-checker/editorconfig-checker/commit/cb0039cfe68a11139011bcffe84b8ff62b3209bb)) + + +### Bug Fixes + +* actually use the correct end marker ([#405](https://github.com/editorconfig-checker/editorconfig-checker/issues/405)) ([3c03499](https://github.com/editorconfig-checker/editorconfig-checker/commit/3c034994cba21db7babd33672a0d26184ff88255)) +* add `.ecrc` deprecation warning ([#389](https://github.com/editorconfig-checker/editorconfig-checker/issues/389)) ([d33b81c](https://github.com/editorconfig-checker/editorconfig-checker/commit/d33b81cc71c2eb740dd3e1c00f07dbc430b89087)) +* this release-please marker ([#403](https://github.com/editorconfig-checker/editorconfig-checker/issues/403)) ([617c6d4](https://github.com/editorconfig-checker/editorconfig-checker/commit/617c6d44b5a8668de16bf67038dd5930e01c074e)) +* typo in config, `SpacesAftertabs` => `SpacesAfterTabs` ([#386](https://github.com/editorconfig-checker/editorconfig-checker/issues/386)) ([25e3542](https://github.com/editorconfig-checker/editorconfig-checker/commit/25e3542ee45b0bd5cbdd450ba8eebee6ad3bba43)) diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000..5420ac5 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2018 Max Strübing + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..67b45ac --- /dev/null +++ b/docs/README.md @@ -0,0 +1,438 @@ +# editorconfig-checker + +Buy Me A Coffee + +[![ci](https://github.com/editorconfig-checker/editorconfig-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/editorconfig-checker/editorconfig-checker/actions/workflows/ci.yml) +[![codecov](https://codecov.io/gh/editorconfig-checker/editorconfig-checker/branch/main/graph/badge.svg)](https://codecov.io/gh/editorconfig-checker/editorconfig-checker) +[![Hits-of-Code](https://hitsofcode.com/github/editorconfig-checker/editorconfig-checker?branch=main&label=Hits-of-Code)](https://hitsofcode.com/github/editorconfig-checker/editorconfig-checker/view?branch=main&label=Hits-of-Code) +[![Go Report Card](https://goreportcard.com/badge/github.com/editorconfig-checker/editorconfig-checker/v3)](https://goreportcard.com/report/github.com/editorconfig-checker/editorconfig-checker/v3) + +![Logo](docs/logo.png) + +1. [What?](#what) +2. [Quickstart](#quickstart) +3. [Installation](#installation) +4. [Usage](#usage) +5. [Configuration](#configuration) +6. [Excluding](#excluding) + 1. [Excluding Lines](#excluding-lines) + 2. [Excluding Blocks](#excluding-blocks) + 3. [Excluding Paths](#excluding-paths) + 1. [Inline](#inline) + 2. [Default Excludes](#default-excludes) + 3. [Ignoring Default Excludes](#ignoring-default-excludes) + 4. [Manually Excluding](#manually-excluding) + 1. [via configuration](#via-configuration) + 2. [via arguments](#via-arguments) +7. [Docker](#docker) +8. [Continuous Integration](#continuous-integration) +9. [Support](#support) +10. [Contributing](#contributing) +11. [Semantic Versioning Policy](#semantic-versioning-policy) + +## What? + +![Example Screenshot](docs/screenshot.png) + +This is a tool to check if your files consider your `.editorconfig` rules. +Most tools—like linters, for example—only test one filetype and need an extra configuration. +This tool only needs your `.editorconfig` to check all files. + +If you don't know about editorconfig already you can read about it here: [editorconfig.org](https://editorconfig.org/). + +Currently, implemented editorconfig features are: + +- `end_of_line` +- `insert_final_newline` +- `trim_trailing_whitespace` +- `indent_style` +- `indent_size` +- `max_line_length` + +Unsupported features are: + +- `charset` + +## Quickstart + + +```shell +VERSION="v3.2.0" +OS="linux" +ARCH="amd64" +curl -O -L -C - https://github.com/editorconfig-checker/editorconfig-checker/releases/download/$VERSION/ec-$OS-$ARCH.tar.gz && \ +tar xzf ec-$OS-$ARCH.tar.gz && \ +./bin/ec-$OS-$ARCH +``` + + +## Installation + +Grab a binary from the [release page](https://github.com/editorconfig-checker/editorconfig-checker/releases). + +If you have go installed you can run `go get github.com/editorconfig-checker/editorconfig-checker/v3` +and run `make build` inside the project folder. +This will place a binary called `ec` into the `bin` directory. + +If you are using Arch Linux, you can use [pacman](https://wiki.archlinux.org/title/Pacman) to install from [extra repository](https://archlinux.org/packages/extra/x86_64/editorconfig-checker/): + +```shell +pacman -S editorconfig-checker +``` + +Also, development (VCS) package is available in the [AUR](https://aur.archlinux.org/packages/editorconfig-checker-git): + +```shell +# editorconfig-checker-git + +# i.e. +paru -S editorconfig-checker-git +``` + +If Go 1.16 or greater is installed, you can also install it globally via `go install`: + +```shell +go install github.com/editorconfig-checker/editorconfig-checker/v3/cmd/editorconfig-checker@latest +``` + +## Usage + +```txt +USAGE: + -config string + config + -debug + print debugging information + -disable-end-of-line + disables the trailing whitespace check + -disable-indent-size + disables only the indent-size check + -disable-indentation + disables the indentation check + -disable-insert-final-newline + disables the final newline check + -disable-trim-trailing-whitespace + disables the trailing whitespace check + -dry-run + show which files would be checked + -exclude string + a regex which files should be excluded from checking - needs to be a valid regular expression + -format + specifies the output format, see "Formats" below for more information + -h print the help + -help + print the help + -ignore-defaults + ignore default excludes + -init + creates an initial configuration + -no-color + disables printing color + -color + enables printing color + -v print debugging information + -verbose + print debugging information + -version + print the version number +``` + +If you run this tool from a repository root it will check all files which are added to the git repository and are text files. If the tool isn't able to determine a file type it will be added to be checked too. + +If you run this tool from a normal directory it will check all files which are text files. If the tool isn't able to determine a file type it will be added to be checked too. + +### Formats + +The following output formats are supported: + +- **default**: Plain text, human readable output.
+ ```text + : + -: + ``` +- **gcc**: GCC compatible output. Useful for editors that support compiling and showing syntax errors.
+ `::: : ` +- **github-actions**: The format used by GitHub Actions
+ `::error file=,line=,endLine=::` +- **codeclimate**: The [Code Climate](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) json format used for [custom quality reports](https://docs.gitlab.com/ee/ci/testing/code_quality.html#implement-a-custom-tool) in GitLab CI + ```json + [ + { + "check_name": "editorconfig-checker", + "description": "Wrong indent style found (tabs instead of spaces)", + "fingerprint": "e87a958a3960d60a11d4b49c563cccd2", + "severity": "minor", + "location": { + "path": ".vscode/extensions.json", + "lines": { + "begin": 2, + "end": 2 + } + } + } + ] + ``` + +## Configuration + +The configuration is done via arguments or it will take the first config file found with the following file names: + +- `.editorconfig-checker.json` +- `.ecrc` (deprecated filename, soon unsupported) + +A sample configuration file can look like this and will be used from your current working directory if not specified via the `--config` argument: + +```json +{ + "Verbose": false, + "Debug": false, + "IgnoreDefaults": false, + "SpacesAfterTabs": false, + "NoColor": false, + "Exclude": [], + "AllowedContentTypes": [], + "PassedFiles": [], + "Disable": { + "EndOfLine": false, + "Indentation": false, + "IndentSize": false, + "InsertFinalNewline": false, + "TrimTrailingWhitespace": false, + "MaxLineLength": false + } +} +``` + +You can set any of the options under the `"Disable"` section to `true` to disable those particular checks. + +You could also specify command line arguments, and they will get merged with the configuration file. The command line arguments have a higher precedence than the configuration. + +You can create a configuration with the `init`-flag. If you specify a `config`-path it will be created there. + +By default, the allowed_content_types are: + +1. `text/` (matches `text/plain`, `text/html`, etc.) +1. `application/ecmascript` +1. `application/json` +1. `application/x-ndjson` +1. `application/xml` +1. `+json` (matches `application/geo+json`, etc.) +1. `+xml` (matches `application/rss+xml`, etc.) +1. `application/octet-stream` + +`application/octet-stream` is needed as a fallback when no content type could be determined. You can add additional accepted content types with the `allowed_content_types` key. But the default ones don't get removed. + +## Excluding + +### Excluding Lines + +You can exclude single lines inline. To do that you need a comment on that line that says: `editorconfig-checker-disable-line`. + +```javascript +const myTemplateString = ` + first line + wrongly indented line because it needs to be` // editorconfig-checker-disable-line +``` + +Alternatively, you can use `editorconfig-checker-disable-next-line` to skip the line that comes after this comment. +This modifier is present to improve readability, or because your sometimes have no other choice because of your own/language constraints. + +```javascript +// editorconfig-checker-disable-next-line used because blah blah blah what ever the reason blah +const myTemplateString = `a line that is (...) longer (...) than ... usual` // or with a very long inline comment +``` + +Please note that using `editorconfig-checker-disable-next-line` has only an effect on the next line, so it will report if the line where you added the modifier doesn't comply. + +### Excluding Blocks + +To temporarily disable all checks, add a comment containing `editorconfig-checker-disable`. Re-enable with a comment containing `editorconfig-checker-enable` + +```javascript +// editorconfig-checker-disable +const myTemplateString = ` + first line + wrongly indented line because it needs to be +` +// editorconfig-checker-enable +``` + +### Excluding Paths + +You can exclude paths from being checked in several ways: + +- ignoring a file by documenting it inside the to-be-excluded file +- adding a regex matching the path to the [configuration file](#configuration) +- passing a regex matching the path as argument to `--exclude` + +All these excludes are used in addition to the [default excludes](#default-excludes), unless you [opt out of them](#ignoring-default-excludes). + +If you want to see which files would be checked without checking them you can pass the `--dry-run` flag. + +Note that while `--dry-run` might output absolute paths, the regular expression you write must match the filenames using relative paths from where editorconfig-checker is used. This becomes especially relevant if you need to anchor your regular expression in order to only match files in the top level your checked directory. + +#### Inline + +If you want to exclude a file inline you need a comment on the first line of the file that contains: `editorconfig-checker-disable-file` + +```haskell +-- editorconfig-checker-disable-file +add :: Int -> Int -> Int +add x y = + let result = x + y -- falsy indentation would not report + in result -- falsy indentation would not report +``` + +#### Default Excludes + +If you choose to [ignore them](#ignoring-default-excludes), these paths are excluded automatically: + +```txt +"\\.git[\\/]", +"[\\/]node_modules[\\/]", +"^\\.yarn/", +"^yarn\\.lock$", +"^package-lock\\.json$", +"^composer\\.lock$", +"^Cargo\\.lock$", +"^Gemfile\\.lock$", +"^\\.pnp\\.cjs$", +"^\\.pnp\\.js$", +"^\\.pnp\\.loader\\.mjs$", +"\\.snap$", +"\\.otf$", +"\\.woff$", +"\\.woff2$", +"\\.eot$", +"\\.ttf$", +"\\.gif$", +"\\.png$", +"\\.jpg$", +"\\.jpeg$", +"\\.webp$", +"\\.avif$", +"\\.pnm$", +"\\.pbm$", +"\\.pgm$", +"\\.ppm$", +"\\.mp4$", +"\\.wmv$", +"\\.svg$", +"\\.ico$", +"\\.bak$", +"\\.bin$", +"\\.pdf$", +"\\.zip$", +"\\.gz$", +"\\.tar$", +"\\.7z$", +"\\.bz2$", +"\\.log$", +"\\.patch$", +"\\.css\\.map$", +"\\.js\\.map$", +"min\\.css$", +"min\\.js$", +``` + +#### Ignoring Default Excludes + +If you either set `IgnoreDefaults` to `true` or pass the `-ignore-defaults` commandline switch, the [default excludes](#default-excludes) will be ignored entirely. + +#### Manually Excluding + +##### via configuration + +In your [configuration file](#configuration) you can exclude files with the `"exclude"` key which takes an array of regular expressions. +This will get merged with the default excludes (if not [ignored](#ignoring-default-excludes)). You should remember to escape your regular expressions correctly. + +A [configuration file](#configuration) which would ignore all test files and all Markdown files can look like this: + +```json +{ + "Verbose": false, + "IgnoreDefaults": false, + "Exclude": ["testfiles", "\\.md$"], + "SpacesAfterTabs": false, + "Disable": { + "EndOfLine": false, + "Indentation": false, + "IndentSize": false, + "InsertFinalNewline": false, + "TrimTrailingWhitespace": false, + "MaxLineLength": false + } +} +``` + +##### via arguments + +If you want to play around how the tool would behave you can also pass the `--exclude` argument to the binary. This will accept a regular expression as well. The argument given will be added to the excludes as defined by your [configuration file](#configuration) (respecting both its [`Exclude`](#via-configuration) and [`IgnoreDefaults`](#ignoring-default-excludes) settings). + +For example: `ec --exclude node_modules` + +## Docker + +You are able to run this tool inside a Docker container. +To do this you need to have Docker installed and run this command in your repository root which you want to check: +`docker run --rm --volume=$PWD:/check mstruebing/editorconfig-checker` + +Docker Hub: [mstruebing/editorconfig-checker](https://hub.docker.com/r/mstruebing/editorconfig-checker) + +## Continuous Integration + +### Mega-Linter + +Instead of installing and configuring `editorconfig-checker` and all other linters in your project CI workflows (GitHub Actions & others), you can use [Mega-Linter](https://megalinter.io/latest/) which does all that for you with a single [assisted installation](https://megalinter.io/latest/install-assisted/). + +Mega-Linter embeds [editorconfig-checker](https://megalinter.io/latest/descriptors/editorconfig_editorconfig_checker/) by default in all its [flavors](https://megalinter.io/latest/flavors/), meaning that it will be run at each commit or Pull Request to detect any issue related to `.editorconfig`. + +If you want to use only `editorconfig-checker` and not the 70+ other linters, you can use the following `.mega-linter.yml` configuration file: + +```yaml +ENABLE: + - EDITORCONFIG +``` + +### GitLab CI + +The [ss-open/ci/recipes project](https://gitlab.com/ss-open/ci/recipes) offers a ready to use lint job integrating editorconfig-checker. + +- Main documentation: +- Editorconfig job specific documentation: + +## Support + +If you have any questions, suggestions, need a wrapper for a programming language or just want to chat join #editorconfig-checker on freenode(IRC). +If you don't have an IRC-client set up you can use the [freenode webchat](https://webchat.freenode.net/?channels=editorconfig-checker). + +## Contributing + +Anyone can help to improve the project, submit a Feature Request, a bug report or even correct a spelling mistake. + +The steps to contribute can be found in the [CONTRIBUTING.md](./CONTRIBUTING.md) file. + +## Semantic Versioning Policy + +**editorconfig-checker** adheres to [Semantic Versioning](https://semver.org/) for releases. + +However, as it is a code quality tool, it's not always clear when a minor or major version bump occurs. The following rules are used to determine the version bump: + +- Patch release (1.0.x -> 1.0.y) + - Updates to output formats (error messages, logs, ...). + - Performance improvements which doesn't affect behavior. + - Build process changes (e.g., updating dependencies, updating `Dockerfile`, ...). + - Reverts (reverting a previous commit). + - Bug fixes which result in **editorconfig-checker** reporting less linting errors (removing "false-positive" linting errors). +- Minor release (1.x.0 -> 1.y.0) + - Adding new [configuration options](#configuration), including new CLI flags. + - Adding new [path to exclude by default](#default-excludes). + - Adding new [output formats](#formats). + - Supporting a new [editorconfig](https://editorconfig.org/) property (e.g: `insert_final_newline`, `indent_size`, ...). + - Any new feature which doesn't break existing behavior. +- Major release (x.0.0 -> y.0.0) + - Removal of a [configuration](#configuration) option. + - Removal of an [output format](#formats). + - Removal of a [path to exclude by default](#default-excludes). + - Removal of support for an [editorconfig](https://editorconfig.org/) property. + - Bug fixes, which result in **editorconfig-checker** reporting more linting errors, because the previous behavior was incorrect according to the [editorconfig specification](https://editorconfig.org/). diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 68b5e28..7b2c102 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -2,6 +2,16 @@ display: none; } +figure { + margin: 0.5em; +} + +figcaption p { + margin-top: 0; + color: var(--color-toc-item-text); + font-size: 80%; +} + /* Authors */ .authors { border-top: 1px solid var(--color-brand-content); diff --git a/docs/architecture/OSTrails-architecture.png b/docs/architecture/OSTrails-architecture.png new file mode 100644 index 0000000..9d6aa86 Binary files /dev/null and b/docs/architecture/OSTrails-architecture.png differ diff --git a/docs/architecture/dmp_if.rst b/docs/architecture/dmp_if.rst new file mode 100644 index 0000000..813fa7d --- /dev/null +++ b/docs/architecture/dmp_if.rst @@ -0,0 +1,35 @@ +Architecture: DMP IF +==================== + +.. page-authors:: + Tomasz Miksa + +An **interoperability framework** refers to a set of guidelines, standards, and protocols that ensure the ability of different systems, applications, or organizations to work together effectively, exchanging data and functions seamlessly despite differences in their underlying technologies. The framework typically addresses the technical, semantic, and organizational aspects needed to facilitate collaboration and integration between disparate systems. + +The **DMP-IF** consists of: + * RDA DMP **common standard** for machine-actionable DMPs (DCS), + * OSTrails **application profile** for maDMPs, + * maDMP Application Programming Interface (**API**). + +The DMP-IF follows this definition and is designed with DMP Platforms in mind but can be used by any service or tool that exchanges maDMPs. The IF does not prescribe internal organisation of services, e.g. their architecture or how they represent information internally. The IF focuses on how the information is exchanged with other services, i.e. defines concepts and models to represent the information, as well as actions that can be performed to get or modify information in a service implementing the DMP-IF. For example, listing all datasets described by a DMP, including their identifiers and licences, is performed in a unified way, independent of the underlying implementation. The DMP-IF addresses the technical and semantic layers only. + +The **common standard** is an RDA recommendation. It defines a minimum set of concepts used to model information in DMPs common for most use cases. The **application profile** builds on top of the common standard. It provides additional concepts and constraints necessary to support the interactions identified in the pathways and reference architecture. Thus, it provides more concepts and more constraints that reflect the needs of OSTrails as whole and eventually EOSC. While both focus on establishing a common language on how information contained in DMPs is expressed in a machine-actionable way, the API provides a set of methods that can be used to perform specific actions on DMPs. The structure of messages exchanged with the use of the API is based on the common language defined by the common standard and the application profile. + +The DMP-IF is **relevant to software engineers and service operators** who want to standardise how information on DMPs is exchanged. End-users, i.e. researchers, are not supposed to be aware of the DMP-IF. The DMP-IF facilitates the reuse and exchange of information so that typical RDM tasks can be automated, and DMPs are a place where all the information relevant to data management, e.g. type of data, storage location, access permissions, etc., are kept. DMP platforms should thus become a source of up-to-date information for other services that depend on them, e.g. researchers involved in a project described by a DMP should automatically get access to relevant equipment and repositories described by the DMP. As a result, creating the DMP should primarily benefit researchers by facilitating data management of their typical tasks and become less a one-time exercise to meet formal requirements. + +**Adopting the DMP-IF** can be performed gradually and tailored to the needs of the specific use case. Yet, full interoperability can only be achieved when the specific service implements the complete maDMP API. This is because the API reflects the community agreement on the common language used to describe the DMP contents and makes technical decisions that leave less room for interpretation, e.g. choice of communication protocol, such as HTTP, and ways to serialise the exchanged messages, for instance, using JSON. + +Ongoing and future work +*********************** + +Together with the RDA DMP Common Standards WG we perform the maintenance of the recommendation. The RDA DMP Common Standards working group will be able to accept only minor and small changes to the recommendation. These will be mostly refinements bringing clarity or changes that are backward-compatible. As a result, we will have a stable and up-to-date set of concepts shared across the whole DMP community. Any major changes that could considerably influence the design of the recommendation need to be performed by a new working group – this is an RDA requirement. For this reason, OSTrails develops the OSTrails application profile to incorporate bigger changes that also cover the project-specific needs, which may not be shared across the whole RDA community. + +By defining one application profile, we want to mitigate a situation when every use case owner defines their own set of extensions. For example, we will define a set of concepts that support the requirements of most funders instead of having extensions per funder. This should prevent situations in which overlapping concepts are represented differently, and hence, the interoperability is lower. While the DCS is an official recommendation of RDA and must leave many decisions open, e.g., which type of controlled vocabulary to use for identifier types, the OSTrails application profile imposes additional constraints on the RDA recommendation that are relevant within the OSTrails and EOSC contexts. For example, the application profile may have stricter requirements regarding the use of persistent identifiers (rather than URLs) or may require the use of specific controlled vocabularies. + +The broader objectives of the maDMP API are as follows: + * Enable interoperability and interchangeability of DMP platforms: Ensure that any DMP tool can be utilised in diverse contexts without compatibility concerns. + * Reduce reliance on static text documents: Shift away from narrative DMP formats, such as PDFs, towards enhanced use of persistent identifiers where appropriate. + * Promote the reuse of information from DMPs: Facilitate the transfer of information from DMPs to inform and drive actions within other RDM systems. + * Enhance the quality and timeliness of DMPs: Improve accuracy by sourcing data directly from systems where RDM activities are conducted. + +This approach aims to establish a robust framework for seamless integration and automation in the RDM ecosystem, significantly advancing the utility and efficiency of DMPs. The maDMP API does not replace existing APIs offered by DMP Platforms. There are still operations that are specific to each platform. The maDMP API standardises typical interactions with maDMPs in a similar fashion as the DCS, which represents consensus on most common DMP elements in most settings, but not all of them. diff --git a/docs/architecture/fair-if.png b/docs/architecture/fair-if.png new file mode 100644 index 0000000..8c89c73 Binary files /dev/null and b/docs/architecture/fair-if.png differ diff --git a/docs/architecture/fair_if.rst b/docs/architecture/fair_if.rst new file mode 100644 index 0000000..2ea7d3f --- /dev/null +++ b/docs/architecture/fair_if.rst @@ -0,0 +1,53 @@ +Architecture: FAIR-IF +===================== + +.. page-authors:: + Daniel Garijo + +The FAIR Testing Interoperability Framework (FAIR-IF) uses, almost exclusively, existing standards or extensions of standards, such as W3C Data Quality Vocabulary (https://www.w3.org/TR/vocab-dqv/), the W3C Data Catalog vocabulary (https://www.w3.org/TR/vocab-dcat-3/) and the W3C Provenance Ontology (https://www.w3.org/TR/prov-o/). These are employed to build the descriptors for the components that make up the FAIR Testing Reference Model and are described here. While most of these components contribute only indirectly to the Interoperability behaviour of the FAIR-IF, a brief discussion of all of them will simplify understanding how Interoperability is achieved. + +FAIR Reference Model Conceptual Components +****************************************** + +Guided by the Compliance Assessment Toolkit :cite:`faircore4eosc_d2.2`, we have identified the set of distinct components that make up a FAIR testing environment. These, and the relationships between them, are diagrammed in Figure 1. These are categorised as Conceptual (shown in green), Software (blue), and Data (orange) levels. In addition, there is a higher level of Conceptual object we call a Dimension (red), which represents an established principle (e.g. FAIR Principle F1) that motivates the need for the creation of a FAIR test (or set of tests). + +.. figure:: fair-if.png + + FAIR Reference Model + + +Detailed definitions of these components are work in progress as we examine use-cases emerging from the participating Pilots, to ensure that the identified FAIRness Reference Model components are a) complete, and b) match the requirements of the FAIR-IF, and the overall expectations of the OSTrails IF. Briefly, here are the current definitions of the components. + +The three Conceptual-level components involved in the FAIR Reference Model are: + * Dimensions (using W3C Data Quality Vocabulary dqv:Dimension) - a high-level objective that should be met by digital objects corresponding to one of the FAIR Principles (e.g. R1.1. all digital objects should have a licence). + * Metrics: Narrative description that a Test must wholly implement + * Benchmarks: a narrative definition of how to interpret the Test Result Set resulting from the application of one or more Metrics to a digital object. + +The two Software-level components in the FAIR Reference Model are: + * Tests: A software object or defined manual workflow that examines some aspect of a digital object, and outputs a Test Result (i.e. pass/fail/indeterminate). + * Algorithms: A piece of code or defined manual workflow that implements a Benchmark. + +All these components (excluding Dimensions) have metadata descriptors following a formal model (see the FAIR Test Results formal specification https://w3id.org/ftr/). + +The two data-level components are: + * Test Result: The consequential output from a test. For the first iteration of the OSTrails FAIRness Reference Model, we will require that tests are very precise, and can have only “pass”, “fail”, or “indeterminate” as their possible outcomes. (This decision is subject to change based on experience with using the OSTrails IF). The output will include metadata (e.g. a progress log) that can be used to interpret the provenance behind the output. Aggregations of Test Results are referred to as “Test Result Sets” and have a defined structure. + * Assessment Outcome: The output from an Algorithm, representing the measurement of some Benchmark as a numeric or controlled vocabulary score. + +The final component in the diagram, shown in black in the Figure above, is another software component – the “FAIR Assessment Tool” – that will exist, but its interface and behaviour are defined as part of the OSTrails Implementation Framework rather than the FAIR Reference Model. + +To see the individual metadata descriptors of each of these components we refer the reader to the FAIR test results specification https://w3id.org/ftr/, which describes an OWL ontology, documentation and SHACL shapes to validate minimal test and metric metadata conformance. + +An overview of the resources implementing different aspects of our framework maybe found in the "resources section" (https://docs.ostrails.eu/en/update-restructure/commons/resources.html#). + +Additional information +********************** + +Check our deliverables for more information: + +.. bibliography:: + :list: bullet + :filter: False + :keyprefix: fair-if- + :labelprefix: fair-if- + + faircore4eosc_d2.2 diff --git a/docs/architecture/intro.rst b/docs/architecture/intro.rst new file mode 100644 index 0000000..be48eb3 --- /dev/null +++ b/docs/architecture/intro.rst @@ -0,0 +1,56 @@ +Architecture +============ + +.. page-authors:: + Tomasz Miksa + + +The OSTrails reference architecture :cite:`ostrails_d1.4` :cite:`ostrails_d2.5` provides guidance on realising interactions between key components identified in the OSTrails pathways :cite:`ostrails_d1.1`: Data Management Plans (DMPs), Scientific Knowledge Graphs (SKGs), and FAIR Assessment. It clarifies which interactions are standardised within the Interoperability Frameworks and which are relevant to the project without prescribing specific implementation methods. For example, while the reference architecture specifies when the DMP API (part of the DMP Interoperability Framework) must be used, it leaves the method of accessing information from data repositories flexible. + +A key objective of this architecture is to prevent vendor lock-in, ensuring tools and services can be used interchangeably in typical scenarios outlined by the pathways. For instance, any SKG conforming to the SKG-IF can seamlessly integrate with DMP tools to provide additional insights into reused datasets. This architecture emphasises harmonising the modelling and exchange of information across research data management services while allowing diverse implementation choices tailored to specific use cases. + +The architecture also supports both current well-known and potential future patterns of interactions between components, fostering innovative use cases that enhance automation and machine-actionability of digital object information exchange. For example, while it is yet uncommon for data repositories to update DMPs, the architecture anticipates and accommodates such potential pathways. + +.. figure:: OSTrails-architecture.png + + OSTrails Architecture + + +We use colour coding in the diagram: + * Orange represents the components and communications that are subject to standardisation within the DMP-IF. + * Blue represents the components and communications that are subject to standardisation within the SKG-IF. + * Green represents the components and communications that are subject to standardisation within the FAIR-IF. + * Gray represents the components and communications that are relevant for delivering the pathways identified by the project but are not subject to any of the interoperability frameworks, e.g. standards may already be in place, under development by other projects, or simply be based on custom interfaces provided by specific services. + +The reference architecture consists of the following conceptual components: + * DMP Platform – Platform, tool, or service (software system) for planning data management, producing data management plans (DMPs), including machine-actionable data management plans (maDMPs). + * SKG - For the purposes of the OSTrails project, an SKG is defined as any database/repository with information pertaining to research products, processes and actors & agents which can present a graph-type view of this information via a suitable API. + * FAIR Assessment Tool – Software that applies a set of FAIR Tests to the metadata/data of a digital object (such as datasets), presents the output as a FAIR Test Result Set, and provides assistance on how to interpret and improve the results. FAIR Assessment tools may also include additional functionalities such as searching for and/or authoring Metrics and searching for and/or authoring Benchmarks. + * DMP Evaluation Service - A service that takes a DMP as input and gives as a result measurements indicating if the DMP meets given compliance requirements. These requirements depend on the evaluation scenario but in general consist of measurements for subsets of information contained in a DMP. Such measurements can be the FAIRness of digital objects included in the DMP, compliance of the DMP with the RDA maDMP standard, or automated measurements of funder requirements such as the existence of relevant information and their allowed values. To provide these measurements, the DMP Evaluator coordinates the inclusion of the results of other evaluators and resolves information contained in a DMP through SKGs and other sources. + * Data Repository – any service that stores and provides access to data. Usually, it provides a means for persistent identification and ensures that data is accompanied by metadata. Examples include zenodo.org, institutional repositories, etc. + * Other SKG – same definition as for the SKG. This element is introduced in the reference architecture to indicate that the SKG-IF can be used for communication between different SKGs. + +The reference architecture says that a *DMP Platform* must provide a DMP API that can be used by other services. SKGs and data repositories use this API to interact with the DMP Platform. The specific operations of the API will be described elsewhere. For the time being, one can imagine that a data repository can use the DMP API to e.g. add information about a specific licence assigned to a dataset described by the DMP. + +The *SKGs* must provide an SKG API so that other SKGs can interact with them. DMP Platforms use SKG API to access information in SKGs, e.g. to search for datasets, or to fetch information using identifiers. DMP Evaluation Service and FAIR assessment tools use the SKG API to get additional information needed during assessment. Data repositories also use this API. + +*FAIR Assessment Tools* have APIs that are only partially defined by the OSTrails reference architecture; that is, while the input required by a FAIR assessment tool cannot be predicted, the output structures from all FAIR assessment tools (namely, the “FAIR Test Result Set” data structure) have been specified by the FAIR Reference Architecture (Deliverable D1.2). Further discussion regarding this appears in the chapter 5 of this document. DMP Platforms, DMP Evaluation Services, and SKGs can thus expect a standardised response when interacting with FAIR assessment tools that comply with the FAIR-IF. + +The *DMP Evaluation Service* provides an interface that the DMP Platform uses to interact with it, i.e. send maDMPs for evaluation and fetch the results. This interface will be designed as part of the DMP Evaluation Service and described in a separate deliverable. Yet, it will be specific to this service and does not belong to any of the interoperability frameworks, i.e. in case other similar services exist, they can define their own interfaces. + +In a similar way, *Data Repositories* may have custom APIs that are used by FAIR Assessment tools or DMP Platforms. OSTrails does not attempt to standardise this communication because it is already a subject of the work by the EOSC Future project on standardising access to content via PID. + +Additional information +********************** + +Check our deliverables for more information: + +.. bibliography:: + :list: bullet + :filter: False + :keyprefix: architecture-intro- + :labelprefix: architecture-intro- + + ostrails_d1.4 + ostrails_d2.5 + ostrails_d1.1 diff --git a/docs/architecture/skg_if.rst b/docs/architecture/skg_if.rst new file mode 100644 index 0000000..a230c1f --- /dev/null +++ b/docs/architecture/skg_if.rst @@ -0,0 +1,18 @@ +Architecture: SKG IF +==================== + +.. page-authors:: + Tomasz Miksa + + +This page introduces the Scientific/Scholarly Knowledge Graph Interoperability Framework (SKG-IF). It outlines its motivation, relation to key elements, and applications in OSTrails. + +The `SKG-IF data model `_ is designed to enhance interoperability among different knowledge graph systems and platforms used in research. It facilitates the exchange and use of data across these systems by defining a shared language and standardised operations. Researchers or end-users are not expected to interact directly with the SKG-IF. Instead, it enables automated workflows and interoperability between services, enhancing the research ecosystem's efficiency and machine-actionability. + +OSTrails SKG-IF is based on the RDA SKG interoperability framework. By providing a standardised approach to modelling a core set of scholarly data, the SKG-IF supports diverse applications involving compatible SKGs, such as combining SKGs to build new ones or exchanging data between SKGs to benefit from each other's construction methods. OSTrails will extend the existing RDA model of SKGs, propose (a mechanism for) model extensions and an API that can be used to enable scientific discovery and assessment. The OSTrails project will do so in the context of, or in close collaboration with, the RDA SKG-IF WG adding a scientific perspective to the previous scholarly one. + +More specifically, SKG-IF data model entities are currently described with a comprehensive set of metadata properties, initially agreed on by the existing SKG community of stakeholders (DataCite, OpenCitation, Crossref, OpenAlex, OpenAIRE Graph), inspired also by existing metadata standards or best practices such as EuroCRIS/CERIF and now the perspective of the scientific communities. The model is agnostic of specific PID schemes or vocabularies, enabling cross-SKG interoperability by agreeing on a common structure and sharing of specific semantics. When PIDs or vocabularies are requested (e.g. resource types), properties require the vocabulary name and the specific value. Finally, the IF adopts JSON-LD, a widely recognised data exchange standard, to ensure seamless data exchange and semantic interoperability. + +The work on SKG-IF is performed in the context of RDA, guaranteeing a broad set of stakeholders taking part in the decision making. OSTrails brings to the Working Group the requirements arising by scientific communities and service providers in achieving the project objectives. The project roadmap may, therefore, potentially not always be synced and aligned with the RDA WG’s. To this aim, as described below, in its first year OSTrails has co-designed and strongly contributed to the definition of SKG-IF extensions. Extensions are a mechanism allowing a community to define “customizations” of the SKG-IF core model, such as new entities, new properties of existing entities, or new relationships. Extensions, today part of the SKG-IF framework, can compensate the difference in rhythm, when manifesting, between an RDA WG and project objectives, which are driven by deadlines and deliverables. Starting from interoperability use-cases identified in the project, OSTrails partners have identified (i) which entities of the SKG data model can be adopted to meet their requirements and, when such entities are missing, (ii) the SKG extensions required to fulfil them. + +For more information please refer to: Miksa, T., Wilkinson, M., Manghi, P., & Suchánek, M. (2025). **D1.4 OSTrails Interoperability Reference Architecture V1**. Zenodo. https://doi.org/10.5281/zenodo.14795000 diff --git a/docs/commons/commons-components.png b/docs/commons/commons-components.png new file mode 100644 index 0000000..b52f06e Binary files /dev/null and b/docs/commons/commons-components.png differ diff --git a/docs/commons/commons-layers.png b/docs/commons/commons-layers.png new file mode 100644 index 0000000..35a1476 Binary files /dev/null and b/docs/commons/commons-layers.png differ diff --git a/docs/commons/governance.rst b/docs/commons/governance.rst new file mode 100644 index 0000000..fb5167a --- /dev/null +++ b/docs/commons/governance.rst @@ -0,0 +1,58 @@ +OSTrails Commons: Governance +============================ + +.. page-authors:: + Marek Suchánek + + +The OSTrails Commons is a structured collection of open, reusable specifications designed to facilitate interoperability within the OSTrails ecosystem. Its governance ensures sustainable management, adoption, and evolution. The governance framework incorporates structured leadership, participation policies, and sustainability strategies aligned with global best practices, including the Global Open Research Commons (GORC). Please note, that this is **early-stage** governance structure for OSTrails Commons and it may change as the Commons are being materialised over the course of the project. + +.. _commons-structure: + +Commons Components and Layers +----------------------------- + +The Commons is organised into five components, ensuring comprehensive coverage of all included resources. Every resource, whether directly supporting interoperability or serving as foundational infrastructure, is categorised within this structure. This framework encompasses the core Plan-Track-Access framework-related elements, supporting tools, and essential management resources to maintain and evolve the Commons effectively. + +.. figure:: commons-components.png + :scale: 60% + + Components of OSTrails Commons + +Furthermore, the Commons is organised into a layered structure that complements the core components (DMP, SKG, FAIR) and supporting tools. This approach ensures a systematic, modular framework where resources are categorised not only by their functional area but also by the type of technical or conceptual contribution they make. The layering enables consistency across components, promotes reusability, and supports the alignment of tools with the Interoperability Framework. + +Each layer reflects a distinct aspect of resource organisation, whether it involves APIs for tool integration, data models for structured information exchange, or compliance mechanisms for evaluating adherence to the framework. This structure is designed to D2.5 OSTrails Commons Specification remain extensible, allowing new layers to be introduced as needs evolve, especially in response to extensions or updates in the Interoperability Framework. Unlike the introduction of new components, which are tied to the PTA framework and thus less likely, additional layers may be necessary to address emerging interoperability requirements or technological advancements. + +.. figure:: commons-layers.png + :scale: 60% + + Layers and Components of OSTrails Commons + + +Governance Structure +-------------------- + +OSTrails Commons is managed through a federated governance model, ensuring adaptability and inclusivity. The governance structure consists of: + +- **Group of Maintainers**: Responsible for specific parts of the Commons, ensuring technical consistency, version control, and interoperability standards across components (DMP, SKG, FAIR). +- **Resource Representatives**: Responsible for specific resource(s) that are part of the Commons, maintaining its record up-to-date and the resource aligned with the Commons and OSTrails Interoperability Framework. +- **Community Contributors**: Researchers, developers, and stakeholders who provide feedback, propose enhancements, and contribute to resource maintenance. + +Maintenance and Evolution +------------------------- + +The Commons evolves through structured updates and community contributions. Maintenance follows these principles: + +- **Versioning Policy**: Updates follow semantic versioning, ensuring compatibility and traceability. +- **Compliance Monitoring**: Resources are periodically assessed against interoperability standards (EOSC, GORC). +- **Feedback Mechanism**: Contributions and issues are managed via GitHub discussions and issue tracking. +- **Deprecation & Archival**: Outdated resources are phased out following transparent guidelines to maintain usability and relevance. + +GORC Alignment +-------------- + +As part of the OSTrails Commons Specification, the Global Open Research Commons (GORC) International Model has been utilized, ensuring: + +- **Sustainability**: Long-term stewardship of resources and metadata. +- **Interoperability**: Adherence to global data exchange and research infrastructure standards. +- **Transparency & Engagement**: Open decision-making processes, public documentation, and structured community involvement. diff --git a/docs/commons/intro.rst b/docs/commons/intro.rst new file mode 100644 index 0000000..d77eda3 --- /dev/null +++ b/docs/commons/intro.rst @@ -0,0 +1,27 @@ +OSTrails Commons +================ + +.. page-authors:: + Mark Wilkinson + Marek Suchánek + + +The **OSTrails Commons** :cite:`ostrails_d2.5` (referred to also as ‘the Commons’ hereafter) is formally defined as a **collection of open, reusable, and adaptable resources that collectively enable and enhance interoperability** within the OSTrails ecosystem and beyond. These resources are designed to lower adoption barriers to integration by standardising interactions between tools, ensuring alignment with the OSTrails Interoperability Framework (IF) and Reference Architecture (RA) :cite:`ostrails_d1.4`. The Commons is not standalone tools or services; rather, they provide the foundational elements that support and guide the development, operation, and evolution of interoperable research-supporting platforms. By bridging technical, semantic, and procedural gaps, the Commons facilitate collaboration and scalability while remaining flexible for adaptation to emerging technologies and diverse research contexts. + +The Commons is **built through iterative cycles**, where specifications will evolve (either individually or in synchrony with other components of The Commons) to **incorporate feedback from tool developers and other stakeholders**. This iterative approach ensures that the Commons remains practical and adaptable. For this reason, entities in the commons are carefully versioned, and versioned releases are generated as required to ensure that the tools work together. + +The Commons is **guided by the Plan-Track-Assess Pathways defined by OSTrails**, which provides a map of how tools interact to facilitate research workflows. The pathways flow through three primary Interoperability Frameworks (IF): the SKG-IF, the DMP-IF, and the FAIR-IF. As such, this living repository is similarly split into three chapters with the same names, containing the detailed record of the members of that sub-set of Commons artefacts. + +Additional information +********************** + +Check our deliverables for more information: + +.. bibliography:: + :list: bullet + :filter: False + :keyprefix: commons-intro- + :labelprefix: commons-intro- + + ostrails_d2.5 + ostrails_d1.4 diff --git a/docs/commons/resources.rst b/docs/commons/resources.rst new file mode 100644 index 0000000..dfa09aa --- /dev/null +++ b/docs/commons/resources.rst @@ -0,0 +1,147 @@ +OSTrails Commons: Resources +=========================== + +.. page-authors:: + Daniel Garijo + Marek Suchánek + Allyson Lister + + +This page embodies the OSTrails Commons, a collection of reusable resource according to its structure as :ref:`components `. + +DMP Commons +----------- + +The following resources in this section are part of the DMP Commons component. + +OSTrails Application Profile for maDMPs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +OSTrails Application Profile (AP) as a tailored extension of the `RDA DMP Common Standard (DCS) for maDMPs `_ will be designed to enhance interoperability while addressing various requirements (e.g. funders). Technically, the specification of the application profile will be done as prescribed by the DCS (which will support such extensions) and will be part of the Commons as the description of data structure. + +- *Planned resource to be developed* + + +OSTrails maDMP API Specification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +maDMP API Specification will build on top of the DSC and OSTrails AP and specify the operations and data exchange. We plan to materialize this in the form of OpenAPI specification (using the current version, currently v3.1.1. Again, this promotes adoption as OpenAPI specification not only documents the API but also provides a way to generate source code or other artifacts (e.g. tests) as well as check compliance. + +- *Planned resource to be developed* + + +SKG Commons +----------- + +The following resources in this section are part of the SKG Commons component. + +OSTrails SKG IF +^^^^^^^^^^^^^^^ + +OSTrails SGK-IF as an extension of the `RDA SKG-IF `_ will focus on Common Standard and Data Model extensions, resulting in a specification for data structures guiding the adoption. + +- *Planned resource to be developed* + + +OSTrails SKG-IF Common API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SKG-IF Common API will be a specification of API following identified use cases and supporting relevant operators to guide the adoption and eventually also check compliance. + +- *Planned resource to be developed* + + +FAIR Commons +------------ + +The following resources in this section are part of the FAIR Commons component. + +FAIR Assessment specifications and SHACL shapes (FTR) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +FTR is the first OWL implementation of the FAIR Reference model described in Deliverables D1.2 and D.1.4. The reference model extends W3C standards such as DCAT (https://www.w3.org/TR/vocab-dcat-3/), DQV (https://www.w3.org/TR/vocab-dqv/) and PROV (https://www.w3.org/TR/prov-o/) to describe test results, test definitions, metrics, benchmarks, algorithms, dimensions/principles and their interpretation to generate a FAIR assessment score. + +The code release includes the vocabularies, definitions, specifications in machine-readable format and a set of SHACL validation rules to ensure tests and metrics are defined according to the specification. + +- Persistent identifier: https://w3id.org/ftr/1.0.0 +- Code Repository: https://github.com/OSTrails/FAIR_assessment_output_specification/ +- Version: 1.0.0 +- Release (in GitHub): https://github.com/OSTrails/FAIR_assessment_output_specification/releases/tag/v1.0.0 +- License: CC-BY 4.0 + + +FAIR Champion +^^^^^^^^^^^^^ + +FAIR Champion is a general-purpose FAIR assessment tool intended to be used by all communities and for all digital objects. In this release, FAIR Champion is aware of the 22 FAIR Tests (below), but any test, from any provider, can be registered so long as the test generates a metadata descriptor compliant with the FAIR Reference Model defined by OSTrails. The OpenAPI interface descriptor for this release is only partially complete; the Champion has a variety of functions related to new test registration and benchmark registration that are currently pending decisions by the OSTrails project. + +- Persistent identifier: https://tools.ostrails.eu/champion/sets/ +- Code repository: https://github.com/OSTrails/FAIR-Champion +- Version: Release v1 +- Release: https://github.com/OSTrails/FAIR-Champion/releases/tag/1.0.0 +- License: MIT + + +FAIR Champion Tests +^^^^^^^^^^^^^^^^^^^ + +A set of 22 tests for FAIRness. These are generic tests for all four FAIR facets – F, A, I, R – and do not represent any specific community or digital object. All tests require the GUID of the digital object’s metadata as input. Output follows the FAIR Test Results schema (https://w3id.org/ftr/1.0.0). + +- Persistent identifier: https://tests.ostrails.eu/tests +- Code repository: https://github.com/OSTrails/FAIR-Core-Tests +- Version: Release v1 +- Release: https://github.com/OSTrails/FAIR-Core-Tests/releases/tag/1.0.0 +- License: MIT + + +FOOPS! Test and metric catalogue +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Ontology Pitfall Scanner for FAIR is a FAIR assessment tool for vocabularies and ontologies. In this release, FOOPS! has been adapted to comply with the FTR specification. A catalog of test descriptions has been made available in https://w3id.org/foops/catalogue. The release contains the source code of the tools, as well as the machine-readable and human-readable documentation of all tests, metrics and benchmarks associated with the tool. + +- Persistent identifier: https://w3id.org/foops/catalogue +- Zenodo link (latest release): https://doi.org/10.5281/zenodo.14767999 +- Code repository: https://github.com/oeg-upm/fair_ontologies +- Version: 0.2.0 +- Release: https://github.com/oeg-upm/fair_ontologies/releases/tag/v0.2.0 +- License: Apache-2.0 + + +FAIR Data Point +^^^^^^^^^^^^^^^ + +The FAIR Data Point software is maintained by a third party (the “FAIRDataTeam”). In OSTrails we utilize the FAIR Data Point (FDP) in its configuration as an “index”, using the 16.x releases of the software suite in DockerHub. FDP Index is the first implementation of a test registry and will include many of the descriptions from the FAIR Champion and FOOPS! + +- Identifier: https://tools.ostrails.eu/fdp-index/ +- Code repository: https://github.com/FAIRDataTeam +- Version: Docker Image version 16.x +- Release: N/A +- License: MIT + + +FAIR Data Point Index Proxy +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An early prototype of a “proxy” service that allows native DCAT records to be registered in a FAIR Data Point Index. + +- Identifier: https://tools.ostrails.eu/fdp-index-proxy +- Zenodo link (latest release) +- Code repository: https://github.com/OSTrails/FDP-Index-Proxy +- Version: Release v1.0.0 +- Release: https://github.com/OSTrails/FDP-Index-Proxy/releases/tag/v1.0.0 +- License: MIT + + +FAIRsharing Registry +^^^^^^^^^^^^^^^^^^^^ + +FAIRsharing is a registry of standards, databases, policies and FAIR assistance conceptual components. Registration of FAIR principles/dimensions, metrics, and benchmarks within FAIRsharing allows human- and machine-readable integration of the FAIR assessment components within the wider research landscape, and is key to discovery of these resources as well as for the implementation of the tests themselves via the rich metadata contained within the registry. Rather than being a specific tool release, it is the extension to FAIRsharing with the new FAIRassist registry which is relevant to the other Commons resources described in this section. + +- Identifier: https://fairsharing.org/ +- Code repository: https://github.com/FAIRsharing/fairsharing.github.io +- Version: Continuous release + +Cross-Cutting and Supporting Resources +-------------------------------------- + +*(No resources yet in this component.)* diff --git a/docs/conf.py b/docs/conf.py index b58427b..b0738bf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,7 +62,7 @@ 'sidebar-item-spacing-horizontal': '.75rem', }, 'sidebar_hide_name': True, - 'top_of_page_button': None, + 'top_of_page_buttons': [], } html_css_files = ['custom.css'] html_js_files = ['custom.js'] diff --git a/docs/index.rst b/docs/index.rst index 81fe531..92ff83e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,25 @@ Documentation Structure *This documentation is currently under development...* +.. toctree:: + :maxdepth: 2 + :caption: Architecture + + Introduction + DMP IF + SKG IF + FAIR IF + + +.. toctree:: + :maxdepth: 2 + :caption: Commons + + Introduction + Governance + Resources + + .. toctree:: :maxdepth: 2 :caption: Other diff --git a/docs/other/contributing.rst b/docs/other/contributing.rst index 56faa5a..fa74f59 100644 --- a/docs/other/contributing.rst +++ b/docs/other/contributing.rst @@ -1,4 +1,116 @@ Contributing Guidelines ======================= -*To be specified* +.. page-authors:: + Marek Suchánek + John Shepherdson + + +Thank you for considering contributing to the OSTrails documentation! We welcome contributions from everyone, regardless of your level of experience. This document outlines the process for contributing to the documentation. + +Ways of Contributing +-------------------- + +- **Reporting Issues**: If you find a bug in the documentation, please open an issue on the GitHub repository. +- **Suggesting Enhancements**: If you have an idea for improving the documentation, please open an issue on the GitHub repository. +- **Improving the Documentation**: If you would like to improve the documentation, please follow the process outlined below. + +Issue Reporting +--------------- + +If you find a bug in the documentation, please `open an issue `_ in the GitHub repository. When reporting an issue, please follow the requested information for given issue templates. + +Documentation +------------- + +The documentation is hosted on Read-the-Docs and using standard Sphinx documentation. The documentation is written in reStructuredText (``.rst``) format. It can be compiled locally using Sphinx and viewed in a web browser. + +Writing Style +^^^^^^^^^^^^^ + +When contributing to the documentation, please follow the following writing style: + +- Use British English. +- Use the active voice. +- Use the present tense. +- Use the imperative mood for commands. + +For more information on ReStructuredText syntax, please refer to the `official documentation `_. In this documentation, we use ``=`` underline for headings, ``-`` underline for subheadings, and ``^`` underline for subsubheadings. + +We also use the following extensions: + +- ``sphinxcontrib.bibtex`` for managing bibliographies (see `sphinxcontrib.bibtex docs `_) +- ``sphinxcontrib.openapi`` for rendering OpenAPI specifications (see `sphinxcontrib.openapi docs `_) + +All bibliographical references should be added to the ``references.bib`` file in the ``docs`` directory. A record need to contain all required fields according to the `BibTeX format `_. + +The code style is captured using `EditorConfig `_, see ``.editorconfig`` file. Please ensure that your editor supports EditorConfig. It is also checked using CI together with the absence of warnings. + +Building the Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, install the required dependencies (preferably in a virtual environment): + +.. code-block:: bash + + python -m venv venv + source venv/bin/activate + + pip install -r requirements.txt + + +Then, you can build the documentation using the following command: + +.. code-block:: bash + + cd docs + make html + + +Once built, you can view the documentation by opening the ``index.html`` file in the ``_build/html`` directory in a web browser. + +Way of Working +-------------- + +The following part describes the way of working when contributing to the documentation. Always also comply to the ``CODE_OF_CONDUCT.md`` when contributing (based on `Contributor Covenant `_). + +Commit Messages +^^^^^^^^^^^^^^^ + +Please follow the `Conventional Commits `_ specification when writing commit messages. This will help us to automatically generate the changelog. + +For instance, the following commit message: + +.. code-block:: none + + feat: add new extension to the documentation + docs: update framework general description + deps: update dependencies + fix: correct typos + + +Branching and Pull Requests +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When contributing to the documentation, please follow these steps: + +1. Fork the repository (if not in the OSTrails organisation). +2. Create a new branch for your changes (base = `next``). +3. Make your changes and commit them. +4. Push your changes. +5. Open a pull request to the ``next`` branch of the main repository. + +Crediting Contributors +^^^^^^^^^^^^^^^^^^^^^^ + +We will credit all contributors in the documentation. If you would like to be credited, please add your name and related information to the ``CONTRIBUTORS.yml`` file. + +Then, you can add your name to the list of contributors for a specific page under the first heading of the page. For example: + +.. code-block:: rst + + Page Title + ========== + + .. page-authors:: + Jane Smith diff --git a/docs/other/resources.rst b/docs/other/resources.rst index d2a63cc..d6273bc 100644 --- a/docs/other/resources.rst +++ b/docs/other/resources.rst @@ -3,4 +3,4 @@ Resources .. bibliography:: :all: - :list: enumerated + :style: plain diff --git a/docs/references.bib b/docs/references.bib index e69de29..05db23b 100644 --- a/docs/references.bib +++ b/docs/references.bib @@ -0,0 +1,57 @@ +@misc{faircore4eosc_d2.2, + author = {Hugo, Wim and + Steinhoff, Wilko and + Lieshout, Natascha and + Buys, Matthew and + Zamani, Themis and + van Rijsselberg, Fjodor and + Märkälä, Anu}, + title = {D2.2 – Compliance Assessment Toolkit}, + month = jul, + year = 2024, + publisher = {Zenodo}, + doi = {10.5281/zenodo.12683218}, +} + +@misc{ostrails_d1.1, + author = {Reichmann, Stefan and + Rey Mazón, Miguel and + Hasani-Mavriqi, Ilire and + Thaci, Laura and + Eckhard, David}, + title = {D1.1: Plan-Track-Assess Pathways}, + month = jul, + year = 2024, + publisher = {Zenodo}, + doi = {10.5281/zenodo.13145788}, +} + +@misc{ostrails_d1.4, + author = {Miksa, Tomasz and + Wilkinson, Mark and + Manghi, Paolo and + Suchánek, Marek}, + title = {D1.4 OSTrails Interoperability Reference Architecture V1}, + month = jan, + year = 2025, + publisher = {Zenodo}, + doi = {10.5281/zenodo.14795000}, +} + +@misc{ostrails_d2.5, + author = {Suchánek, Marek and + Martínková, Jana and + Shepherdson, John and + Miksa, Tomasz and + Jirka, Jakub and + Knaisl, Vojtěch and + Moilanen, Katja and + Sansone, Susanna-Assunta and + Stavropoulos, Tassos}, + title = {D2.5 OSTrails Commons Specifications}, + month = jan, + year = 2025, + publisher = {Zenodo}, + doi = {10.5281/zenodo.14795060}, +} + diff --git a/requirements.txt b/requirements.txt index 2a8c72f..0b56f96 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,43 +1,45 @@ -alabaster==0.7.16 -attrs==23.2.0 -Babel==2.14.0 -beautifulsoup4==4.12.3 -certifi==2024.2.2 -charset-normalizer==3.3.2 -deepmerge==1.1.1 -docutils==0.21.1 -furo==2024.1.29 -idna==3.7 +alabaster==1.0.0 +attrs==25.1.0 +babel==2.17.0 +beautifulsoup4==4.13.3 +certifi==2025.1.31 +charset-normalizer==3.4.1 +deepmerge==2.0 +docutils==0.21.2 +furo==2024.8.6 +idna==3.10 imagesize==1.4.1 -Jinja2==3.1.3 -jsonschema==4.21.1 -jsonschema-specifications==2023.12.1 +Jinja2==3.1.5 +jsonschema==4.23.0 +jsonschema-specifications==2024.10.1 latexcodec==3.0.0 -MarkupSafe==2.1.5 -mistune==2.0.5 -packaging==24.0 +MarkupSafe==3.0.2 +mistune==3.1.1 +packaging==24.2 picobox==4.0.0 pybtex==0.24.0 pybtex-docutils==1.0.3 -Pygments==2.17.2 -PyYAML==6.0.1 -referencing==0.34.0 -requests==2.31.0 -rpds-py==0.18.0 -six==1.16.0 +Pygments==2.19.1 +PyYAML==6.0.2 +referencing==0.36.2 +requests==2.32.3 +rpds-py==0.22.3 +setuptools==75.8.0 +six==1.17.0 snowballstemmer==2.2.0 -soupsieve==2.5 -Sphinx==7.3.7 +soupsieve==2.6 +Sphinx==8.1.3 sphinx-basic-ng==1.0.0b2 sphinx-copybutton==0.5.2 -sphinx_mdinclude==0.5.4 -sphinxcontrib-applehelp==1.0.8 -sphinxcontrib-bibtex==2.6.2 -sphinxcontrib-devhelp==1.0.6 -sphinxcontrib-htmlhelp==2.0.5 +sphinx_mdinclude==0.6.2 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-bibtex==2.6.3 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 sphinxcontrib-httpdomain==1.8.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-openapi==0.8.4 -sphinxcontrib-qthelp==1.0.7 -sphinxcontrib-serializinghtml==1.1.10 -urllib3==2.2.1 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +typing_extensions==4.12.2 +urllib3==2.3.0