diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..544e06cd4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: FDP Documentation + url: https://fairdatapoint.readthedocs.io/ + about: Please check FDP Documentation before reporting an issue, especially if you have an issue with your custom deployment. + - name: FDP Specification + url: https://specs.fairdatapoint.org/ + about: Please check FDP Specification first, if you have any question related to the architecture or how things work in FDP. + - name: FDP Specification Issues + url: https://github.com/fdp-specs/fdp-specs.github.io/issues + about: Please create new issues related to FDP Specification in its dedicated GitHub repository. diff --git a/.github/dependabot.yml b/.github/dependabot.yml index e06776de9..6fb1a918e 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,17 +1,29 @@ +# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference version: 2 updates: - package-ecosystem: "maven" + # Look for `requirements.*` files in the `root` directory directory: "/" + # Check the registry for updates every week schedule: - interval: "daily" - target-branch: "develop" + interval: "weekly" + # Add labels to generated PRs labels: - "dependencies" + # Group minor updates and patch updates, except for spring-boot-starter-parent updates, + # and create separate PRs for updates that do not match any grouping rule. + groups: + minor-or-patch: + applies-to: version-updates + update-types: + - "minor" + - "patch" + exclude-patterns: + - "*spring-boot-starter-parent*" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" - target-branch: "develop" labels: - "dependencies" diff --git a/.github/workflows/code-style.yml b/.github/workflows/code-style.yml index 4b1ff082d..fdd5a0409 100644 --- a/.github/workflows/code-style.yml +++ b/.github/workflows/code-style.yml @@ -3,7 +3,7 @@ name: "Code Style" on: push: branches: - - develop + - master pull_request: concurrency: diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 92b05fe3b..0fdd9104b 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -3,7 +3,7 @@ name: Publish to Docker Hub on: push: branches: - - develop + - master pull_request: paths-ignore: - "**.cff" diff --git a/.github/workflows/maven-verify.yml b/.github/workflows/maven-verify.yml index 98633b76f..1e508c657 100644 --- a/.github/workflows/maven-verify.yml +++ b/.github/workflows/maven-verify.yml @@ -5,7 +5,7 @@ name: Maven verify on: push: branches: - - develop + - master - "support/**" pull_request: paths-ignore: diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index a9fa6cc24..842a71dcd 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -3,7 +3,7 @@ name: "Security Audit" on: push: branches: - - develop + - master pull_request: schedule: - cron: '23 4 * * 1' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 86869f2a8..8fceec6b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,52 +1,72 @@ # Contributing -When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other -method with the owners of this repository before making a change. +Before contributing to this repository, please discuss the intended change with the repository owners. +This can be done via [issues], [discussions], email, or any other available method. Please note we have a code of conduct, please follow it in all your interactions with the project. -## Pull Request Process - -1. Ensure any unnecessary install or build dependencies and other files are removed before the end of the layer when - doing a build. -2. Explain the changes and update the README.md file and other documentation if necessary. -3. Be ready to communicate about the Pull Request and make changes if required by reviewers. -4. The Pull Request may be merged once it passes the review and automatic checks. - -## Gitflow Workflow - -We use the standard [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow): - -* __master__ branch is used only for releases (and eventually hotfixes), this branch is also protected on GitHub (pull - requests with review and all checks must pass) -* __develop__ branch is used for development and as a base for following development branches of features, support - stuff, and as a base for releases -* __feature/*__ (base develop, rebase-merged back to develop when done) -* __chore/*__ (like the feature but semantically different, not the feature but some chore, e.g., cleanup or update of - Dockerfile) -* __fix/*__ (like the feature but semantically different, not something new but fix of a non-critical bug) -* __release/*__ (base develop, merged to master and develop when ready for release+tag) -* __hotfix/*__ (base master, merged to master and develop) - -Please note, that for tasks from [our Jira](https://dtl-fair.atlassian.net/projects/FDP/issues), we use such -as `[FDP-XX]` identifying the project and task number. - -## Release Management - -For the release management we use (aside from -the [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)): - -* [Semantic versioning](https://semver.org) -* Release Candidates - X.Y.Z-rc.N should be created if don’t expect any problems (in that case use alpha or beta), and - make a walkthrough to verify its functionality according to the manuals finally - it also verifies that the - documentation is up to date with the new version. -* [CHANGELOG.md](https://keepachangelog.com/en/1.0.0/ ) -* GitHub releases and tags - make the release using GitHub (or hub extension), CI will automatically upload ZIP and TGZ - distribution files there - better verify. -* Docker Hub image - in case of release, Docker image with the same tag will be created automatically. -* The matching version of [FDP](https://github.com/FAIRDataTeam/FAIRDataPoint) - , [FDP-Client](https://github.com/FAIRDataTeam/FAIRDataPoint-client), - and [OpenRefine extension](https://github.com/FAIRDataTeam/OpenRefine-metadata-extension) must be always compatible. - -Also, never forget to update the -joint [FAIR Data Point documentation](https://github.com/FAIRDataTeam/FAIRDataPoint-Docs)! +>[!IMPORTANT] +>Code generated using any form of AI, LLM, or similar tools, ***MUST*** be clearly labeled as such in the PR. + +## Version control workflow + +Our version control workflow is pragmatic, aiming to minimize overhead for a small team. +It resembles [github flow] with some aspects of [git flow] and [trunk-based development], but does not really fit well in any of those boxes. + +- We have a single `master` branch which is supposed to remain stable. +- For every *significant* change, we create a new short-lived branch from `master`. +- We immediately create a pull request (PR) for the new short-lived branch. +- We push often, at least once a day. + This allows us to keep track of work in progress and provide guidance before things get off track. +- After merging back into `master`, the short-lived branch is deleted. +- Rebasing and force pushing the *short-lived* branch is allowed only *if* the corresponding PR does not have any comments yet. + This ensures the comments remain in context. +- Releases are created directly from the `master` branch. +- Only the latest major release is supported. + +Note that there is still a `develop` branch, but that is legacy. + +## Pull requests are used for significant changes + +All significant contributions should be added via [pull requests] (PRs). +This allows us to discuss and review the changes, and document design choices. +Very minor changes, like fixing a typo in the readme or a comment, can sometimes be pushed directly onto master. + +Pull request titles must be *concise* and *descriptive*. +This enables auto-generation of meaningful change logs during the release process. + +## Pull requests must be focused + +Individual PRs *must* have a strong focus which is clear from the title. +When writing the title, remember that it is the only thing users will see in the change log. +PRs should also have a clear description and rationale, and should be linked to relevant issues, if any. + +If a PR gets very large, split it up into smaller PRs that can be reviewed separately. + +## Merge method is chosen depending on content + +Depending on the size and type of PR, different [merge methods] can be applied. +We prefer a squash merge for small PRs, resulting in a single commit. +However, in some cases, it may be useful to keep the individual commits from the PR. +In that case we use a merge commit (as in `--no-ff`). + +## External dependencies are minimized + +To reduce the maintenance burden, we aim to minimize the number of external dependencies. +If external dependencies cannot be avoided, we prefer well-supported projects with large numbers of contributors. + +## Semantic versioning applies to the API + +Release versions are based on [semantic versioning], i.e. `major.minor.patch`. +However, the semantic versioning rules for `major` changes are only applied to changes in the HTTP API. +For example, breaking changes in application *configuration* may occur in `minor` versions, as long as these changes are not reflected in the HTTP API. + +[discussions]: https://github.com/FAIRDataTeam/FAIRDataPoint/discussions +[git flow]: https://nvie.com/posts/a-successful-git-branching-model/ +[github flow]: https://githubflow.github.io/ +[issues]: https://github.com/FAIRDataTeam/FAIRDataPoint/issues +[merge methods]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github +[pull requests]: https://github.com/FAIRDataTeam/FAIRDataPoint-client-redux/pulls +[releases]: https://github.com/FAIRDataTeam/FAIRDataPoint/releases +[semantic versioning]: https://semver.org +[trunk-based development]: https://trunkbaseddevelopment.com/ diff --git a/README.md b/README.md index f4393b053..9e3e960bf 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,49 @@ # FAIR Data Point [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/FAIRDataTeam/FAIRDataPoint?sort=semver)](https://github.com/FAIRDataTeam/FAIRDataPoint/releases) -[![Documentation Status](https://readthedocs.org/projects/fairdatapoint/badge/?version=latest)](https://fairdatapoint.readthedocs.io/en/latest/?badge=latest) +[![Libraries.io](https://img.shields.io/librariesio/github/FAIRDataTeam/FAIRDataPoint)](https://libraries.io/github/FAIRDataTeam/FAIRDataPoint) [![License](https://img.shields.io/github/license/FAIRDataTeam/FAIRDataPoint)](https://github.com/FAIRDataTeam/FAIRDataPoint/blob/develop/LICENSE) [![Docker Pulls](https://img.shields.io/docker/pulls/fairdata/fairdatapoint)](https://hub.docker.com/r/fairdata/fairdatapoint) -[![Libraries.io](https://img.shields.io/librariesio/github/FAIRDataTeam/FAIRDataPoint)](https://libraries.io/github/FAIRDataTeam/FAIRDataPoint) +[![Documentation Status](https://readthedocs.org/projects/fairdatapoint/badge/?version=latest)](https://fairdatapoint.readthedocs.io/en/latest/?badge=latest) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19236251.svg)](https://doi.org/10.5281/zenodo.19236251) -[**FAIR Data Point** (FDP)](https://www.fairdatapoint.org) is a REST API for creating, storing, and serving **FAIR -metadata**. This FDP implementation also presents a Web-based graphical user interface (GUI). The metadata contents are -generated **semi-automatically** according to -the [FAIR Data Point software specification](https://specs.fairdatapoint.org) document. +The [FAIR Data Point (FDP)] provides an HTTP API for creating, storing, and serving FAIR (**F**indable, **A**ccessible, **I**nteroperable, **R**eusable) metadata in the form of [RDF]. +The metadata content is generated semi-automatically according to the [FAIR Data Point specification]. ## Usage -More information about FDP, how to deploy it and use it can be found in -the [FDP Deployment and REST API usage Documentation](https://fairdatapoint.readthedocs.io/). - -## Related GitHub Projects - -- [FAIR Data Point Client](https://github.com/FAIRDataTeam/FAIRDataPoint-client) -- [FAIR Data Point E2E Tests](https://github.com/FAIRDataTeam/FAIRDataPoint-E2E-Tests) -- [FAIR Data Point Documentation](https://github.com/FAIRDataTeam/FAIRDataPoint-Docs) -- [OpenRefine Metadata Extension](https://github.com/FAIRDataTeam/OpenRefine-metadata-extension) +More information about the FDP, how to deploy it, and how to use it, can be found in the [FDP documentation]. ### API Documentation -FAIR Data Point API comes with an embedded [OpenAPI documentation using Swagger](https://swagger.io/specification/). The -details of API calls can be found there. It also allows trying out API calls directly. To access the FDP swagger -document please visit the following url via web -browser [localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) (for local deployment) -or `https://your.domain.tld/swagger-ui.html` for your deployment ( -e.g. [app.fairdatapoint.org/swagger-ui.html](https://app.fairdatapoint.org/swagger-ui.html)). More detailed descriptions and examples of these API calls is available in the [Deployment and Usage instructions](https://fairdatapoint.readthedocs.io/) +The FAIR Data Point API also comes with embedded [OpenAPI] documentation based on SwaggerUI. +Each FDP serves its own human friendly API documentation at the path `/swagger-ui.html`, for example, https://app.fairdatapoint.org/swagger-ui.html. +In addition, machine readable API docs (JSON) are available at the path `/v3/api-docs`, for example, https://app.fairdatapoint.org/v3/api-docs. ## Development ### Technology Stack -- **Java** (JDK 21) -- **MongoDB** (4.2) -- **Maven** (3.2.5 or higher) -- **Docker** (19.03.0-ce or higher) - *for building Docker image only* +The FDP runs on the following technology stack and is typically deployed as a Docker container. + +- **Spring-boot** +- **Java** +- **Maven** +- **MongoDB** +- **Docker** (only required for building a Docker image and running the container) ### Build & Run -To run the application, a MongoDB instance is required to be running. To configure the MongoDB with standard -connection (`mongodb://localhost:27017/fdp`), simply instruct Spring Boot to use the `development` profile. Then run: +The FDP requires a MongoDB instance to store its application data, such as user accounts and settings. +This can be achieved by running the official [mongo docker image]. + +To configure the FDP to use MongoDB with standard connection (`mongodb://localhost:27017/fdp`), instruct Spring Boot to use the `development` profile, as follows: ```bash $ mvn spring-boot:run -Dspring-boot.run.profiles=development ``` -Alternatively, create an `application.yml` file in the project root -and [configure the mongodb address](https://fairdatapoint.readthedocs.io/en/latest/deployment/advanced-configuration.html#mongo-db) -, and then run: +Alternatively, create an [application.yml] file in the project root with the desired configuration settings, and run: ```bash $ mvn spring-boot:run @@ -60,46 +51,32 @@ $ mvn spring-boot:run ### Run tests -Run from the root of the project: +Tests can be run, from the root of the project, as follows: ```bash $ mvn test ``` -### Package the application - -Run from the root of the project: - -```bash -$ mvn package -``` - ### Create a Docker image -Run from the root of the project (requires building `jar` file using `mvn package` as shown above): - -```bash -$ docker build -t fairdatapoint:local . -``` - -### Build using Docker - -If you do not have Java and Maven locally, you can build the Docker image using Docker (instead of using locally -built `jar` file): +To build a Docker image, run this from the project root: ```bash -$ docker build -f Dockerfile.build -t fairdatapoint:local . +$ docker build -f Dockerfile -t fairdatapoint:local . ``` ## Security -Most of the `GET` requests are publicly accessible. In contrast, `POST`, `PUT`, `DELETE`, and `PATCH` requests are -mainly secured. We use [JWT Tokens](https://jwt.io/) -and [Bearer Token Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). The -token can be retrieved using `/tokens` endpoint where you send username and password. For details, visit the OpenAPI -documentation. +Most of the API endpoints allow `GET` requests without authentication. +In contrast, `POST`, `PUT`, `DELETE`, and `PATCH` requests typically do require authentication. +We use [JWT Tokens](https://jwt.io/) and [Bearer Token Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). +A token can be obtained by posting username and password to the `/tokens` endpoint. +For more details, visit the FDP OpenAPI documentation at `/swagger-ui.html`. + +By default, the FDP sets up the following *default users*. -**Default users** +>[!WARNING] +>The default users are convenient for local testing, but they *must* be removed, or modified, *before* exposing the FDP to the public internet. - **ADMIN:** - Username: `albert.einstein@example.com` @@ -110,25 +87,47 @@ documentation. ## Contributing -We maintain a [CHANGELOG](CHANGELOG.md), you should also take a look at our [Contributing guidelines](CONTRIBUTING.md) -and [Code of Conduct](CODE_OF_CONDUCT.md). +Interested in contributing to FDP development? +Take a look at our [contribution guidelines](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md). ## Citation -The following paper can be cite as a reference paper for the FAIR Data Point: - - @article{10.1162/dint_a_00160, - author = {Bonino da Silva Santos, Luiz Olavo and Burger, Kees and Kaliyaperumal, Rajaram and Wilkinson, Mark D.}, - title = "{FAIR Data Point: A FAIR-oriented approach for metadata publication}", - journal = {Data Intelligence}, - pages = {1-21}, - year = {2022}, - month = {08}, - issn = {2641-435X}, - doi = {10.1162/dint_a_00160}, - url = {https://doi.org/10.1162/dint\_a\_00160}, - eprint = {https://direct.mit.edu/dint/article-pdf/doi/10.1162/dint\_a\_00160/2038268/dint\_a\_00160.pdf}} +The following paper can be cited as a reference for the FAIR Data Point: + +```bibtex +@article{ + 10.1162/dint_a_00160, + author = {Bonino da Silva Santos, Luiz Olavo and Burger, Kees and Kaliyaperumal, Rajaram and Wilkinson, Mark D.}, + title = "{FAIR Data Point: A FAIR-oriented approach for metadata publication}", + journal = {Data Intelligence}, + pages = {1-21}, + year = {2022}, + month = {08}, + issn = {2641-435X}, + doi = {10.1162/dint_a_00160}, + url = {https://doi.org/10.1162/dint\_a\_00160}, + eprint = {https://direct.mit.edu/dint/article-pdf/doi/10.1162/dint\_a\_00160/2038268/dint\_a\_00160.pdf} +} +``` ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for more details. +This project is licensed under the MIT License - see the [LICENSE] file for more details. + +## Related GitHub Projects + +- [FAIR Data Point Client] +- [FAIR Data Point Documentation] + +[FAIR Data Point (FDP)]: https://www.fairdatapoint.org +[FAIR Data Point Client]: https://github.com/FAIRDataTeam/FAIRDataPoint-client +[FAIR Data Point Documentation]: https://github.com/FAIRDataTeam/FAIRDataPoint-Docs +[FAIR Data Point specification]: https://specs.fairdatapoint.org +[FDP documentation]: https://fairdatapoint.readthedocs.io/ +[OpenAPI]: https://swagger.io/specification/ +[application.yml]: src/main/resources/application.yml +[LICENSE]: LICENSE +[contribution guidelines]: CONTRIBUTING.md +[code of conduct]: CODE_OF_CONDUCT.md +[mongo docker image]: https://hub.docker.com/_/mongo/ +[RDF]: https://www.w3.org/TR/rdf11-primer/